Callbacks
Note: Fusion handles callbacks differently to the other engines. Please see the Fusion Specific Info page on Callbacks for more information.
The Automation API allows you to define an Activity and a WorkItem in a way that makes it possible to gain better control over the execution flow of the WorkItem processing. This is done using a callback mechanism for three different types of events.
The callback events are:
onDemand callback
The onDemand callback allows you to provide additional input data to a WorkItem during the WorkItem execution, when needed.
Using the onDemand callback requires it to be specified in both the Activity and the WorkItem. Also, your AppBundle has to support it: to invoke the onDemand callback, it has to write a specially formatted string to the output and it also has to handle the response in a specific way. A detailed walkthrough named Use onDemand Inputs is provided in the Advanced section of the How-to Guide.
Note: The AutoCAD engine additionally supports onDemand callbacks for a WorkItem’s output as well.
onProgress callback
The onProgress callback allows you to check for the status of a WorkItem execution on a periodic basis. When defined, the Automation service calls the onProgress callback approximately every 30 seconds. The callback body includes the ID of the WorkItem that triggered it.
Note that the Automation service starts calling the onProgress callback only after the WorkItem is taken from the SQS queue and the actual processing of it is started.
It is also possible to invoke the onProgress callback directly from an AppBundle by writing a specially formatted string to trace output. The format is like this:
!ACESAPI:acesHttpOperation("onProgress","","","{<your-call-body-content>}","")
I.e. invoking the onProgress call from your add-in may look like
LogTrace("!ACESAPI:acesHttpOperation({0},\"\",\"\",{1},\"\")",
"onProgress",
"{ \"current-progress\": 30, \"step\": \"apply parameters\" }");
You can use the callback not only to monitor the status of the execution, but also to cancel the job if needed. To cancel a running job, send an HTTP 205 Reset Content response to the received onProgress callback. You should not use DELETE workitems/:id to cancel a WorkItem that uses the onProgress callback once this WorkItem is picked from the SQS queue for execution.
onComplete callback
The onComplete callback lets you know when the WorkItem execution has ended without the need to actively check for the WorkItem status periodically. The callback body includes the ID of the WorkItem that triggered it, along with the WorkItem status and the URL for the WorkItem report. Time and other data are also included in the stats section, same as in the response to GET workitems/:id call.
Example
In order to use both the onProgress and onComplete callbacks, it is only required to include them in the WorkItem’s “arguments” section as shown here:
curl -X POST \
https://developer.api.autodesk.com/da/us-east/v3/workitems \
...
-d '{
"activityId": ""QDsYgPEnrk7aPsaP6VvmEXPBmwYAZcMx.timeSleep7x10s+prod",
"arguments": {
...
"onProgress": {
"verb": "post",
"url": "https://onprogress.free.beeceptor.com"
},
"onComplete": {
"verb": "post",
"url": "https://oncomplete.free.beeceptor.com"
}
}
}'
The activityId has to be a fully qualified ID, see Aliases and IDs section.
The URLs in the onProgress and onComplete sections should point to your web server endpoints dedicated to handling these callbacks.
Sample request body for the default (timer-run) onProgress callback:
{
"id":"0d891fa9da8f4dff8ecf248cca81c9d3"
}
Sample request body for the custom (as shown in the above onProgress custom call example) onProgress callback:
{
"id":"0d891fa9da8f4dff8ecf248cca81c9d3",
"progress": {
"current-progress": 30,
"step": "apply parameters"
}
}
Sample request body for the onComplete callback:
{
"status": "failedInstructions",
"reportUrl": "https://dasprod-store.s3.us-east-1.amazonaws.com/workItem/QDsYgPEnrk7aPsaP6VvmEXPBmwYAZcMx/0d891fa9da8f4dff8ecf248cca81c9d3/report.txt?...",
"stats": {
"timeQueued": "2019-07-16T08:22:44.2532481Z",
"timeDownloadStarted": "2019-07-16T08:22:45.9190287Z",
"timeInstructionsStarted": "2019-07-16T08:22:46.6863037Z",
"timeInstructionsEnded": "2019-07-16T08:24:00.421216Z",
"timeUploadEnded": "2019-07-16T08:24:00.421216Z",
"bytesDownloaded": 1425408
},
"id": "0d891fa9da8f4dff8ecf248cca81c9d3"
}
(Beta) The onComplete body also includes the following, as in GET workitems/:id:
- For a Revit WorkItem submitted with
memoryGborgpu, those values, and withmemoryGbthe approximate peak memory,stats.megabytesPeakRam. - For a WorkItem that ran on a priority queue,
"priority": "P1". It is not included for any other WorkItem.
Engine support for callbacks
Engine |
onDemand (input) |
onDemand (output) |
onProgress |
onComplete |
|---|---|---|---|---|
| AutoCAD | Yes | Yes | Yes | Yes |
| 3ds Max | Yes | No | Yes | Yes |
| Inventor | Yes | No | Yes | Yes |
| Revit | Yes | No | Yes | Yes |
| Fusion | ||||
Note: Use onProgress/onDemand (input only) synchronously in the add-in code. For example, calling Console.ReadLine() immediately after Console.WriteLine(“!ACESAPI:acesHttpOperation(onProgress,,,<your-callback-body-content>,)”). If this contract is violated, you may get inconsistent results for callbacks.