AgileApps Support Wiki Pre Release

Service Chain

From AgileApps Support Wiki

A service chain is a configuration of Web Services that operate in a defined sequence, where the outputs from one are available for use as inputs to the next. (Such a sequence could also be called a service pipeline.)

About Service Chains

Some Web Services (like the platform's REST APIs), require a separate login step. The configuration procedure for that two step connection is described here. For Web Services that do not require login, or that allow login credentials to be supplied as part of the request, you can configure a single-step service using either the SOAP or REST process explained earlier, and configure the Basic Auth parameters, as needed. But for a login-controlled service, a two-step connection makes sense.

In addition to supplying credentials for login-controlled services, there are other scenarios in which a service chain is useful:

  • Get an access key of some kind.
In a banking system, for example, a routing number and account number might be supplied to get a one-time authorization key for a single transaction.
  • Get other data required by the next step in the chain.
In a commodities purchasing system, for example, one service might get the current price. That value could then be fed into a another system that gets the current exchange rate for the customer's currency. That combination of values would determine how much could be purchased for a given amount.

Thumbsup.gif

Best Practice:
It is possible to set up a two-step sequence in a Process Model. But it is generally wiser to define the steps in the Web Service configuration, for a number of reasons:

  • If configured in the process model, the steps need to be repeated in every process that accesses the service. As part of the Web Service, on the other hand, the configuration is done only once.
  • With the service configured, process modelers don't need to worry about protocol details. They can focus their attention on the business problem they are trying to solve.
  • In addition to being available for use in a process, a two-step service can be used for an External Lookup or as an External Data Source.

However, it multiple requests are needed, process steps might be more efficient, as the login occurs only once.

Create a Service Chain

A two-step service chain consists of a pipeline service and an endpoint service. A pipeline service makes outputs available to other web services. An endpoint service, on the other hand, uses a pipeline service for one or more of its inputs.

Considerations
  • The maximum number of links in the chain is two (hence the term, "two-step chain").
  • The inputs to the pipeline service must be hardcoded values or expressions.
  • A pipeline service can be accessed only by other Web Services. It is not available for use in other contexts.
  • An endpoint service is available for use anywhere that a normal single-step service can be used--for example, in a Process, an External Lookup, or an External Data Source.

Notepad.png

Note: In the steps that follow, the platform's REST API is used as an example. In that context, logging in sets up a valid session. The session ID is then passed to subsequent requests in the form of a cookie--a string that contains one or more values in an pre-defined format. (In other words, the session ID is the access key the platform needs to respond to a request.) The details will vary for any particular service, but that is the general idea behind a login-controlled service.

Set up the Pipeline Service

For example, set up the service that will be used to log in to a remote server.

  1. Give the Web Service a name (the Title).
  2. Configure the header parameters.
    For a platform REST request, for example, you would enter Content-Type,Accept
    to specify the format of data that is sent and returned (xml or json).
  3. In the first configuration page, click Pipeline Service.
  4. Configure other parameters (for example, Basic Auth, if applicable).
  5. Click [Next]
  6. Configure inputs that are required to login.
  7. Click [Next]
  8. Configure outputs from the Web Service
    For the outputs that need to be saved for use in subsequent requests, select Ask for Mapping.
    From the platform's REST login resource, for example, you would save the sessionId value, and perhaps give it the friendly name, "Session ID".
  9. Click [Save]
Set up the Endpoint Service

This service makes the actual request.

  1. Give the Web Service a name (the Title).
  2. Configure the header parameters.
    For a platform REST request, for example, you would enter Content-Type,Cookie,Accept
    where the cookie parameter will contain the session ID, and the other parameters specify the format of sent and returned data (xml or json).
  3. Configure inputs provided by the login service.
    Those values can be selected in the list of actions available for each input parameter, along with other options like Ask for Mapping, Hardcode, and Ignore.
    For example, to provide the session ID in the cookie format expected by the platform REST APIs, you would
    a. Map the input Cookie parameter.
    b. From the action list, select the Session ID parameter saved by the Login service.
    That selection inserts the data path into the field: platform.login.sessionId
    c. Create an expression that matches the cookie value expected by the platform:
    'JSESSIONID='+platform.login.sessionId
  4. Configure other inputs and outputs normally.
  5. Click [Save]