How to call ERP Connectivity

In order to call any interface of ERP Connectivity the client must be authenticated and authorized for the requested resource in Multitenant Access Control. For calling a Connector Package or an Orchestrator Package the ErpConnectivityS2S role needs to be assigned to the client.

Before the call to ERP Connectivity will be triggered, the client needs to obtain a valid token from Multitenant Access Control. We propose to use the client credentials flow for it. Please check Multitenant Access Control’s developer guide on how to implement that.

After the token is obtained, it can be used in "Authorization" header of HTTP request towards ERP Connectivity. ERP Connectivity will then check if the token is valid for this special use.

Generic communication pattern in ERP Connectivity

ERP Connectivity provides asynchronous interfaces for calling a Connector Package or Orchestrator Package. Therefore, there are two interfaces for each Package:

one interface for triggering the execution of a specific Package

The exact endpoint is provided in the technical information of a Package (see screenshot - point 2).
one interface for getting the result of a Package execution.

This endpoint will be provided with the RabbitMQ information message that is sent out after Package execution. You can find the routing key, which is needed to filter correct message from Nexeed Integration exchange, in the technical information of a Package (see screenshot - point 1)
(optional) one interface for calling Connector Package execution synchronously.

- only available for specific Connector Packages This endpoint allows the client to expect synchronous execution of called Connector Package. This is only available if the Connector Package provides the possibility to be executed synchronously. The exact endpoint is provided in the technical information of a Connector Package (see screenshot - point 3).

Connector Package details - endpoint information

The order of events is like following:

Client triggers Package execution with call to that specific endpoint
ERP Connectivity executes that package with provided information
ERP Connectivity sends out a notification via RabbitMQ
Client can call ERP Connectivity with provided endpoint from notification to retrieve response payload

Endpoints provided per Package

With Version 4.11 of ERP Connectivity a unified API for executing Connector and Orchestrator Packages is provided. This Version 2 of the API will provide following REST endpoints per Package:

/rest/v2/TENANT_ID/AREA/OPERATION
- TENANT_ID needs to be replaced with the tenant id where the Connector Package is installed
- AREA needs to be replaced with the area that this Connector Package belongs to (e.g. batch-management for BatchManagement area in Connector Package)
- OPERATION needs to be replaced with the operation that this Connector Package belongs to (e.g. batch-creation for Batch Creation operation in Connector Package)
/rest/v2/TENANT_ID/AREA/OPERATION/PACKAGEIDENTIFIER
- same replacements as above
- PACKAGEIDENTIFIER needs to be replaced with the unique identifier of the specific Package. This can be found in the WebUI after Package installation.
/rest/v2/TENANT_ID/AREA/OPERATION/direct
- only available for specific Connector Packages
- same replacements as above
/rest/v2/TENANT_ID/AREA/OPERATION/PACKAGEIDENTIFIER/direct
- only available for specific Connector Packages
- same replacements as above
/rest/v2/TENANT_ID/AREA/OPERATION/result/RESULTID
- same replacements as above
- RESULTID needs to be replaced with the id that is part of the trigger request response.

AREA and OPERATION always need to be in kebab-case.

Example: /rest/v2/TENANT_ID/batch-management/batch-creation

Special notes for calling Connector Packages

This section only covers Version 1 of the Package execution API. This version is deprecated. Please use version 2 which is described above!

Each Connector Package creates its own endpoint collection. This collection contains following two to three endpoints:

/api/v1/TENANT_ID/connector-package/AREA/OPERATION
- TENANT_ID needs to be replaced with the tenant id where the Connector Package is installed
- AREA needs to be replaced with the area that this Connector Package belongs to (e.g. batch-management for BatchManagement area in Connector Package)
- OPERATION needs to be replaced with the operation that this Connector Package belongs to (e.g. batch-creation for Batch Creation operation in Connector Package)
/api/v1/TENANT_ID/connector-package/AREA/OPERATION/results/RESULTID
- same replacements as above
- RESULTID needs to be replaced with the id that is part of the trigger request response.
/api/v1/TENANT_ID/connector-package/AREA/OPERATION/direct
- only available for specific Connector Packages
- same replacements as above

Special notes for calling Orchestrator Packages

This section only covers Version 1 of the Package execution API. This version is deprecated. Please use version 2 which is described above!

Each Orchestrator Package creates its own endpoint collection. This collection contains following two to three endpoints:

/api/v1/TENANT_ID/orchestrator-package/AREA/OPERATION
- TENANT_ID needs to be replaced with the tenant id where the Orchestrator Package is installed
- AREA needs to be replaced with the area that this Orchestrator Package belongs to (e.g. production for Production area in Orchestrator Package)
- OPERATION needs to be replaced with the operation that this Orchestrator Package belongs to (e.g. production-confirmation for Production Confirmation operation in Orchestrator Package)
/api/v1/TENANT_ID/orchestrator-package/AREA/OPERATION/results/RESULTID
- same replacements as above
- RESULTID needs to be replaced with the id that is part of the trigger request response.
/api/v1/TENANT_ID/orchestrator-package/AREA/OPERATION/direct
- only available for specific Orchestrator Packages
- same replacements as above

Communication using SOAP

Some Packages also create an endpoint collection using SOAP technology:

/soap/v2/TENANT_ID/AREA/OPERATION/direct executes the given package via soap and immediately returns the result
- TENANT_ID needs to be replaced with the tenant id where the Package is installed
- AREA needs to be replaced with the area that this Package belongs to (e.g. batch-management for BatchManagement area in Package)
- OPERATION needs to be replaced with the operation that this Package belongs to (e.g. batch-creation for Batch Creation operation in Package)
- This endpoint must be called with a valid SOAP envelope payload in XML, an example for which can be generated using the WSDL endpoint below.
/soap/v2/TENANT_ID/AREA/OPERATION/PACKAGEIDENTIFIER/direct executes the given package via soap and immediately returns the result
- TENANT_ID needs to be replaced with the tenant id where the Package is installed
- AREA needs to be replaced with the area that this Package belongs to (e.g. batch-management for BatchManagement area in Package)
- OPERATION needs to be replaced with the operation that this Package belongs to (e.g. batch-creation for Batch Creation operation in Package)
- PACKAGEIDENTIFIER needs to be replaced with the unique identifier of the specific Package. This can be found in the WebUI after Package installation.
- This endpoint must be called with a valid SOAP envelope payload in XML, an example for which can be generated using the WSDL endpoint below.
/soap/v2/TENANT_ID/AREA/OPERATION/wsdl gets the WSDL definition of the SOAP endpoint
- TENANT_ID needs to be replaced with the tenant id where the Package is installed
- AREA needs to be replaced with the area that this Package belongs to (e.g. batch-management for BatchManagement area in Package)
- OPERATION needs to be replaced with the operation that this Package belongs to (e.g. batch-creation for Batch Creation operation in Package)