Outbound REST

There are the following supported methods for sending REST messages:

• Send resource content
• Send REST event

Note:

Both options support OAuth 2 Client Credentials flow via the External System configuration.

Send Resource Content

The capability exists to send messages containing the resource content for each supported resource. The message format will follow that of the "transmissions" resource currently used for inbound BATCH asynchronous messages. Initially, though, only a single transaction will be contained in each outbound transmission although the capability to support multiple transactions (e.g. triggered by Staging Processing) will be extended in a future version.

The outbound capability will be triggered and managed identically to the current outbound Transmission XML notification using the same Agent actions, External Systems records and Transmission Manager. The selection of the REST resource format will be made by using the new REST Communication Method in the corresponding selection list for the integration action and by specifying the "application/json" Content Type on the target External System record.

The resource format used will be equivalent to a "GET" of the root resource with the "expand=all" parameter. The capability to use custom formats will be added in a future version.

The HTTP success codes, 2xx, indicate a successful receipt of the message, although a synchronous response message in the format of the "transmissionStatus resource, can provide more information. The process flags related to "Transmission Ack" apply to the "transmissionStatus" response.

Note:

Not all business objects supported for outbound Transmission XML are also valid as REST resources, e.g. Tender Offers. Only resources valid as inbound root resources can be sent outbound. In addition, the "serviceProviders" inbound resource will not be available as an outbound resource in this release. This will be addressed in a future release.

Send REST Event

The capability exists to use an Agent action, SEND REST EVENT, to send a lightweight "application/json" content type event notification message to an external system. The intention is then for this to be used to retrieve resource data via a subsequent GET request based on the content of the event message. In this way, specific fields can be retrieved rather than sending unnecessary data as part of a full resource message.

Note:

It is extremely important that this new action SHOULD NOT be used as part of a long running agent process and should ONLY be used in an agent that is triggered by an event with the "Create New Process" option selected. The outbound REST event is a synchronous call and is required to complete quickly; in order of one or two seconds. If this constraint is not enforced then there may be a negative impact to other upstream processes.

Example event message:

{
   "event" : "LOCATION_EVENT-MODIFIED",
   "referenceValue" : "12345678",
   "sendReason" : "Location name change",
   "resourceUrl" : "logisticsRestApi/resources/v2/locations/GUEST.LOC_GID1"
}

Action Field	Property	Description
N/A	event	This is a concatenation of the agent event notify function, "-" and notify sub function.
External System	N/A	The target system containing authentication and target URL information.
Reference Value	referenceValue	Intended to contain some value from the object involved in the triggering event. For example, can be static text or an agent variable assigned to the result of a Saved Query which selects a particular reference number value.
Send Reason	sendReason	A textual description of the context of the event. May also contain agent variables.
Override Resource Name	N/A	Used to override the default root resource name determined from the PK of the object receiving the event.
N/A	resourceUrl	A relative URL for the root resource involved in the triggering event. Needs to be combined with the external server URL for any subsequent GET.