Inbound Integrations

With inbound integrations we refer to allowing an external system to either request data from / send data to the 3DEXPERIENCE™ system.

To enable this, you will create one or more custom REST endpoints within TIF. Such REST endpoint is defined by creating a REST Mapping from the Administration UI.

The REST Mapping defines the characteristics of the end-point, such as:

URI

The URI used to match the request with

HTTP Method

Which method we are mapped to. E.g. GET, POST, PUT, PATCH, DELETE etc

Request Header Requirements

If there are some requirements on the request headers being sent.

Request Parameter Requirements

You can also define some requirements on request parameters.

You can define as many endpoints as needed, but, be aware of that one request made to TIF should not map to more than ONE REST mapping. If that is the case, an error is raised.

For more details on the REST Mapping details, please see this document.

The base URL for the REST endpoint is:

https://<tif-tenant>.tif.technia.cloud/integration/api/v1/newjob

Then you append the REST Mapping URI to this base URL.

For example, if your REST mapping defines the URI /item the complete URL is then

https://<tif-tenant>.tif.technia.cloud/integration/api/v1/newjob/item

Access Token

The external system will call TIF using a special access / request token. Please see this document how to create these.

The Source system property of the token is important as different tokens having the same source-system value, will be able to query for jobs they have been created.

A token with a different source-system value will not see jobs created by another source system.

Request Job

The source system will request a job in TIF similar to the curl example below

curl -X POST \
    -i \
    -H "TIF-API-Key: <api-key-here>" \
    -H "custom-header-1: value" \
    -H "Content-type: application/json" \
    https://<url>/integration/api/v1/newjob/rest/mapping/uri?param1=value1 \
    -d "{'prop1':123,'prop2':true}"

The response will return the following information:

Job ID

As the response header TIF-Job-Id

Job Status

As the response header TIF-Job-Status

Async

Defines if the job is being executed asynchronously or not. The header holding this value is called TIF-Async.

If the Job was not executed asynchronously, the response will contain the output from the job also.

The following response codes are used:

200

Request succeeded, content provided

201

Job Created, execution takes place asynchronously

202

The request was accepted, and a job was executed but failed.

204

Request succeeded but job returned no data

404

Request could not be mapped to a job, most likely no REST Mapping matched the request

409

Request were mapped to > 1 REST Mapping

503

If the service configured for the REST mapping is paused (and the mapping is configured for synchronous invocation).

If the REST mapping is marked as being processed synchronous, then the response from a create job operation will contain the job-files of type OUTBOUND. If there are more than one such file attached to the job, a ZIP file is created with all those files attached.

An optional request parameter called fileFilter may be used to limit the included files. This request parameter defines a glob pattern of files to be included. Multiple fileFilter params can also be provided if needed.

Example:

?fileFilter=*.txt&fileFilter=SpecificFile.xml

Job Tags

The job created using the above mechanism can be associated with custom tags. That can be of use when querying / filtering jobs.

Such tag is provided using the request parameter jobTag. You can provide multiple job-tags if wanted.

Query Job Status

The client may query the status of the job, and/or retrieve data for the job using a dedicated endpoint:

GET https://<url>/integration/api/v1/jobs/<job-id>

As mentioned above, the request must be made with a token having its source-system identical as when the job was created. Otherwise, you will receive a 404/Not Found response.

There are also some other endpoints that can be used. These are described in the table below.

Method URI Description

GET

/integration/api/v1/jobs

Query jobs endpoint. The below params can be used to control the result:

  • pageStart (int, default 0)

  • pageSize (int, default 25)

  • hasError (boolean)

  • resolved (boolean)

  • status (string, multiple allowed)

  • startDate (string, format: iso8601 date or date/time format)

  • endDate (see startDate)

  • jobTags (string, multiple allowed)

GET

/integration/api/v1/jobs/{job-id}

Get one specific job

GET

/integration/api/v1/jobs/{job-id}/input

Get the input for one specific job

GET

/integration/api/v1/jobs/{job-id}/output

Get the output for one specific job.

Note that if the job have >1 output files of type OUTBOUND data, you will get a ZIP archive in return.

If you want to limit the returned job-file(s), e.g. you do not want to return all job-files of type OUTBOUND, you can provide a request parameter called fileFilter. This parameter may contain a wild-card glob pattern of file/files to be included. You can supply multiple filters if needed.

GET

/integration/api/v1/jobs/{job-id}/output/{data-id}

Returns the output for a specific file.