Skip to end of metadata
Go to start of metadata

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:

  1. Performing conversion of supported files (2D & 3D) to viewables where tagging, and requesting of derivatives should be done completely programmatically

  2. 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

  1. Successfully authenticate with the /authenticate API, get access token.
  2. Upload original files using /files , and obtain IDs for each file
  3. 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:

  1. If your client does not automatically set the "Accept-Language" header the localisation language defaults to English
  2. 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_textStringA 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.

        idString

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)
        messageStringIf 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
  • No labels