Field Guide
As described in the API Basics page, there are four primary entities in the Automation API for executing custom programs or running scripts on input files:
- Activity
- WorkItem
- AppBundle
- Engine
Entity Relationships
- WorkItems reference exactly one Activity.
- Activities reference exactly one Engine.
- Activities reference one or more AppBundles. Note: Inventor Activities may only reference one AppBundle.
- AppBundles reference zero or more other AppBundles. Note: Inventor AppBundles may not reference any other AppBundles.
- AppBundles reference exactly one Engine.
Activity
An Activity is an action that can be executed within the core engine (AutoCAD, 3dsMax, Inventor or Fusion). For example, this might be plotting a DWG to PDF, updating the CAD standards in a drawing file or modifying the assembly based on iLogic parameters in Inventor.
Examples
AutoCAD
{
"commandLine": [
"$(engine.path)\\accoreconsole.exe /i $(args[HostDwg].path) /al \"$(appbundles[Publish2View22].path)\" /s \"$(settings[script].path)\""
],
"parameters": {
"HostDwg": {
"verb": "get",
"description": "Host drawing",
"localName": "$(EmptyDwg)"
},
"Result": {
"zip": true,
"verb": "post",
"description": "Results",
"localName": "result"
}
},
"engine": "Autodesk.AutoCAD+22",
"appbundles": [
"AutoCAD.Publish2View22+prod"
],
"settings": {
"script": "(command \"_prepareforpropertyextraction\" \"index.json\")\n(command \"_indexextractor\" \"index.json\")\n(command \"_publishtosvf\" \"./output/result.svf\")\n(command \"_createbubblepackage\" \"./output\" \"./result\" \"\" \"\")\n"
},
"description": "AutoCAD translation sample generating SVF via core console.",
"version": 1,
"id": "AutoCAD.AcSvfPublish+prod"
}
3ds Max
{
"id": "ExportToFBX",
"commandLine": "$(engine.path)/3dsmaxbatch.exe -sceneFile \"$(args[InputFile].path)\" \"$(settings[script].path)\"",
"description": "Export a single max file to FBX",
"appbundles": [
],
"engine" : "Autodesk.3dsMax+2021",
"parameters": {
"InputFile" : {
"zip": false,
"description": "Input 3ds Max file",
"ondemand": false,
"required": true,
"verb": "get",
"localName": "input.max"
},
"OutputFile": {
"zip": false,
"ondemand": false,
"verb": "put",
"description": "Output FBX file",
"required": true,
"localName": "output.fbx"
}
},
"settings": {
"script": "exportFile (sysInfo.currentdir + \"/output.fbx\") #noPrompt using:FBXEXP"
}
}
Inventor
{
"commandLine": [
"$(engine.path)\\InventorCoreConsole.exe /i \"$(args[InventorDoc].path)\" /al \"$(appbundles[ChangeParams].path)\" \"$(args[InventorParams].path)\""
],
"parameters": {
"InventorDoc": {
"verb": "get",
"description": "IPT file or ZIP with assembly to process"
},
"InventorParams": {
"verb": "get",
"description": "JSON with changed Inventor parameters",
"localName": "params.json"
},
"OutputIpt": {
"zip": false,
"ondemand": false,
"optional": true,
"verb": "put",
"description": "IPT with the changed parameters",
"localName": "Result.ipt"
},
"OutputIam": {
"zip": false,
"ondemand": false,
"optional": true,
"verb": "put",
"description": "ZIP with assembly with the changed parameters",
"localName": "Result.zip"
}
},
"engine": "Autodesk.Inventor+23",
"appbundles": [
"Inventor.ChangeParams+prod"
],
"description": "Change parameters of a part or an assembly (Inventor 2019).",
"id": "ChangeParams"
}
Revit
{
"id": "CountItActivity",
"commandLine": [ "$(engine.path)\\\\revitcoreconsole.exe /i \"$(args[rvtFile].path)\" /al \"$(appbundles[CountItApp].path)\"" ],
"parameters": {
"rvtFile": {
"zip": false,
"ondemand": false,
"verb": "get",
"description": "Input Revit model",
"required": true,
"localName": "$(rvtFile)"
},
"countItParams": {
"zip": false,
"ondemand": false,
"verb": "get",
"description": "CountIt parameters",
"required": false,
"localName": "CountItParams.json"
},
"result": {
"zip": false,
"ondemand": false,
"verb": "put",
"description": "Results",
"required": true,
"localName": "result.txt"
}
},
"engine": "Autodesk.Revit+2018",
"appbundles": [ "YourNickname.CountItApp+test" ],
"description": "Count and output elements from Revit file."
}
Fusion
{
"id": "{{activityName}}",
"engine": "{{engine}}",
"commandline": [],
"parameters": {
"TaskParameters": {
"verb": "read",
"description": "the parameters for the script",
"required": false
},
"PersonalAccessToken": {
"verb": "read",
"description": "the personal access token to use",
"required": true
}
},
"appbundles": [
"{{dasAppBundleId}}+my_working_version"
],
"settings": {},
"description": ""
}
WorkItem
A WorkItem is a specification of the processing job for an Activity, and it is submitted to and executed by the core engine.
Note that a WorkItem cannot be modified after it has been created.
Request Example
{
"activityId": "dqRuDWmG904xamaQi6zWLFOm7snzBOaR.InventorActivity_MaxOnDemand_x1+InvActivityNickName_MaxOnDemand_x1",
"arguments": {
"InventorDoc": {
"url": "https://inventor-io-samples.s3.us-west-2.amazonaws.com/V3_Front_End_Limit/MaxOnDemand/Memory_Inventor.zip",
"zip": true,
"pathInZip": "1100_10001080329_IAM_001.iam",
"localName": "Assembly"
},
"InventorParams": {
"url": "https://inventor-io-samples.s3.us-west-2.amazonaws.com/V3_Front_End_Limit/MaxOnDemand/changeParameters.json"
},
"OutputIam": {
"url": "https://inventor-io-samples.s3.us-west-2.amazonaws.com/V3_Front_End_Limit/MaxOnDemand/Result.zip?AWSAccessKeyId=AKIAIMGS3VXBFI36OKEQ&Expires=1577791320&Signature=vnuzDeDtIaLXm4%2FL5YS5j4dPDu0%3D",
"verb": "put"
}
}
}
Response Example
{
"status": "pending",
"reportUrl": "https://dasprod-store.s3.us-east-1.amazonaws.com/workItem/sdfsdfsfWmG904xamaQi6gsdgfdsgsdsgfzWLFOm7snzBOaR/sdgfdsgdfgd5988036d7f8ef36a3/report.txt...",
"stats": {
"timeQueued": "2018-08-07T12:23:49.5379221Z"
},
"id": "dd1c37bf239b4695988036d7f8ef36a3"
}
AppBundle
An AppPackage is a module that is used by an Activity in order to perform a particular action.
Example
{
"engine": "Autodesk.AutoCAD+22",
"description": "App for Model&View (Omega)",
"version": 1,
"id": "AutoCAD.Publish2View22+prod"
}
Engine
An Engine is what executes a WorkItem job and processes the actions specified by an Activity.
Example
{
"productVersion": "23.0",
"description": "AutoCAD 2019 (Pi) Core Engine",
"version": 2,
"id": "Autodesk.AutoCAD+23"
}
Variable expansion
A variable $(workitem.id) can be used in the payload. The following fields support variable expansion:
- workitems.arguments[n].url
- workitems.arguments[n].headers
- workitems.arguments[n].value
- activities.commandLine[n]
Examples
{
"activityId": "owner.name+alias",
"arguments": {
"result": {
"verb": "put",
"url": "https://myProvider/$(workitem.id)/File.ext"
}
}
}
{
"activityId": "owner.name+alias",
"arguments": {
"result": {
"verb": "post",
"url": "https://myProvider/results",
"headers": {
"myWorkitemId": "$(workitem.id)"
}
}
}
}
Command lines
Note: Use of the command line is not support with the Fusion engine.
The command line contains variables of the form $(collection[index].property) where collection may have the following values:
- args or settings refers to the arguments of the workitem or settings of the activity respectively, index must be the name of the argument/setting, property can be the following:
1.1. path: full path to the file system entry (file or folder) for the argument/setting.
Note that this may be different than the localName for input arguments when the Content - Disposition header value is provided by the server. It is also different from localName when zip`=`true, in this case path will be determined like this:
- if the zip file contains a manifest (etransmit) then path will point to ‘main file’ designated by the manifest.
- if the zip file contains no manifest then path will point to what’s designated by pathInZip.
1.2. value: string value of the argument/setting
- appbundles refers to a referenced app, index must be the id of the appbundle, property can be the following:
2.1. path: full path to the folder where the appbundle is executing from.
- engine refers to a referenced engine, ‘index’ should not be used, property can be the following:
3.1. path: full path to the folder where the engine is executing from.
- Examples:
$(engine.path)/AcCoreConsole.exe /i “$(args[hostDwg].path)” /s $(setting[script].path)
“$(appbundles[Autodesk.ShardingApp].path)/AcReadEx.exe” /i “$(args[hostDwg].path)” /retries $(args[retries].value))
Note: args and appbundles must be provided between quotes.
Expanded WorkItem Payload
The working directory of the executable running in the context of the service will also contain a <workitem.id>_Job.das file. Appbundles can use this information to get to the details of the submitted work.
For example, you can use the following C# code to read this the contents of this file in your appbundle code:
var json = File.ReadAllText($”{Environment.ExpandEnvironmentVariables(“%DAS_WORKITEM_ID%”)}_job.das”);
This file contents are encoded as JSON. The following attributes will be present on the root object:
| Id string | Id of the WorkItem |
| ActivityId string | Id of referenced Activity |
| EngineId string | Id of referenced Engine |
| Apps array of strings | Ids of referenced Appbundles |
| BoundArguments dictionary of objects | This attribute presents a merged view of the Actvitity.parameters and WorkItem.arguments |
| Settings dictionary of objects | Same as Activity.settings |
| CommandLine array of strings | Same as Activity.commandLine |
| Quotas dictionary of integers | Some of the quotas applied to this workitem. Please note that this is not a complete list. |
