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: `Authorization: Bearer TOKEN` 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: success – Authentication was successful failure – Authentication was not successful
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: success – The file was created failure – The file could not be created
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: monolithic – create monolithic viewable outputs, one for each original that has viewable in its list of requested outputs. shattered – create shattered viewable outputs (VE 9.0+ only). analysis – creates only structure XML output, no outputs will be built. format parameter will be ignored.
format	String	Specifies the file format for the output viewables. Can be one of: rh – RH binary format. Default for 8.0. vds – VDS format. Default for 9.0+.
processing_settings	Object	A dictionary of name-value pairs of settings that will be used during processing. Optional. Settings: is_resolved_structure – Whether or not the originals hierarchy is a resolved structure or not. If set to true, CAD structure analysis is skipped, and the structure provided is used as-is instead. Default: false. output_expiry_days – Number of days output files are kept for before being deleted. is_viewable_creation_failure_error – Whether or not it’s an error if viewables could not be created. Default: true. (VE 9.0+ only) is_derivative_creation_failure_error – Whether or not it’s an error if derivatives could not be created. Default: false. is_structure_extraction_error – Whether or not it’s an error if input file structure extraction fails. If it’s not an error, conversions are attempted for any successful extractions. Default: true. is_missing_cad_file_error – Whether or not it’s an error if a CAD file referenced in the structure is missing. If it’s not an error, a warning message will be logged but conversion will proceed. Default: true. (VE 9.0+ only) extract_all_configurations_if_unspecified – Whether or not all configurations should be extracted, with viewables created, if no configurations were specified for an original. Default: true.
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: viewable thumbnail animated_thumbnail 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: load_hidden_geometry – Boolean load_metadata – Boolean load_hidden_metadata – Boolean load_pmi – Boolean load_hidden_pmi – Boolean
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: read_only – Boolean compression_level – Integer
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: success – The job was started failure – The job could not be started
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: queued – job is in the queue, but has not started yet running – job is currently in progress completed – job has completed
outcome	String	The outcome of the job, one of: success – the job completed successfully, and produced all requested outputs failure – the job failed, and some outputs might be missing or failed - the outputs array should be consulted if present
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: created – output created failed – output creation failed skipped – output creation was skipped (e.g. dependency failed)
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: viewable – an RH or VDS viewable thumbnail – a JPEG thumbnail of the viewable animated_thumbnail – an animated GIF thumbnail of the viewable derivative – a derivative of the viewable (e.g. 3D PDF) structure – a VZXML file containing the structure of the supplied original file. Note: this is only created for toplevel originals. related_alf_file - a separate file containing assembly level information, which will be required to load the output viewable. VE 9.0+ only, and only present if the viewable format is vds, and the output kind is shattered. related_general_file - a separate file that was created during the conversion process, which may be required to load the output viewable. VE 9.0+ only.
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:

success – The job was marked for abort
failure – The job could not be aborted

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

Generic Conversion - API Reference

Introduction

API overview

Usage scenario

API Reference

GET /version

Request

Response

Object Fields

Example

POST /authenticate

Request

Object Fields

Example

Response

Object Fields

Examples

POST /files or PUT /files

Raw Uploads

Form Uploads

Response

Fields

Example

POST /jobs

Request

Object Fields

Example

Response

Object Fields

Example

GET /jobs

Response

Example

GET /jobs/<ID>

Response

Example

DELETE /Jobs/<ID>

Response

Object Fields

GET /files/<ID>

Example Raw HTTP Response