Introduction
Generic Conversion Workflow is a simple way for an external application to perform generic conversion of CAD files into VE viewables retrieve these viewables once the conversion has completed, purely programmatically.
Consumer of this API can be any application written in any language able to perform HTTPS POST and GET requests, using JSON as the message format.
Supported versions
VE Generator 8.0 SP4 or later
API overview
The API was designed as simple as possible for the purposes of performing simple conversion. It does not store the source CAD files, viewables and derivatives in the VEG database.
The API can be used in following scenarios where other methods are not supported:
Performing conversion of supported files (2D & 3D) to viewables where tagging, and requesting of derivatives should be done completely programmatically
Performing conversion of supported files (2D & 2D) to viewables in environments where it is not feasible to share files using network shares accessible to both VEG and the caller of the API
The API is RESTful, using standard HTTP methods GET, PUT and POST.
The message format used is JSON.
Before performing API calls, the caller should perform authentication, which will issue the caller a token with default lifetime of 125 minutes. Timeout can be customized in the web folder's Web.config file, section SecurityImplementation.
This token is to be provided in the HTTP Authorization header in all subsequent API calls. If usage of the token returns a 401 Unauthorized HTTP response, re-authentication should be performed.
Usage scenario
- Successfully authenticate with the
/authenticate
API, get access token. - Upload original files using
/files
, and obtain IDs for each file - Start a conversion job using
/jobs
, specifying some or all of the following information:
- The kind of output to be created
The output viewable format
Any custom processing settings
Which of uploaded files to convert (one or many) and their individual processing parameters, including CAD configuration to be extracted, metadata, etc.
The server will return a job ID for the conversion job.
4. Monitor the progress of the conversion job using the job ID, both the status and the progress of the job is available.
5. Upon successful conversion (successful job status), the response will contain information about he viewables and derivatives that were produced by the job. Outputs can be retrieved using the /files
API.
6. Upon conversion failure (failed job status), more information will be available to diagnose the cause of the job failure.
API Reference
GET /version
Returns version information about the endpoint. This should be used to determine whether the caller supports the version of the API, or whether the API is of a high enough version.
This method does not require authentication - no HTTP Authorization header required.
Request
Request body is empty.
Response
Response is a JSON object.
Object Fields
Response Field | Type | Description |
---|---|---|
api | String | Contains the version of the REST API in the format MAJOR.MINOR. |
product | Object | Contains product information |
name | String | The name of the product implementing the API |
version | String | The version of the product implementing the API. Do not parse this value, it is informational only, and has no guaranteed format. |
Example
{ "api": "1.0", "product": { "name": "VE Generator Generic Conversion", "version": "9.0.0.42382 " } }
POST /authenticate
Authenticates the caller.
Note: Because the password is provided in clear text, this call is required to be made over SSL.
Request
Request body is a JSON object.
Object Fields
Response Field | Type | Description |
---|---|---|
username | String | The VEG user name to authenticate with. |
password | String | The VEG password of the user. |
Example
{ "username": "myName", "password": "myPassword" }
Response
Response is a JSON object.
Object Fields
Response Field | Type | Description |
---|---|---|
token | String | If authentication was successful, contains the token to be used for other calls. The token should be provided with each subsequent request in the HTTP Authorization header, using this format:
If it is not possible to set a custom HTTP header, the TOKEN can be passed as a query parameter named oauth_token: GET /files/ID?oauth_token=TOKEN |
outcome | String | An enumeration of one of the following values:
|
message | String | A message describing the authentication failure. |
Examples
1.
{ "token": "{65FDC020-2A64-439F-ABFE-D6B782E47189}", "outcome": "success" }
2.
{ "outcome": "failure", "message": "invalid username or password" }
POST /files or PUT /files
Uploads a single new file. Two upload methods are supported, the path /files
is used for both:
Raw Uploads
The request body is the raw, binary content of the file. The X-FileName header contains the file name of the file being uploaded. The Content-Type HTTP header specifies the MIME type of the file content, if not specified, the file extension will be used to produce a fallback MIME type.
Form Uploads
The Content-Type header is set to multipart/form-data, and the request body is encoded as a form data upload. Only one file part is supported, attempting to upload multiple files will be rejected by the server. The Content-Type header for a file part specifies the MIME type of the file content, if not specified, the file extension will be used to produce a fallback MIME type. The file name is supplied via the Content-Disposition header for a part.
Response
Response is a JSON object.
Fields
Response Field | Type | Description |
---|---|---|
outcome | String | An enumeration of one of the following values:
|
id | String | If outcome was success, contains the ID that can be used to refer to the file. Optional. |
message | String | If outcome was failure, contains a message describing the reason for failure. Optional. |
Example
{ "outcome": "success", "id": "YlXy1q0uf3KOUcjKoiXcXre7YSQfp7Y36tOwFPty6S8" }
POST /jobs
Starts a new conversion job, converting previously uploaded files into viewable and derivative outputs.
Request
The request is a JSON object.
Object Fields
Request Field | Type | Description |
---|---|---|
kind | String | Contains the kind of outputs to be created. Required. Can be one of:
|
format | String | Specifies the file format for the output viewables. Can be one of:
|
processing_settings | Object | A dictionary of name-value pairs of settings that will be used during processing. Optional. Settings:
|
originals | Array of Object | An array of JSON objects representing original files. At least one original must be supplied. |
id | String | An identifier for this original, can be used to refer to this original from instances. Required. Note: The string must contain only alpha-numeric characters, and must start with a letter and not a number. |
name | String | The name of the original. Will be used as the base name for the viewable file name, e.g. name.vds or name.rh. Required. |
file_id | String | The identifier of the file as returned by file uploading. Optional when the original has children and is_resolved_structure is true. |
toplevel | Boolean | Whether or not this file is a top-level file. Default: false. |
outputs | Array of String | The viewable outputs that should be created for the original. Note: viewable is ignored if kind is shattered Possible values:
Default: [viewable], which means that only a viewable will be produced. |
configuration | String | If specified, the named CAD configuration to extract from this file. If not specified, all configurations will be extracted (this may result in multiple viewable outputs). Optional. |
identifiers | Array of Object | Any VE identifiers to assign to the scene node corresponding to this original. Identifiers are applied throughout hierarchies, so if this original is contained within another original in the same job, identifiers set here will be present in the viewable for the other original as well. Optional. |
source | String | The source of the identifier. A source of SAP is reserved for SAP identifiers. Required. |
type | String | The type of the identifier. Required. |
fields | Array of Object | The fields contained within the identifier. A field should be a JSON object that contains a single key-value pair, e.g. {"NUMBER": "123"}. Is an array because multiple fields with the same name are allowed to exist (unlike metadata below). At least one field is required for an identifier. |
metadata | Array of Object | Any metadata to set on the scene node corresponding to this original. Optional. |
name | String | The metadata group name. Required. |
fields | Object | A dictionary of name-value pairs representing the metadata values to set, e.g. {"PARTNO": "ABC123", "TEST": "VALUE"}. At least one field must be supplied. |
import_settings | Object | A dictionary of name-value pairs representing import settings that can be used when translating the input files. Optional. Available settings:
|
export_settings | Object | A dictionary of name-value pairs representing export settings that can be used when producing the output viewable files. Optional. Available settings:
|
derivatives | Array of Object | The derivatives that should be created, in addition to the viewable outputs. Optional. |
type | String | The type of derivative to create. Will map to the name of a derivative. Note: Either type or group is required, but both cannot be specified. |
group | String | The derivative group. Will map to all derivative types in that group. Note: Either type or group is required, but both cannot be specified. |
parameters | Object | A dictionary of name-value pairs representing the derivative type parameter values to pass through (e.g. PDF template name). Note: ignored if group specified. |
children | Array of Object | Optional array of child JSON objects referencing child original file instances. Ignored unless processing_settings has the is_resolved_structure setting set to true. |
name | String | The name of this child instance. |
original_id | String | The id of the original that is a child of this original. Required. |
tmatrix | String | The 4x4 parent-relative transformation matrix, in VZXML format, positioning the child within this original. Optional. If omitted, the identity matrix is used. |
Example
{ "kind": "monolithic", "format": "RH", "processing_settings": { "output_expiry_days": 12 }, "originals": [ { "id": "d123", "name": "Skateboard", "file_id": "f123", "toplevel": true, "configuration": "Custom" }, { "id": "d124", "file_id": "f124", "identifiers": [ { "source": "SAP", "type": "DOCUMENT", "fields": [ { "NUMBER": "123" }, { "TYPE": "SWA" }, { "PART": "000" }, { "VERSION": "00" } ] } ], "metadata": [ { "name": "SAP", "fields": { "MATERIAL": "123" } }, { "name": "CADMetadata", "fields": { "PARTNO": "ABC123", "TEST": "VALUE" } } ], "import_settings": { "load_hidden_geometry": true, "load_metadata": false }, "export_settings": { "read_only": true, "compression_level": 1 } }, { "id": "d123", "name": "Truck", "file_id": "f125", "derivatives": [ { "type": "pdf", "parameters": { "template": "my_template" } } ] } ] }
Response
The response is a JSON object.
Object Fields
Response Field | Type | Description |
---|---|---|
outcome | String | An enumeration of one of the following values:
|
id | String | If outcome was success, contains the job ID. |
message | String | If outcome was failure, contains a message describing the reason for failure. Optional. |
Example
{ "outcome": "success", "id": "123", }
GET /jobs
Gets the list of conversion jobs created by the current user. This list is limited to the 1000 most recent jobs, and is in descending order.
Response
The response is a JSON array, containing the job IDs.
Example
["123", "456", "2332"]
GET /jobs/<ID>
Gets the details of the conversion job with the ID of <ID>. Returns 404 if a job with the specified ID does not exist. Returns 406 if the specified localization language is not valid.
NOTE:
- If your client does not automatically set the "Accept-Language" header the localisation language defaults to English
- Supported two letter localisation abbreviations are: "de", "en", "es", "fr", "ja", "ko", "pt", "ru", "zh"
Response
The response is a JSON object.
Response Field | Type | Description |
---|---|---|
id | String | The job ID. |
status | String | The status of the job, one of:
|
outcome | String | The outcome of the job, one of:
|
progress | Double | The progress of the job, as a percentage. |
progress_text | String | A human-readable text message describing the current work being performed by the job |
message | String | If the outcome of the job was failure, will contain the overall reason for the failure of the job. |
outputs | Array of Object | If the outcome was success, and output_status is available, contains the list of outputs created by the job. |
id | String | The identifier of this output, if the output needs to be referenced; the OUTPUT_ID metadata field value in the group SAP of an entity in the structure analysis XML file will have this value, and this can be used to match entities to outputs |
status | String | The status of the output, one of:
|
message | String | If the status of the output is not created, this will contain a message that contains the reason for the failure of this particular output |
kind | String | The type of the output, one of:
|
name | String | The name of the file for this output. |
file_id | String | The ID of the file that the content for output is stored in. |
original_id | String | The ID of the original this output is associated with. |
configuration | String | The configuration this output is associated with, if applicable. Note: If extract_all_configurations_if_unspecified is true (the default), there may be multiple outputs for one original, since all CAD configurations will be extracted. |
Example
{ "id": "123", "status": "completed", "outcome": "success", "progress": 77.8, "outputs": [ { "status": "created", "kind": "viewable", "name": "Skateboard.vds", "original_id": "d123", "file_id": "f555", "configuration": "Default" }, { "status": "created", "kind": "structure", "name": "Skateboard.vzxml ", "original_id": "d123", "file_id": "f556", "configuration": "Default" }, ] }
DELETE /Jobs/<ID>
Aborts job with the ID of <ID>. This call is available from version 9.10 (9.0 FP10). Returns 404 if a job with the specified ID does not exist. Returns 500 if any other server error occurs like user not authorized to abort.
Response
The response is a JSON object. Returns 200.
Object Fields
Response Field | Type | Description |
---|---|---|
outcome | String | An enumeration of one of the following values:
|
message | String | If outcome was failure, contains a message describing the reason for failure. Optional. |
GET /files/<ID>
Downloads the file with the identifier <ID>. Returns 404 if a file with the specified ID does not exist.
The content of the file will be in the response body. The Content-Length header will contain the size of the file content, and the Content-Type header will contain the type of the file content. The Content-Disposition header will be of the format attachment; filename=FILENAME. This can be used to determine the file name to use for the downloaded file content.
Example Raw HTTP Response
HTTP/1.1 200 OK Content-Disposition: attachment; filename=test4.txt Content-Type: text/plain Content-Length: 18 Date: Mon, 08 Jun 2015 01:45:44 GMT Server: SAP multi part upload