ACC Cost Exchange Sample

Description

This sample demonstrates exchanging properties of Budget, Contract, Cost item and Change Order between cost module and .CSV file using Cost Management API. It includes 3 main tasks:

1. Display Cost properties either in Raw data and Human readable form.
2. Export Cost properties either in Raw data and Human readable form to a CSV file.
3. Import Cost properties from a locally stored CSV file(based on Raw data).
4. The sample supported the Cost Webhook events, you can register/unregister cost webhook events by right clicking on the project node, if the cost webhook events are registered, the tab name will be appended with * (BUDGET* for example) whenever the related cost object is created/updated/deleted.

Thumbnail

Demonstration

Web App Setup

Prerequisites

1. APS Account: Learn how to create an APS Account, activate subscription and create an app at this tutorial.
2. ACC|BIM360 Account: must be Account Admin to add the app integration. Learn about provisioning.
3. Cost Management: Create ACC|BIM360 project, activate Cost Management module, setup project to create Budget Code Template for Cost Management according to the guide
4. Node.js: basic knowledge with Node.js.
5. JavaScript basic knowledge with jQuery

For using this sample, you need an Autodesk developer credentials. Visit the Autodesk Developer Portal, sign up for an account, then create an app. For this new app, use http://localhost:3000/api/aps/callback/oauth as Callback URL. Finally take note of the Client ID and Client Secret.

Running locally

Install NodeJS, version 14 or newer.

Clone this project or download it (this nodejs branch only). It's recommended to install GitHub desktop. To clone it via command line, use the following (Terminal on MacOSX/Linux, Git Shell on Windows):

git clone https://github.com/autodesk-platform-services/aps-acc-cost-exchange

Install the required packages using npm install.

Environment variables

Set the enviroment variables with your client ID & secret and finally start it. Via command line, navigate to the folder where this repository was cloned and use the following:

Mac OSX/Linux (Terminal)

npm install
export APS_CLIENT_ID=<<YOUR CLIENT ID FROM DEVELOPER PORTAL>>
export APS_CLIENT_SECRET=<<YOUR CLIENT SECRET>>
export APS_CALLBACK_URL=<<YOUR CALLBACK URL>>
export APS_CALLBACK_COST_EVENTS=<<YOUR CALLBACK COST EVENTS URL>>

npm start

Windows (use Node.js command line from Start menu)

npm install
set APS_CLIENT_ID=<<YOUR CLIENT ID FROM DEVELOPER PORTAL>>
set APS_CLIENT_SECRET=<<YOUR CLIENT SECRET>>
set APS_CALLBACK_URL=<<YOUR CALLBACK URL>>
set APS_CALLBACK_COST_EVENTS=<<YOUR CALLBACK COST EVENTS URL>>

npm start

Using the app

Open the browser: http://localhost:3000.

Please watch the Video for the detail setup and usage, or follow the steps:

• Setup the app before using the App

1. Make sure to Create ACC|BIM360 project, activate Cost Management module, setup project for Cost Management.

• Operate with App after setup

1. Select a project and display Cost properties either in Raw data and Human readable form.
2. Click Export button to export Cost properties either in Raw data and Human readable form to a CSV file.
3. Click Import button to update Cost properties from a locally stored CSV file(based on Raw data).
4. Right click on the project node, register/unregister all cost webhook events for this project.
5. If the cost webhook events are registered, you will see the tab name be appended with * (BUDGET* for example) whenever the related cost object is created/updated/deleted, you can refresh to check the latest info.

Limitation

• Cost Management module needs to be activated before using this app, due to the current limitation of Cost API, user needs to activate & setup cost project manually. Please check Create ACC|BIM360 project, activate Cost Management module, setup project for Cost Management for details.

Known issues

1. The 'scopeOfWork' property contain rich text which may includes '\n' and ',', but the 2 characters are reserved for special usage while parsing CSV file, to avoid the issue, I use the following 2 characters as replacement for 'scopeOfWork' property.

        const Enter_Replacement = '\xfe';
        const Comma_Replacement = '\xfd';

Tips & Tricks

1. Not all the properties could be updated, only these marked as Editable are supported.
2. To import properties from CSV file, the suggested way is to export a CSV file of raw data first, update the editable properties within the file, then import it back to cost module.

Troubleshooting

1. Cannot see my ACC projects: Make sure to provision the APS App Client ID within the ACC Account, learn more here. This requires the Account Admin permission.

Further Reading

Document:

• Data Management API
• BIM360 API and App Provisioning
• Cost Management API
• Create ACC|BIM360 project, activate Cost Management module, setup project for Cost Management

Tutorials:

• View ACC Models

Blogs:

• APS Blog
• Field of View, a BIM focused blog

License

This sample is licensed under the terms of the MIT License. Please see the LICENSE file for full details.

Written by

Zhong Wu @johnonsoftware, Autodesk Partner Development