We’re pleased to inform you that Data Connector API now supports extracting activities data!
Accessing to activities data through API has been a highly demanded feature. With the new enhancement to the Data Connector API, you now have a programmatic way to extract data for activities, for example, from Document Management or Docs, Issues, and Account Admin. Data Connector API is compatible with Autodesk Construction Cloud (ACC) unified products and BIM 360. You can find information about Data Connector feature in product help.
Changes made to the endpoints to support activities are simple:
- “activities” is added to the list services for servicesGroups field in POST/PATCH requests.
- Two optional fields, startDate and endData, are added in POST/PATCH requests to specify a date range to extract. Currently, only activities respects the date range.
Below shows a sample usage of the above fields:
curl -v 'https://developer.api.autodesk.com/data-connector/v1/accounts/:accountId/requests' \
-X 'POST' \
-H 'Authorization: Bearer AuIPTf4KYLTYGVnOHQ0cuolwCW2a' \
-H 'Content-Type: application/json' \
-d '{
"description": "My Project Activities Data Extract",
"isActive": true,
"scheduleInterval": "ONE_TIME",
"effectiveFrom": "2020-11-06T19:09:40.106Z",
"effectiveTo": "2020-11-12T19:09:40.106Z",
"serviceGroups": "[\"activities\"]",
"projectId": "ffffffff-1f51-4b26-a6b7-6ac0639cb138",
"startDate": "2023-06-01T00:00:00.000Z",
"endDate": "2023-06-30T00:00:00.000Z"
}'
Notice serviceGroups, startDate, and endDate in the above code. In addition, the projectId above can be omitted when wanting to extract activity data from the Account level.
Although the usage of the additional fields is simple, due to the fact that the amount of data could potentially be very large, there are restrictions when extracting activities data:
- The user needs to specify the extraction date range by startDate and endDate within a 31-day window.
- The API supports extracting historical activity data for the last 12 months.
- By default, when both startDate and endDate are omitted, users get activities for the last 24 hours (UTC YESTERDAY) from the time of the extract execution. For example, if the user extract runs at “2023-04-18 10:00:00”, the user will get the activities greater than or equal to 2023-04-17 00:00:00 and less than 2023-04-18 00:00:00.
- If the extraction date range exceeds the 31-day window, Data Connector API will use the default date range (UTC YESTERDAY) for activities extraction.
- If you provide only startDate or endDate (but not both), Data Connector uses the single date for both startDate and endDate.
The image below illustrates behavior and restrictions mentioned above:
The following Q&A may answer some of your questions:
Q1. Why do I get an empty activities extraction result of Data Connector API?
For example, I can see one Docs activity of uploading an RVT file to Docs a few minutes ago in this project, but if I re-run the same extraction after one more day, I can get this activity extracted in the "activities_docs_activities.csv."
A1. Please check if the activity data is within the default date range (i.e., UTC YESTERDAY). Data syncing from service modules to the Data Connector service will take at least 20 minutes, so please retry 20 minutes later after uploading the file to the Docs service.
Q2. Do we have more information about activities verbs?
A2. You may find reading activities data is more complex than other data types due to the variable nature of payloads associated with the various “activities verbs”. An activities verb defines the particular activities in ACC/BIM 360 service modules, and different service modules use different activities verbs. You can find the detailed explanations in README.html, which comes with the extraction dataset. We suggest taking a look at it first when working with Data Connecter API and activities.
Q3. Why can't I download the extracted files (e.g. CSV) anymore?
A3. The files generated from the data extraction can be downloaded up to 30 days after extraction. You can find information about Data Connector feature in product help.
Additional Enhancements: Sorts, Filter, and Last Download
In addition to the activities support, you can also find the following enhancements in the recent release:
- sortFields is added as an optional request parameter to GET requests and GET jobs endpoints. You can use this to sort parameters in the response.
- fielter[field_to_filter] is added as an optional request parameter to GET requests and GET jobs. You can use this to filter your response by specific values and dates.
- Two fields, lastDownloadedBy and lastDownloadedAt, are added to GET requests/:requestId/jobs, GET jobs, and GET jobs/:jobId. You can check these values to determine who last downloaded, and date and time for the ZIP or individual file in the extraction.
If you haven’t used Data Connector API before, you may find the following blog posts useful:
If you have any questions, feel free to contact us through our APS support channel.