Callbacks
Note: Design Automation for Fusion handles callbacks differently to the other engines. Please see the Fusion Specific Info page section for more information.
Design Automation allows the user 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 the user to provide additional input data to the 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 OnDemand input walkthrough is provided as part of Design Automation documentation.
Note: Design Automation for AutoCAD also supports OnDemand callbacks for a WorkItem’s output.
OnProgress callback
The OnProgress callback allows the user to check for the status of a WorkItem execution on a periodic basis. When defined, Design Automation calls the OnProgress callback approximatelly every 30 seconds. The callback body includes the id of the WorkItem for which it has been sent.
Note that Design Automation 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\" }");
The user can use the callback not only to monitor the status of the execution, but also to cancel the job if needed. To do so, just send an HTTP 205 Reset Content as a response to the received OnProgress callback. THe user 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 the user 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 for which it has been sent, together with the WorkItem status and the url for the WorkItem report. Also, time and other data are 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 the `Aliases and IDs section</en/docs/design-automation/v3/developers_guide/aliases-and-ids/>`_ of the Design Automation documentation for more. The urls in the onProgress and onComplete sections should point to the user’s 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"
}
Engine support for callbacks
Currently, all engines support the onDemand (input only), onProgress and onComplete callbacks.
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.