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

Special notes for calling Connector Packages

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

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

Example: /api/v1/TENANT_ID/connector-package/batch-management/batch-creation

Special notes for calling Orchestrator Packages

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

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

Example: /api/v1/TENANT_ID/orchestrator-package/production/production-confirmation

Communication using SOAP

Some Packages also create an endpoint collection using SOAP technology:

/soap/v1/TENANT_ID/PACKAGE_TYPE/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
- PACKAGE_TYPE needs to be replaced with the kebab-case type of package to call (either connector-package or orchestrator-package)
- 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/v1/TENANT_ID/PACKAGE_TYPE/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
- PACKAGE_TYPE needs to be replaced with the kebab-case type of package to call (either connector-package or orchestrator-package)
- 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)