Exchange Integration Point

This integration point provides the ability to:

Invoke an Integration
Recover an Integration

The integration point returns HTTP status codes as defined in the Developer Guide in section Response Messages.

The operations are protected by the HTTP API access restriction 'exchange IP'. For the GET operations a grant must be provided with the Read flag set. For the POST operations a grant must be provided with the Create flag set.

The endpoint is available at the following location:

http://<host>:<port>/<context-root>/exchanges

Integration Invocation

An integration is invoked using this integration point. To determine which integration is invoked, provide the type and the code of the integration.

http://<host>:<port>/<context-root>/exchanges/<type>/<code>

type: This is the integration type. Possible values are domain values that are available at runtime.
integration: For all the common usecases that are not geography specific.
Localization specific: example: For Australian usecases, this may contain values like, isoft, transfergateway etc.
code: The unique identification of the integration configuration.

An integration can be invoked using the above path with a variety of possibilities:

HTTP input parameters
JSON key-value payload
Dynamic Logic parsing of payload and parameters
With File

These varieties are described later.

Invocation of a Disabled Integration

An integration can be disabled. This can be useful for instance to resolve a problem with a specific integration. Whenever an integration is in a disabled state, invoking that integration will yield a HTTP 409 (Conflict) error. The response payload describes the reason of the conflict.

Invocation of a Specific Integration Version

When invoking an exchange, the application selects the highest-enabled integration version automatically. You can invoke an exchange for a specific integration version. This supports a user in the following cases:

When a new version is under development, and you want to continue using the previous version.
When you want to test the integration before adopting a new release.
When the highest integration version has an issue, you want the application to use a previous version until the issue resolves.

To invoke an exchange for a specific integration version, you must add the following HTTP header to the request:

HTTP Header

Description

ohi-integration-version

The version number on the integration

Invoking a disabled integration version results in an HTTP 409 (Conflict) error.

The OIG Agent cannot invoke an exchange for a specific integration version.

Invocation of an Access-Controlled Integration

If the integration specifies an access restriction, then only the user that has access grant to the specified access restriction can view, invoke or recover the exchange in the context of this integration. If the user does not have access then error 403 (Forbidden) is raised.

The user that has create access grant to the specified access restriction can invoke the exchange in the context of this integration.
The user that has an update access grant to the specified access restriction can recover the exchange in the context of this integration.
The user that has retrieve access grant to the specified access restriction can view exchanges (and sub exchanges) in the context of this integration.

Note - This is not applicable for scheduled invocations.

Performing a Blocking Invocation

An exchange typically is processed asynchronously. In some cases this might not be possible and/or desirable from a client perspective. For this purpose it is possible to invoke an integration and have it processed in a seemingly synchronous/blocking way. A client then will be blocked until the whole exchange reaches an end-state or until a specified period of time has passed. To control this behavior a caller needs to provide the following HTTP headers along with the call:

HTTP Header	Description
ohi-exchange-allowed-time-ms	The maximum allowed time in milliseconds a client is willing to wait for the exchange to complete. Typically, in the order of magnitude of 1 to 5 seconds.
ohi-exchange-execute-blocking	When specified as "true", this will initiate a POST-REDIRECT-GET sequence, where the GET blocks the client.

HTTP Header

Description

ohi-exchange-allowed-time-ms

The maximum allowed time in milliseconds a client is willing to wait for the exchange to complete. Typically, in the order of magnitude of 1 to 5 seconds.

ohi-exchange-execute-blocking

When specified as "true", this will initiate a POST-REDIRECT-GET sequence, where the GET blocks the client.

It is important that the HTTP/REST Client that invokes the integration is set up, so it can follow HTTP Response code 303 (See Other or redirect to a new URI).

HTTP Input Parameters

In this scenario, the integration is invoked with GET or POST input parameters.

Example for a GET request:

http://<host>:<port>/<context-root>/exchanges/<type>/<code>?id=12&type=a&descr="invokewithparameter"

Example for a POST message:

POST /path/path HTTP/1.0
Content-Type: application/x-www-form-urlencoded
Content-Length: 32

id=12&type=a&descr="invokewithparameter"

In both cases, input parameters are made available as properties on the exchange to be used by each integration step.

It is possible to add an exchange description to provide more context to the integration invocation. The value for description can be provided by specifying a request parameter 'descr' at the time of invocation. Refer to the above examples for clarity.

JSON Key or Value POST

In this scenario, a message is posted on the following URL with a JSON payload.

http://<host>:<port>/<context-root>/exchanges/<type>/<code>/withParameters

Example of the payload

{"param1" : "paramValue1",
 "param2" : "paramValue2",
 "descr" : "invokeIntegrationAsJSON key/value"
}

It is possible to add an exchange description to provide context to the integration invocation. The value for description can be provided by specifying an attribute 'descr', along with the parameter at the time of invocation. Refer above example of the JSON payload for clarity.

Alternatively, provide an exchange description value by specifying a value for a header parameter called 'ohi-exchange-description', for example:

Content-Type: multipart/form-data;
ohi-exchange-description: invocationWithDynamicLogic;

If attribute 'descr' and HTTP header parameter 'ohi-exchange-description' are both specified then the value of the former prevails.

Dynamic Logic Parsing

In the case that the methods above do not suffice, Dynamic Logic can be used to parse the payload. The URL used to invoke:

http://<host>:<port>/<context-root>/exchanges/<type>/<code>

Example: the integration can be invoked by a message with this payload:

<group name="ACME">
  <member>
    12
    <name>Scott</name>
  </member>
 </group>

For example, a group name needs a member ID as properties for the data collection. The parameter extraction dynamic logic configured in the Integration configuration is invoked to extract these properties. Example dynamic logic:

def rootNode = new XmlSlurper().parseText("<group name="ACME"> <member> <id> 12 </id> <name>Scott</name> </member> </group>")
return [groupName:rootNode.@name, memberId:rootNode.member.id]

The Dynamic Logic returns a map of properties.

Note that the payload could also be the message (e.g. a claim) that needs to be passed on to the delivery step. In that case, the Dynamic logic can process this message before passing it on as a parameter or pass it on in its original format.

With File

In this scenario, the endpoint is invoked with a file. The media type used is multipart/form-data. The name of the form-data for uploaded file should be "file". The code of the data file set in which the file will appear as data file can be provided as "fileSetCode". If the data file set code is not provided, the system generates a unique code itself. The URL used to invoke:

http://<host>:<port>/<context-root>/exchanges/<type>/<code>

The following is an example:

POST /upload?upload_progress_id=12344 HTTP/1.1
Host: localhost:3000
Content-Length: 1325
Origin: http://localhost:3000
... other headers ...
Content-Type: multipart/form-data; boundary=----WebKitFormBoundaryePkpFF7tjBAqx29L

------WebKitFormBoundaryePkpFF7tjBAqx29L
Content-Disposition: form-data; name="fileSetCode"

uniqueFileSetCode

------WebKitFormBoundaryePkpFF7tjBAqx29L
Content-Disposition: form-data; name="file"; filename="hello.o"
Content-Type: application/x-object

... contents of file goes here ...
------WebKitFormBoundaryePkpFF7tjBAqx29L--

It is also possible to add an exchange description to provide context to the integration invocation. The value for description can be provided by specifying a request parameter called "descr".

Invocation and Integration Parameters

For invocation that uses parameter, the Integration may specify list of integration parameters essential for integration invocation. If values are not assigned to these parameters explicit at the time of invocation, system assigns the default value provided by the parameter configuration and starts the exchange.

In addition, if such an integration parameter is marked mandatory then, system expects that a value is assigned to it. If value for a mandatory parameter is not present ( and no default value is defined), then exchange invocation fails with error OIG-GATE-038

Response

All the above operations are asynchronous in nature. The successful invocation of the configuration returns back a link to be able to poll/get the status of the invoked configuration. Status code 201 along with the following link is returned in the location header.

http://<host>:<port>/<contextRoot>/generic/exchanges/{exchange-id}

Recover an Exchange

If an exchange fails or times out, it is possible to recover the exchange by sending a POST request to the following url:

http://<host>:<port>/<context-root>/exchanges/{id}/recover

Recovery of an exchange means to start the flow where it failed, hence it will try to process the first exchange step that is either Failed or in Initial status.

Sign-off an Exchange

If an exchange delivers through an agent, the agent is responsible to signoff the integration, after it has delivered to the respective place or file folder. The following POST operation assists in that.

http://<host>:<port>/<context-root>/exchanges/{id}/signoff

Signoff means that the integration is marked as Completed.

Fail an Exchange

If an exchange delivers through an agent, the agent is responsible to signoff the integration, after it has delivered to the respective place or file folder. If something goes wrong in this process, the agent marks the integration as failed to get the failed message to the operator. The invocation of this operation is done along with the error text that is stamped on the exchange when you send a POST request to the following url:

http://<host>:<port>/<context-root>/exchanges/{id}/failure

With this operation, the exchange is marked as Failed, with the current exchange step marked as Failed with the error text specified in the invocation. A user can issue a failure operation to fail an exchange.