Field Guide
As described in the API Basics page, there are four primary entities in the Design Automation API for executing custom programs or running scripts on drawing (DWG) files:
- Activity
- WorkItem
- AppPackage
- Engine
Entity Relationships
- WorkItems reference exactly 1 Activity.
- Activities reference 1 or more Engines.
- Activities reference 0 or more AppPackages.
- AppPackages reference 0 or more other AppPackage.
- AppPackages reference 1 or more Engines.
Activity
An Activity is an action that can be executed within the AutoCAD core engine. For example, this might be plotting a DWG to PDF or update the CAD standards in a drawing file.
Schema
Expand all
| AppPackages array: string | IDs of the AppPackages to reference
If a custom Activity uses only native AutoCAD commands, this attribute should be empty.
|
| HostApplication string | Name of the application to execute a specified WorkItem
By default, this field should be empty. When the field is empty, the AutoCAD core engine (accoreconsole.exe) is used. A client can specify a RealDWG host application to carry out a WorkItem. Host applications are typically submitted via custom AppPackages.
|
| RequiredEngineVersion enum: string | Version of the AutoCAD core engine to execute the Activity. Possible values:
20.1, 21.0, 22.0.Note: Use the
ACADVER system variable within your local install of the AutoCAD program to see which version you are using locally. |
| Parameters object | Input and output parameters that map the names of actual drawings to the drawing names specified in the
Instruction objectParameters is a container object that contains two sub-containers: InputParameters and OutputParameters. Each container is an array of Parameter objects. A Parameter object is closely related to an Argument object in a WorkItem that defines the general input
and output setup of a WorkItem.
For example, if an Activity specifies an input Parameter with a name of “MyParameter” and it’s not optional, then any WorkItem that targets this Activity has to have an input Argument with the same name.
|
| InputParameters object | Array of input Argument objects
|
| Name string | Name of an input Argument object; must be unique within this InputParameters array
|
| LocalFileName string | File name for a locally saved WorkItem input Argument after the resource has been downloaded
|
| Optional bool | Specifies whether an input Argument can be missing
If the value is
true, the missing Argument with the same name of this Parameter is allowed. |
| OutputParameters object | Array of output Argument objects
|
| Name string | Name of an output Argument object; must be unique within this OutputParameters array
|
| LocalFileName string | Name of a locally available file that the Publish process is looking for to upload for this output Argument
|
| Optional bool | Specifies whether an output Argument can be missing
If the value is
true, the missing Argument with the same name of this Parameter is allowed. |
| Instruction object | Describes the actions to be taken
|
| CommandLineParameters string | Additional command line parameters that are passed from the service worker to the new session of the AutoCAD core engine
|
| Script string | Contents that the service worker uses to create an AutoCAD script file locally for the AutoCAD core engine to execute
|
| AllowedChildProcesses array: object | Child processes that will be spawned by the Activity
Note: Any spawned child processes not specified here are disabled.
|
| IsPublic bool | Specifies whether the Activity can be publicly targeted
A public Activity can be used by clients outside of your account.
Note: Only one Activity with the same “Id” (or name) can be public.
|
| Version int | Version number of the Activity
|
| Timestamp datetime: ISO 8601 | Timestamp of the last modification,
YYYY-MM-DDThh:mm:ss.ssZ format; read-onlyNote: This attribute is automatically set by the server and cannot be specified in API requests.
|
| Description string | Additional details about the Activity; optional
|
| Id string | Name of the Activity
The name is used to associate the Activity to a WorkItem. The name of the Activity must be assigned to the WorkItem’s ActivityId attribute.
|
Example
{
"@odata.context": "https://developer.api.autodesk.com/autocad.io/us-east/v2/$metadata#Activities/$entity",
"AppPackages": [],
"HostApplication": "",
"RequiredEngineVersion": "22.0",
"Parameters": {
"InputParameters": [
{
"Name": "HostDwg",
"LocalFileName": "$(HostDwg)",
"Optional": null
}
],
"OutputParameters": [
{
"Name": "Result",
"LocalFileName": "result.pdf",
"Optional": null
}
]
},
"Instruction": {
"CommandLineParameters": "-suppressGraphics",
"Script": "_tilemode 0 -export _pdf _all result.pdf\n"
},
"AllowedChildProcesses": [],
"IsPublic": false,
"Version": 1,
"Timestamp": "2015-09-18T18:46:29.442Z",
"Description": "",
"Id": "PlotToPDF"
}
Show More
WorkItem
A WorkItem is a specification of the processing job for an Activity, and it is submitted to and executed by the AutoCAD core engine.
Note that a WorkItem cannot be modified after it has been created.
Schema
Expand all
| ActivityId string | Activity to be executed
The value must match the
Id attribute of the Activity object. |
| Arguments object | Defines references to input and output arguments
An Argument is a container of two sub-containers: InputArguments and OutputArguments.
|
| InputArguments object | An array of Argument objects
Each Argument object defines a set of input parameters that the service uses to prepare a logic “input” item (drawing, supporting file, script file, ...) along with specifying where and how to get the input.
|
| Resource string: URL | Specifies the location of the resource; the value is generally a URL to download
The URL needs to be pre-signed or you have to provide the Authorization header with a valid token via Headers.
|
| Name string | Unique name of the input argument; must be unique in this InputArguments array
Note: The special input argument named “$(HostDwg)” instructs the service to treat the downloaded resource of the argument as the host drawing in the AutoCAD core engine session.
|
| Headers array: string | An array of “Name” - “Value” pairings that will be applied as HTTP request headers when the service tries to retrieve the input for a WorkItem.
For example, if you specify
{"Name":"Authorization", "Value":"Bearer xxxxxyyyyyzzz"}, the GET request sends Authorization="Bearer xxxxxyyyyyzzz" to the HTTP header. |
| ResourceKind enum: string | Specifies the kind of resource used; when left empty “Simple” is used
Simple: Single remote resource is downloaded as-is; no further unpacking is performed.EtransmitPackage: Single remote resource is an AutoCAD eTransmit package. After the resource is downloaded locally, the contents are unpacked.RemoteFileResource: A cluster of remote resources, described as a RemoteFileResource object with relationships between these resources. The service walks-through the relationship graph and downloads all the resources described.ZipPackage: Remote resource is a single compressed file. After the resource is downloaded locally, the contents are unpacked to a working folder.Embedded: The “Resource” attribute is an in-line resource that conforms with the Data URI scheme. When such a resource is encountered, the file identified by the Resource field is downloaded locally. The Resource field should be of the form
data:[<media-type>][;base64],<data>, and at present <media-type> must be application/json.Variadic: A partial resource to be completed on use. The Resource attribute is a base URI for one or more delay-downloaded resources when access is required, typically from within the underlying application (AutoCAD core engine).
When access is requested, the application supplies missing URI fragments and/or query strings. |
| StorageProvider string | Type of storage in which the input resource come from; can be left empty
Generic is currently the only valid value. |
| HttpVerb enum: string | HTTP operation for this input argument; valid values are
GET or HEAD |
| OutputArguments object | An array of Argument objects that represent the output of the WorkItem after execution
Each output item is typically uploaded to the location specified by the Resource field.
|
| Resource string: URL | URL to publish a given output argument
|
| Name string | Unique name of the output argument; must be unique in this OutputArguments array
|
| Headers array: string | An array of “Name” - “Value” pairings that defines the HTTP header to use when publishing this output arguments.
|
| ResourceKind enum: string | Specifies the kind of resource to be used; when left empty “Simple” is used
Simple: Single remote resource is downloaded as-is; no further unpacking is performed.EtransmitPackage: Single remote resource is an AutoCAD eTransmit package. After the resource is downloaded locally, the contents are unpacked.RemoteFileResource: A cluster of remote resources, described as a RemoteFileResource object with relationships between these resources. The service walks-through the relationship graph and downloads all the resources described.ZipPackage: Remote resource is a single compressed file. After the resource is downloaded locally, the contents are unpacked to a working folder.Embedded: The “Resource” attribute is an in-line resource that conforms with the Data URI scheme. When such a resource is encountered, the file identified by the Resource field is downloaded locally. The Resource field should be of the form:
data:[<media-type>][;base64],<data>, and at present <media-type> must be application/json.Variadic: A partial resource to be completed on-use. The Resource attribute is a base URI for one or more delay-downloaded resources when access is required, typically from within the underlying application (AutoCAD core engine).When access is requested, the application supplies missing URI fragments and/or query strings.
|
| StorageProvider string | Type of storage to use for output; can be left empty
Generic is currently the only valid value. |
| HttpVerb enum: string | HTTP operation for this output argument; valid values are
PUT or POST |
| Status enum: string | Result of the executed task
FailedEnvironmentSetup (-5): Indicates that the required Engine cannot be installedFailedUpload (-4): Indicates that any of the outputs have failed to uploadFailedMissingOutput (-3): Indicates when any of the outputs are missing after the AcCoreConsole.exe has successfully returnedFailedExecution (-2): Indicates that the AcCoreConsole.exe exited with a non-zero exit codeThis includes the following cases:
1. Timeout; exit code is passed to Kill(<exitcode>)
2. Crash; exit code is non-zero
3. Input drawing fails to open; produces various non-zero exit codes
FailedDownload (-1): Indicates that any of the inputs have failed to downloadPending (0): Indicates that the WorkItem is still in the queue, no worker has started processing the WorkItemInProgress (1): Indicates that the WorkItem is being processedSucceeded (256): Indicates that execution of the WorkItem was successful |
| StatusDetails object | Wrapper object that contains a S3 item path for the internal reporting of the WorkItem
|
| Report string: URL | URL to a downloadable report about the executed task
|
| AvailabilityZone string | Geographical region in which the WorkItem is executed
Note: This attribute is currently ignored.
|
| TimeQueued datetime: ISO 8601 | Time when the request entered the queue of the service; read-only
Note: This attribute is automatically set by the server and cannot be specified in API requests.
|
| TimeInputTransferStarted datetime: ISO 8601 | Time when the request was picked up by the service “worker” to be executed; read-only
Note: This attribute is automatically set by the server and cannot be specified in API requests.
|
| TimeScriptStarted datetime: ISO 8601 | Time when all the necessary resources were downloaded and the AutoCAD core engine was about to start; read-only
Note: This attribute is automatically set by the server and cannot be specified in API requests.
|
| TimeScriptEnded datetime: ISO 8601 | Time when the AutoCAD core engine finished executing; read-only
Note: This attribute is automatically set by the server and cannot be specified in API requests.
|
| TimeOutputTransferEnded datetime: ISO 8601 | Time when all the generated output was published; read-only
Note: This attribute is automatically set by the server and cannot be specified in API requests.
|
| BytesTranferredIn int | Total number of bytes that were downloaded as a result of executing the WorkItem request; read-only
Note: This attribute is automatically set by the server and cannot be specified in API requests.
|
| BytesTranferredOut int | Total number of bytes that were uploaded; read-only
Note: This attribute is automatically set by the server and cannot be specified in API requests.
|
| Id string | Unique identifier for the WorkItem
The value is generated by the API and is a GUID. The API does not assign the ID to the WorkItem until the WorkItem has been accepted by the API.
|
| Version int | Version number of the WorkItem; should always be
1 |
| Timestamp datetime: ISO 8601 | Timestamp of the last modification,
YYYY-MM-DDThh:mm:ss.ssZ format; read-onlyNote: This attribute is automatically set by the server and cannot be specified in API requests.
|
Example
{
"@odata.context": "https://developer.api.autodesk.com/autocad.io/us-east/v2/$metadata#WorkItems/$entity",
"ActivityId": "PlotToPDF",
"Arguments": {
"InputArguments": [
{
"Resource": "https://s3.amazonaws.com/AutoCAD-Core-Engine-Services/TestDwg/makeall.dwg",
"Name": "HostDwg",
"Headers": [],
"ResourceKind": null,
"StorageProvider": "Generic",
"HttpVerb": null
}
],
"OutputArguments": [
{
"Resource": "https://acesdev.s3-us-west-2.amazonaws.com/aces-workitem-outputs/9688d314d6e94bc682f901b468ca8dbc/result.pdf?AWSAccessKeyId=ASIAIIRAOVQYGB4OA7IA&Expires=1432231792&x-amz-security-token=AQoDYXdzEGIa0AMSDjA8SIKRwWVY8YvdmMQsZ3T5atGN2gDTUwcffe%2FMejuRGezSx%2F4lDaN1NwsGCc%2B91eXvocmWaEZA%2Bm8uClMwP%2Fr69UmL6RmOiK7dokQlbQGEoPEQwF%2Frpw2jPQ6wDq4suFWXlsuxODWP24v3GJ4fZRj9V4S91Z59Nagcla6Ll46YVS6rc0PlaC4ElJ89ncABb23dR%2BK%2FAAaPsFVVn8ZV81gqDbect8YjvMH2RCfXQb7KnheNFlL77AXMeJM11ahq3UUsDk2o3uYQswJQJg5AsYZEtXjbbKU40MDkLPKjn5Ua18%2FD1pNZFm%2FFhoHMHXHvfvJdfXPWHBKYEFCvIz%2FZyKg8CORDIpK04ZMuAV68jTiHGkes7U5L5QPnCDEDAyZnod6FK7djcNYQwJBE9SNge%2FBLAXmJ5Hsiuy8HZF7GF59LPSR%2BXyygw%2Fy1ssJxmKxK4jsUG33ukj69Mj1nXlKfVdk89cdonuOScw%2BnD91%2B1kRozlIXkDT9Crf%2FceshJHY48vaPtJ5VG1sGIZoHW5fzwcbXDEJzhLJcj0UaFr5N3sgMKCX7KtZcqRYp%2Bupd7khRSAhC2LZdOyCHAQgi45F11qYZ8fwiUassVPEYIwTpYiDbgfOqBQ%3D%3D&Signature=02E4g51C2R9NsdwX0vloUmX8RCM%3D",
"Name": "Result",
"Headers": [],
"ResourceKind": null,
"StorageProvider": "Generic",
"HttpVerb": "POST"
}
]
},
"Status": "Succeeded",
"StatusDetails": {
"Report": "https://acesdev.s3-us-west-2.amazonaws.com/aces-workitem-reports/9688d314d6e94bc682f901b468ca8dbc/report.log?AWSAccessKeyId=ASIAIIRAOVQYGB4OA7IA&Expires=1432231871&x-amz-security-token=AQoDYXdzEGIa0AMSDjA8SIKRwWVY8YvdmMQsZ3T5atGN2gDTUwcffe%2FMejuRGezSx%2F4lDaN1NwsGCc%2B91eXvocmWaEZA%2Bm8uClMwP%2Fr69UmL6RmOiK7dokQlbQGEoPEQwF%2Frpw2jPQ6wDq4suFWXlsuxODWP24v3GJ4fZRj9V4S91Z59Nagcla6Ll46YVS6rc0PlaC4ElJ89ncABb23dR%2BK%2FAAaPsFVVn8ZV81gqDbect8YjvMH2RCfXQb7KnheNFlL77AXMeJM11ahq3UUsDk2o3uYQswJQJg5AsYZEtXjbbKU40MDkLPKjn5Ua18%2FD1pNZFm%2FFhoHMHXHvfvJdfXPWHBKYEFCvIz%2FZyKg8CORDIpK04ZMuAV68jTiHGkes7U5L5QPnCDEDAyZnod6FK7djcNYQwJBE9SNge%2FBLAXmJ5Hsiuy8HZF7GF59LPSR%2BXyygw%2Fy1ssJxmKxK4jsUG33ukj69Mj1nXlKfVdk89cdonuOScw%2BnD91%2B1kRozlIXkDT9Crf%2FceshJHY48vaPtJ5VG1sGIZoHW5fzwcbXDEJzhLJcj0UaFr5N3sgMKCX7KtZcqRYp%2Bupd7khRSAhC2LZdOyCHAQgi45F11qYZ8fwiUassVPEYIwTpYiDbgfOqBQ%3D%3D&Signature=omaAOII4CQaMUAXGChgsvT37I%2FU%3D"
},
"AvailabilityZone": null,
"TimeQueued": "2015-05-20T18:09:47.957Z",
"TimeInputTransferStarted": "2015-05-20T18:09:48.035Z",
"TimeScriptStarted": "2015-05-20T18:09:48.707Z",
"TimeScriptEnded": "2015-05-20T18:09:52.035Z",
"TimeOutputTransferEnded": "2015-05-20T18:09:52.16Z",
"BytesTranferredIn": 169056,
"BytesTranferredOut": 53800,
"Id": "9688d314d6e94bc682f901b468ca8dbc",
"Version": 1,
"Timestamp": "2015-05-20T18:09:52.16Z"
}
Show More
AppPackage
An AppPackage is a module that is used by an Activity in order to perform a particular action.
Schema
| References array: string | AppPackages that this AppPackage depends on; optional
The values must match the
Id attributes of the referenced AppPackage objects. |
| Resource string: URL | Location of the bundle (a zip file of the format used in Autodesk Exchange store) containing DLL, AutoLISP, or other files to be loaded into the AutoCAD core engine
|
| RequiredEngineVersion enum: string | Version of the AutoCAD program that this AppPackage is compatible with. Possible values:
20.1, 21.0, 22.0.Note: Use the
ACADVER system variable within your local install of the AutoCAD program to see which version you are using locally. |
| IsPublic bool | Specifies whether the entity can be publicly targeted
When set to
true, the entity can be referenced by other clients outside of your account. |
| IsObjectEnabler bool | Indicates whether the AppApackage represents an object enabler
|
| Id string | Unique name of the AppPackage
|
| Version int | Version of the bundle referenced by the Resource attribute; identifies an AppPackage in the SetVersion method
|
| Timestamp datetime: ISO 8601 | Timestamp of the last modification,
YYYY-MM-DDThh:mm:ss.ssZ format; read-onlyNote: This attribute is automatically set by the server and cannot be specified in API requests.
|
| Description string | Additional details about the AppPackage; optional
|
Example
{
"@odata.context": "https://developer.api.autodesk.com/autocad.io/us-east/v2/$metadata#AppPackages/$entity",
"References": [],
"Resource": "https://acesdev.s3-us-west-2.amazonaws.com/aces-apppackages/ClientConsole-Dev/54b48200-37e9-4f43-8392-4974b7d9dcd2?AWSAccessKeyId=AKIAJVT56CBNM4XOWBBA&Expires=1432145046&Signature=%2BRuYHEJ1JIXlXx6l1788uDpn66E%3D",
"RequiredEngineVersion": "22.0",
"IsPublic": false,
"IsObjectEnabler": false,
"Id": "MyAppPackage",
"Version": 1,
"Timestamp": "2015-02-11T19:15:40.835Z",
"Description": ""
}
Show More
Engine
An Engine is what executes a WorkItem job and processes the actions specified by an Activity.
Schema
| Resource string: URL | Location of the bundle (a zip file of the format used in Autodesk Exchange store) containing DLL, AutoLISP, or other files to be loaded into the AutoCAD core engine
|
| IsPublic bool | Specifies whether the entity can be publicly targeted
When set to
true, the entity can be referenced by other clients outside of your account. |
| Id string | Unique name of the Engine
|
| Version int | Version number of the Engine
|
| Timestamp datetime: ISO 8601 | Timestamp of the last modification,
YYYY-MM-DDThh:mm:ss.ssZ format; read-onlyNote: This attribute is automatically set by the server and cannot be specified in API requests.
|
| Description string | Additional details about the Engine; optional
|
Example
{
"@odata.context": "https://developer.api.autodesk.com/autocad.io/us-east/v2/$metadata#Engines/$entity",
"Resource": "https://acesdev.s3-us-west-2.amazonaws.com/aces-engines/ClientConsole-Dev/54b48200-37e9-4f43-8392-4974b7d9dcd2?AWSAccessKeyId=AKIAJVT56CBNM4XOWBBA&Expires=1432145046&Signature=%2BRuYHEJ1JIXlXx6l1788uDpn66E%3D",
"IsPublic": true,
"Id": "20.1",
"Version": 1,
"Timestamp": "2015-02-11T19:15:40.835Z",
"Description": "AutoCAD 2015 version"
}
Show More
