https://github.com/autodesk-platform-services/aps-acc-cost-exchange
ACC Cost Exchange Sample: A sample to demonstrate how to exchange data between Cost Management and CSV file
https://github.com/autodesk-platform-services/aps-acc-cost-exchange
autodesk-construction-cloud bim360 cost-management nodejs sample
Last synced: 7 months ago
JSON representation
ACC Cost Exchange Sample: A sample to demonstrate how to exchange data between Cost Management and CSV file
- Host: GitHub
- URL: https://github.com/autodesk-platform-services/aps-acc-cost-exchange
- Owner: autodesk-platform-services
- License: mit
- Created: 2022-12-07T08:49:48.000Z (almost 3 years ago)
- Default Branch: master
- Last Pushed: 2024-01-19T12:29:13.000Z (over 1 year ago)
- Last Synced: 2025-02-06T16:57:39.824Z (8 months ago)
- Topics: autodesk-construction-cloud, bim360, cost-management, nodejs, sample
- Language: JavaScript
- Homepage:
- Size: 1.71 MB
- Stars: 2
- Watchers: 4
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# ACC Cost Exchange Sample
[](https://nodejs.org/)
[](https://www.npmjs.com/)
[](http://developer.autodesk.com/)
[](http://developer.autodesk.com/)
[](http://developer.autodesk.com/)
[](http://developer.autodesk.com/)
[](http://developer.autodesk.com/)
[](http://developer.autodesk.com/)
[](http://opensource.org/licenses/MIT)
[](http://developer.autodesk.com/)
## 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
[](https://youtu.be/X6mFX_yqhTI "Display and exchange cost information with CSV file")
# Web App Setup
## Prerequisites
1. **APS Account**: Learn how to create an APS Account, activate subscription and create an app at [this tutorial](http://aps.autodesk.com/tutorials).
2. **ACC|BIM360 Account**: must be Account Admin to add the app integration. [Learn about provisioning](https://aps.autodesk.com/blog/bim-360-docs-provisioning-forge-apps).
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](https://help.autodesk.com/view/BIM360D/ENU/?guid=BIM360D_Cost_Management_getting_started_with_cost_management_html)
4. **Node.js**: basic knowledge with [**Node.js**](https://nodejs.org/en/).
5. **JavaScript** basic knowledge with **jQuery**
For using this sample, you need an Autodesk developer credentials. Visit the [Autodesk Developer Portal](https://developer.autodesk.com), sign up for an account, then [create an app](https://developer.autodesk.com/myapps/create). 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](https://nodejs.org), version 14 or newer.
Clone this project or download it (this `nodejs` branch only). It's recommended to install [GitHub desktop](https://desktop.github.com/). 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=<>
export APS_CLIENT_SECRET=<>
export APS_CALLBACK_URL=<>
export APS_CALLBACK_COST_EVENTS=<>
npm start
Windows (use **Node.js command line** from Start menu)
npm install
set APS_CLIENT_ID=<>
set APS_CLIENT_SECRET=<>
set APS_CALLBACK_URL=<>
set APS_CALLBACK_COST_EVENTS=<>
npm start
## Using the app
Open the browser: [http://localhost:3000](http://localhost:3000).
**Please watch the [Video](https://youtu.be/X6mFX_yqhTI) 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](https://help.autodesk.com/view/BIM360D/ENU/?guid=BIM360D_Cost_Management_getting_started_with_cost_management_html).
- **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](https://help.autodesk.com/view/BIM360D/ENU/?guid=BIM360D_Cost_Management_getting_started_with_cost_management_html) 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.
```js
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](https://aps.autodesk.com/blog/bim-360-docs-provisioning-forge-apps). This requires the Account Admin permission.
## Further Reading
**Document**:
- [Data Management API](https://developer.autodesk.com/en/docs/data/v2/overview/)
- [BIM360 API](https://developer.autodesk.com/en/docs/bim360/v1/overview/) and [App Provisioning](https://aps.autodesk.com/blog/bim-360-docs-provisioning-forge-apps)
- [Cost Management API](https://aps.autodesk.com/en/docs/bim360/v1/overview/field-guide/cost-management/)
- [Create ACC|BIM360 project, activate Cost Management module, setup project for Cost Management](https://help.autodesk.com/view/BIM360D/ENU/?guid=BIM360D_Cost_Management_getting_started_with_cost_management_html)
**Tutorials**:
- [View ACC Models](https://tutorials.autodesk.io/tutorials/hubs-browser/)
**Blogs**:
- [APS Blog](https://aps.autodesk.com/categories/bim-360-api)
- [Field of View](https://fieldofviewblog.wordpress.com/), a BIM focused blog
## License
This sample is licensed under the terms of the [MIT License](http://opensource.org/licenses/MIT). Please see the [LICENSE](LICENSE) file for full details.
## Written by
Zhong Wu [@johnonsoftware](https://twitter.com/johnonsoftware), [Autodesk Partner Development](http://aps.autodesk.com)