API Basics
Familiarize yourself with these concepts that are used throughout the documentation:
Term | Definition |
---|---|
Activity | The specification of an action that can be executed using a specified engine.
For example, using AutoCAD to plot a supplied DWG to a PDF file.
Another example: using AutoCAD to update a supplied DWG file to use a different set of CAD standards.
An Activity specifies the number of input and output files, and the AppBundle and entry-point to use.
|
AppBundle | A module referenced by an Activity in order to perform specific functions.
Typically this is a DLL or some other form of custom code.
For example, using the AutoCAD engine, this might be a custom AutoLISP routine that extracts
Xdata attached to objects in a drawing or a script file that plots a DWG to a PDF file.
|
module file | An AppBundle entity.
|
WorkItem | A job that executes a specified Activity, using specified input files and generating appropriate output files.
The relationship between an Activity and WorkItem can be thought of as a “function definition” and “function call”, respectively. The Activity specifies the AppBundle(s) to use, which in turn specify the Engine to use.
Note: Once a WorkItem is created, it cannot be modified.
|
Engine | The actual processing engine that runs the WorkItem job and processes the Activity.
The following engine types are available: AutoCAD, 3dsMax, Inventor and Revit. There may be multiple
versions of each engine.
|
Typical Workflows
Using a Pre-Existing Activity
Use this workflow to execute a previously-created Activity, supplying one or more documents as inputs. The Activity will already have had the necessary AppBundles associated with it. The Activity defines the expected input and output files.
This workflow applies to both your own Activities and Activities that are shared with you.
- Upload all files to be processed and referenced. The files can be stored in the Data Management or in any other cloud storage provider.
- Create WorkItem: Use the POST workitems endpoint to create a WorkItem that uses the pre-defined Activity. You specify the URLs of the input files and output files. The WorkItem downloads the input files, and begins the execution of the custom programs or scripts defined in the AppBundles associated with the Activity passed to the WorkItem. When complete, it uploads the output files to the specified URLs.
- Wait for completion: Poll GET workitems/:id to check the current status of the WorkItem. It might be “in progress” or “complete”. (There is also a non-polling mechanism.)
- Get results: When the WorkItem is complete, the output file(s) are available at the specified cloud storage provider. A cloud service can utilize them from there, or you can download them.
Using a Custom Activity
This workflow is used when you need to create a new Activity and associate one or more AppBundles that define the custom programs or scripts to be executed on one or more documents.
- Optionally, upload any custom programs or scripts to be assigned to an AppBundle and associated with a custom Activity to a specified cloud storage provider.
- Use POST appbundles to create a new AppBundle.
- Use POST activities to create a custom Activity.
(following steps are the same as for ‘Using a Pre-Existing Activity’)
- Create WorkItem: Use the POST workitems endpoint to create a WorkItem that uses the pre-defined Activity. You specify the URLs of the input files and output files. The WorkItem downloads the input files, and begins the execution of the custom programs or scripts defined in the AppBundles associated with the Activity passed to the WorkItem. When complete, it uploads the output files to the specified URLs.
- Wait for completion: Poll GET workitems/:id to check the current status of the WorkItem. It might be “in progress” or “complete”. (There is also a non-polling mechanism.)
- Get results: When the WorkItem is complete, the output file(s) are available at the specified cloud storage provider. A cloud service can utilize them from there, or you can download them.