Linking the swagger to your connector

For any REST connector, the green button is available for you to link a swagger.

The first time you use the Swagger Load tool the pop-up below will prompt you to either upload a .json or .yaml file or to point to a URL for the Swagger file you wish to use.

Once this is done and the Swagger document has been loaded against the connector, when you view the connector in the Connector screen you will see the BOTH button will be pink and an extra button will appear in the ACTION column.

Using the swagger to generate configuration

You can access the Swagger Load tool within the Orchestration Manager. It will appear if the Connector you have selected is REST. If not, it will not appear.

If you have previously loaded and used a Swagger file, when you click on ‘Generate Endpoint from Swagger’ it will bring up the most recently loaded Swagger (example below). If you want to use a different Swagger, click on ‘Load New Version’.

The Connector Swagger Manager popup (above) will show all API Transactions available within the Swagger file. You can use the radio buttons to select the API Transaction you want to generate you config for.

Below, you can see the ‘API Transaction’ selected is ‘Find Pet by ID’ and you are then given the option to define the Request and Response content types depending on what the API Transaction chosen supports.

You then click ‘Generate’ to create the configuration for this leg of your Orchestration. You then simply need to clear the validation warnings by setting the Parameter Names to use for each Parameter on the Request and Response.

How do response handlers work?

Handlers can be added to any Inbound API Request or Response or any downstream system Response.

• A Handler on an Inbound API Request could for example trigger the routing of the request to another Inbound API on the same GLU.Engine.
• A Handler on an Inbound API Response could trigger the flow to be re-routed
• A Handler on an API response could based on a parameter matching a certain value overwrite the parameter with another value.
  

A Handler on the Response to an outbound Connector call is the most widely used mechanism for orchestrating your flows.

Within the Orchestration Manager, Handlers can be configured based on response Content, HTTP Status Codes or response conditions. When the handler conditions specified in the handler are met, the defined Handler Action will be triggered. The appropriate configuration box is displayed depending on the action specified.

The Response Handler can be used to end a transaction or result in a different outcome or Response to the Initiating System.

Handler Conditions

Handlers can be configured to run based on:

• Parameter values
  
• HTTP Status Codes
  
• Expressions – used to trigger the processing of a Expression in a flow
  
• Or ‘none’ – if you just want to trigger a routing event at a point in the flow use the ‘None’ category for you Handler.
  

Important notes on handlers: 

• Handlers are always executed in order first to last, so ensure your logic handlers are ordered correctly.
  
• The value in the condition cannot contain a function or formula. If required, use a Derived Parameter to apply a function or formula, then reference the Derived Parameter in the Handler Value.
  
• Note that if for example you have a set of 3 status codes all of which should result in the same handler condition being applied, you can list all three codes in the ‘Value’ field e.g. 1000, 1001, 1002

Parameter Handler

If the Parameter specified via the ‘Name’ dropdown box passes the comparison check (or other boolean operation) specified by the ‘Condition’ dropdown box, it’ll trigger the ‘Action’.

HTTP Status Codes

The GLU Engine needs to specifically be told to handle unsuccessful HTTP status codes (e.g. 400, 401, 500 etc). This is done by adding a status codes handler. Without this handler, the GLU Engine is unable to unmarshall the response payload. Ensure that you create the required HTTP status code handlers in order to orchestrate or unmarshall.

None Handler

A ‘none’ handler means that no triggering event, code or parameter value needs to be present but that the handler will ALWAYS be executed.

Handler Action Types

Route To

Routes the request to a specific flow code.

Send to Many Routes

Routes all requests to the specified flow codes.

• Parallel Processing: If enabled then sending messages to the recipients occurs concurrently. Note the caller thread will still wait until all messages have been fully processed before it continues. It’s only the sending and processing the replies from the recipients which happens concurrently.
  
• Stop On Exception: If checked Requests will fail if there’s an exception on any of the flow codes. In all situations, the recipient list will stop further processing. This is the same behaviour as in the pipeline, which is used by the routing engine. The default behaviour is to not stop but continue processing till the end.
  
• Timeout: Sets a total timeout specified in ,milliseconds, when using parallel processing. If the Recipient List hasn’t been able to send and process all replies within the given timeframe, then the timeout triggers and the Recipient List breaks out and continues.
  

Stop Process

This forces the process to stop and the message gets processed back through the Response Manager. Either the Stop Process can trigger a ‘successful’ response back, alternatively, it can trigger an error template. The error response is comprised on an ‘Error Code’ and an optional ‘Error Message’ describing the error in detail. The error code and error response values will be mapped into the parameter values are that are specified as the response parameters as below.

Overwrite Parameter

‘Overwrite Parameter’ Action will always take place at the step in the flow at which the Handler resides BEFORE any other Handler rules are applied such as a ‘ROUTE TO’ redirection handler. This means that even if the sequence of Handlers has ROUTE TO handlers pre-ceding ‘OVERWRITE’ handlers, the ‘OVERWRITE’ handlers will always be run and only thereafter will the ‘ROUTE TO’ handlers be run – in the order in which they are placed in the list of Handlers (top-down).

The parameter can be overwritten with a value or with other parameter, below some examples:

• Overwrite parameter with a value, e.g. text: HelloWorld or Int: 123 ..etc
  
• Overwrite parameter with GLU static parameter, e.g. ${GLUstaticParam}
  
• Overwrite parameter with other parameter, e.g. ${otherParam}
  
• Overwrite parameter with derived parameter,e.g. ${derivedParam}

Data which is saved in the cache will be available to all APIs in the GLU.Engine.

To reference cached values, use the following GLU Reserved Words in a Derived Parameter:

• SET_DATA_TO_CACHE
• GET_DATA_FROM_CACHE
• GET DATA FROM CACHE CONTAINS
• GET MAPPED ARRAY FROM CACHE

Retry on Timeout

Step 1: Set the timeout value

On the outbound request as shown below, the timeout value needs to be set in milliseconds.

Step 2: Set the Handler rules

On the Outbound Response a Handler can be added to determine the retry rules. When the timeout is triggered, this Handler will facilitate the retry:

• The name of the retry Handler.
• Select the ‘none’ option in the Response Handler Control Panel.
• Select the ‘Retry on timeout’ Action in the dropdown.
• Enter the Retry Count: The number of times the retry will attempt to send the transaction
• Enter the Retry Delay: Each retry will be sent with a delay of x milliseconds.

Step 3: Response after retry attempts

During the retry process, the GLU.Engine will either receive a response from the third party, or it will complete the retry attempts and then send back a timeout response. The timeout response that is sent back will be as per the configuration in the response control panel. The Timeout Response Code and Timeout Response Message are configured as below.

Retry on a specific response parameter value

Step 1: Set the handler rules

An outbound response handler can be used to determine the retry rules for a transaction. When a particular condition is met, this handler will facilitate the retry.

Once the retry handler is processed, the rest of the handlers in the orchestration will be processed (i.e. Retry handlers are first to be processed.)

Note: the condition’s value can be one value or multi values separated by a comma e.g. ValueOne,ValueTwo,ValueThree….. etc

Route to a new flow code on Timeout

One is able to have two orchestrations setup for timeout such that you first ‘Retry’ upon TIMEOUT and thereafter you can ‘Route to’ upon TIMEOUT. To route to a different Flow code upon a timeout, configure the Handler as outlined below.

Step 1: Set the timeout value

On the Outbound Request as below, the timeout value needs to be set in milliseconds.

Step 2: Set the handler rules

• The name of the retry handler
• Select the ‘none’ option in the response handler control panel
• Select the “Route to on timeout” Action in the dropdown.
• Flow Code: Select the flow code of the transaction that you want to route to when a timeout is triggered from within that transaction.

Retry delivery counter variable

The GLU_REDELIVERY_COUNTER is a variable that increments with each retry attempt sent by GLU. It provides a count of the number of iterations that the retry process completes. This needs to be set up in the derived parameter, see example below:

Example: Transaction – to – Transaction routing

Diagram Example: It is possible to have the API request handler redirect the transaction flow to the “Balance Enquiry” transaction.

When setting this up, the Flow Codes drop down box will show all the flow codes in the API.

Example: Orchestration – to – Orchestration routing

Diagram Example: A response handler can redirect the flow to a different orchestration – e.g. the “Insert Endpoint Response into Database” Orchestration.

Example: Orchestration – to – Transaction routing

An orchestration can route to another transaction within the integration. Important to note here the connector setup is important.

1. Setting up the response parameters needed
2. Then processing any necessary logic on the response

To streamline the process of setting up response parameters, especially when dealing with different connector types, you can utilise the Generate Parameters from Template tool. This tool allows you to input a response payload sample, which it then uses to auto-generate the entire response payload along with any associated object or collection path mappings. This means that the tool creates the full parameter set and unmarshalling paths automatically, unless you specify otherwise.

Once the response parameters are set up, you can create response handlers to perform specific logic on the received response from the downstream system. These response handlers enable you to customise how the response is processed and what actions are taken based on its content.

Each step in the flow to a downstream system is defined by the Request that the GLU.Engine will send and the Response it will receive via the pre-configured Receiving System Connector.

Each step has several possible configuration fields:

Flow Code

• Used by Handlers to redirect the transaction flow to specific Flow Codes.
• This allows for non-sequential orchestration flow, independent of the sequence in which transaction steps with receiving systems are defined in the Console.
• Example: ‘db1’ is assigned as the Flow Code.

Exclude from Build

• This enables exclusion of the connection defined by this Flow Code from the build. It’s important to note that if this option is selected you won’t be able to route to Flow Code via this build.
• It’s useful when building a GLU.Engine and the connector is not needed in the current version.
• If ticked, the connector will not be included in the build or GLU billing.

Async

• If selected, the route will be executed asynchronously alongside other routes.
• By default, all routes are performed synchronously.
• Note: The flow between routes can be altered using Handlers, but routes marked as ‘Async’ will be invoked regardless of Handlers.

Process

• Marking an orchestration as ‘Process’, indicates that it will solely handle logic and routing via Handlers.
• There is no outbound request and response available on a Process orchestration.

Is StreamCall

This process is in Beta development with GLU.Ware team. Further descriptions will follow in later releases of GLU.Ware, however if you are interested in using streaming connectors please speak to GLU support.

Connector

• Refers to possible pre-defined Connectors for the Receiving System.

These configuration fields provide flexibility and control over the orchestration flow, allowing you to tailor the behaviour of each transaction steps to meet your specific integration requirements.

Content Type refers to the format and structure of the data being sent or received as part of a message, while connector types and protocols determine how the message is transmitted from one system to another.

The relationship between content types and connector types/protocols comes into play when sending or receiving messages. For example, if you want to send a message containing JSON data over HTTP, you would need to use an HTTP connector and set the content type of the message to application/json so that the receiving system knows how to interpret the data.

GLU connectors support various content types for messages, which can be specified using the Content-Type selector. The following are the content types that GLU supports:

• text/plain
• application/xml
• application/json
• application/octet-stream
• multipart/form-data
• application/x-www-form-urlencoded
• application/soap+xml
• application/atom+xml
• application/rss+xml
• application/pdf
• text/xml; charset=UTF-8
• application/xml; charset=UTF-8
• application/jose

text/plain

This is used for plain text messages like emails or SMS.

application/xml

This is used for XML documents used in data exchange. It can be specified as application/xml or text/xml. In GLU, you can use either of these to specify the content type of XML documents being sent as part of a message to an external system or API. The application/xml type is more commonly used, and it indicates that the content of the message is an XML document. The text/xml type is also valid, but it is less commonly used and has the same semantics as application/xml.

application/json

This is used for JSON documents, commonly used for data exchange.

application/octet-stream

This is used for binary data like images or audio files.

multipart/form-data

This is used for submitting data including binary data, like file uploads.

application/x-www-form-urlencoded

This is used for submitting form data encoded as key-value pairs, similar to how HTML form submissions are handled. It’s important to note that parameters included in this content type cannot contain special characters. In order to encode these, you can apply the following function to the parameters before sending them on an outbound request. 

Note: All body parameters must be included in the request template, separated by the “&” delimiter, with no spaces between parameters and the delimiter.

application/soap+xml

This is for SOAP messages, commonly used in web services communication.

application/atom+xml

This for Atom feeds used to syndicate web content.

application/rss+xml

This is for RSS feeds used to syndicate web content.

application/pdf

This is used for PDF documents that is a popular file format used for document exchange, widely supported by various software applications and platforms. In GLU, you can use the application/pdf content type to send PDF documents as part of a message to an external system or API.

text/xml; charset=UTF-8

This means that the message contains XML documents encoded in the UTF-8 character set. When we use the text/xml media type, it’s a way of saying that the XML document is treated as plain text. We specify the character encoding of the document using the charset parameter. However, it’s more common to use the application/xml content type to indicate an XML document, and you can still specify the character encoding using the charset parameter. So, application/xml; charset=UTF-8 is another way of indicating that the message contains an XML document encoded in UTF-8.

application/xml; charset=UTF-8

Is a valid content type that indicates that the content of the message is an XML document encoded in the UTF-8 character set. The application/xml media type is used to indicate that the content of the message is an XML document, and the charset parameter is used to specify the character encoding of the document.

application/jose

application/jose is a recognized content type designed for handling encrypted and/or signed JSON data. JOSE (JSON Object Signing and Encryption) comprises a set of standards defining methods to secure data using JSON format. It facilitates digital signing, encryption, and authentication of JSON data, enhancing security for inter-system and inter-service communications. In GLU, application/jose serves as the content type for transmitting and receiving JOSE-formatted messages. GLU effectively manages JSON Web Tokens (JWTs) and JSON Web Encryption (JWE) messages. It supports tasks like JWT creation, verification, and decoding, as well as encryption and decryption of JWE messages. When dealing with signed messages, the “alg” parameter specifies the signing algorithm, while for encrypted messages, the “enc” parameter indicates the encryption algorithm in use.

It’s important to note that there are several other media types associated with JOSE, including application/jwt for JSON Web Tokens, application/jwe for JSON Web Encryption, and application/jws for JSON Web Signatures. These media types are utilised to denote specific types of JOSE messages and may include additional parameters for specifying algorithms and other metadata.

The Receiving System API specification will define details like the Context Name, Method, and Content Type to be used for the request. This definition can be different depending on the connector protocol. For more information, go to APIs and Connectors for more details.

When variables are included in the context name, refer to the section on URL Path Variables 

Remove namespace

The “remove namespace” checkbox will remove namespace references from an outbound orchestration XML request. For instance, the payload will undergo transformation as illustrated below: 

In the original payload, the elements (root, element1, element2, element3) are prefixed with the namespace ns defined in the XML namespace declaration xmlns:ns="http://example.com/ns". This namespace declaration associates the ns prefix with the namespace URI "http://example.com/ns".

In the transformed payload, the namespace prefix ns has been removed from all the element names. This transformation effectively removes the namespace from the XML structure, resulting in simpler element names (root, element1, element2, element3) without any namespace prefix.

Timeout

A timeout can be set on each orchestration request. By default, a connector timeout is set to 60sec. Should you wish to specify a timeout for this specific request, a millisecond timeout can be set here.

Change Request To

The “Change Request To” dropdown offers three options for modifying the request sent to the receiving system:

• Don’t Change: Sends the request according to the request template/parameter configuration.
• Pass Source Request: Passes through the incoming API request payload.
• Pass Saved Responses: Allows you to pass a saved response from a previous orchestration where it has been saved under ‘Save Response As’. In the image below, the WalletResponse has been saved:

You could then reference WalletResponse in the ‘pass saved response’ option on the outbound orchestration.

Authentication

If authentication is required by the receiving system, choose the appropriate pre-defined Auth Code from the provided list. Refer to the Authentication Collection for additional details.

Request Templates

If the Receiving System expects the message payload to be provided in a specific format, the template for such format (as defined within the Receiving System API Specification) should be used to populate the ‘Template’ field within the Request Manager Control Panel.

Remove Saved HTTP Cookies

For HTTP connectors, this feature enables the removal of cookies on outbound requests. Singular or Multiple cookies can be removed by specifying their names with comma delimiters. For example, xSessionID,yMonitorId

Enabling Thread Pool

A throttle can be applied to limit the number of transactions per second delivered to a specific receiving system. This is potentially useful when the receiving system faces performance or capacity bottlenecks.

Remove GLU Headers

By default, when sending a request to an outbound endpoint, the following headers are added:

• GLU_TRX_ID, TRACE_ID, GLU_ID

When the ‘Remove GLU headers’ selection is made, the above headers will be removed from the outbound request.

If selected, it instructs your GLU.Engine to pick up the final Response it received from an Outbound Connector call and to pass that response ‘as is’ back in the API Response. The response will be completely unchanged.