Web Services Integration

1 About Web Services

A Web Service is basically a process that is standing by, waiting to do something for you once your program makes an internet connection and tells it what to do. The service might be to retrieve information or store it, perform a procedure on a remote server, take an order, or perform any other task that can be programmed.

Both SOAP- and REST-based services can be integrated into the platform without programming, by performing a few configuration steps.

1.1 Simplifying a Web Service for Designers

In addition, the service interface can be simplified, so it easier to use by a business analyst or application designer. To do that, you can:

• Ignore parameters that are not needed
• Hardcode data for parameters whose values are fixed
• Create more friendly names for the remaining parameters

For example, a web service that concatenates three fields ("field_1", "field_2", and "field_3") can be configured so that the designer sees it as a service which concatenates "first_name" and "last_name" to create "full_name", where "field_2" is hardcoded with a string that contains a single space.

Those steps are covered below, under Configuring a Web Service.

1.2 Using a Web Service

Once configured, the Web Service can be utilized for an External Lookup or an External Data Source. It can also be added as step in a Process. The designer can then use the application-friendly names to:

• Map current record fields to and from input and output parameters
• Specify fixed values or expressions for input parameters
• Define expressions that operate on output parameters and store the results either in the record, or in process variables that can be used in downstream steps.

Those mechanisms are discussed further below, under Working with a Web Service.

For a service that requires an initial login, you can set up two services: One for the login, and one to make the actual request. That process is covered later, in Configuring a Two-Step Service Chain)

1.3 Web Service Execution History

If web service execution fails, an entry is placed in the Audit Log. That entry can be examined to see precisely what request was made, and what happened as a result.

In addition, a Debug flag can be set in the service parameters for a Web Service. That flag causes all Web Service inputs and outputs to be recorded in the Audit Log, to expedite debugging.

Learn more: Audit Log#Web Service Executions

2 Managing Web Service Configurations

2.1 Setting Up a SOAP Web Service

A SOAP Web Service has connection settings that are specified using the Web Service Description Language (WSDL).

Prerequisite:

• A WSDL file, or the URL that can be used to access it.

  The WSDL provides the data needed to set up a connection.

  Web Services managed by the WebMethods integration server are recommended.

Upload the WSDL file:

1. Go to > Developer Resources > Web Services
2. Click [New Web Service]
   The SOAP tab is active, by default.
3. Do one of the following to read the WSDL file:
   • Click [Select WSDL], browse to the folder that contains the file, and upload it, or
   • Enter a URL in the text box and click [Download]
     The Web Service Configuration form appears.

1. In the Web Service Configuration form, configure the connection:
   • Basic Parameters:

   • Title - Required. Give the service a name. (Displays in the Name column of the Services list.)
   • Operation

     Required for a SOAP service. Not present for REST.

     Choose one of the operations defined in the WSDL file.

   • Version - Required. Enter text to identify the service version
   • Pipeline Service

     Check this box for a service that provides values for use in other web services.

     Any outputs from it that are made available for mapping can be used as inputs to other web services.

     Use it, for example, for APIs that be accessed only after logging in. You create a service that logs in and retrieves the cookie value or other access key required for subsequent requests. (That "two-step service chain" will be described in more detail, shortly.)

   • Debug

     Check this box to record successful executions of a Web Service in the Audit Log, in addition to the standard recording of service errors.

   • Service Parameters:

   • URL - Optional for SOAP (used to point to a destination other than one specified by the WSDL). Required for REST.
   • Use Basic Auth - Check this box when the destination URL requires a username and password to be included in the standard http header.

   • Username - Optional. Username required to use the service, when needed
   • Password - Optional. Password required to use the service, when needed

   • Use a Pipeline Service - Check this box when the service request requires information from a prior service. (For example, a session ID or other access key.)

     Select a pipeline Web Service defined earlier for use in a two-step service chain.

   • TTL - Optional. The "Time to Live", in milliseconds.

     The amount of time the platform waits before abandoning a request.

2. When done, click [Next].

You can now proceed with Configuring Inputs and Outputs for the Web Service.

2.2 Setting Up a REST Web Service

2.2.1 Define Service Parameters

Start by providing data necessary to set up the service:

1. Go to Configuration > Developer Resources > Web Services.

2. Click [New Web Service]

3. Click the REST tab.

4. Provide the initial data needed to set up a service:

• Header Parameters

  Specify a comma separated list of parameters to be included in the http header.

  Parameters specified here become configurable inputs to the service.

  (The values are included in the request header, rather than in the request body. In subsequent steps, you provide values for them.)

  For example, to access an AgileApps Cloud platform REST API, the header specifies content type, it must include a session cookie, and it can optionally specify the data format to return (XML or JSON), so the header parameters would be:

  Content-Type,Cookie,Accept.

• URL

  Specify the URL for the REST resource.

  All elements in the URL--including path elements and query parameters--become configurable inputs to the service. Enter the appropriate information in the following fields and click Next.

Best Practice: Specify all reasonable query parameters in the URL, and then hardcode the default values for those parameters when configuring the input mapping. The effect is the same as leaving them out (since you are specifying defaults), but you will have the ability to change the mapping later, if you need to. Under the Configuration > Customization > Custom Template Variables page, you can create a custom template variable to configure the host/path/query parameters of a web service. For any path element or query parameter that could reasonably change, specify a custom template variable name, rather than an actual value. If you have a test server and a production server, for example, it makes sense to specify: http://domain/... rather than http://localhost/... Both URLs let you configure the domain, but the former lets you specify it in a more readable way--as domain=testServer, for example, or domain=production. Also, one more advantage of using a custom template variable for the web service configuration is to reduce the number of web service creations as the custom template variable mapping gives the flexibility of modifying the web service configuration based on their values. The Web Service Configuration page now allows you to perform the input field mapping with the custom template variables. To see the steps, you can refer to Step 5.

• HTTP Method

  Specify the HTTP request type: GET, POST, PUT, or DELETE.

  By convention, GET fetches data, POST adds data, PUT replaces data, and DELETE removes it.

• Sample Data Format

  Specify the type of sample data that will entered into the fields below (XML or JSON).

  This setting tells the platform how to parse the data, to determine the input and output parameters the Web Service defines.

• Request

  Provide an XML or JSON structure that exemplifies the one the service expects you to send.

  The entries defined in the structure become the data-configuration parameters for inputs to the service.

• Normal Response

  Provide an XML or JSON structure that exemplifies the one you receive.

  The entries defined in the structure become the data-configuration parameters for outputs from the service.

• Error Response

  Provide an XML or JSON structure that exemplifies the structure that is returned when an error occurs.

  This entry is required only when the error-response structure differs from the normal response. (It would not be needed for the platform's REST APIs, for example, because the platform's normal response always includes a result code and message.)

  The entries defined in the structure become the data-configuration parameters for outputs from the service.

5. The Input Fields Mapping page allows you to map the host and path/query parameters with the template variables you created on the Custom Template Variables page. The input fields are reflected based on the web service you used/created on the previous page.

For example: If you created a web service with the URL - https://dummy.restapiexample.com/api/v1/employee/1,

• you can create custom template variables as follows:
  
  • $custom.host is the custom template variable name for the hostname dummy.restapiexample.com
  • $custom.version is the custom template variable name for the version name v1.

• the input fields mapping will be as follows:

Field	Action	Parameters
protocol	Hardcode Selected by default	'https' 'https' is the protocol of this web service.
host	Hardcode Selected by default	$custom.host You must provide this template variable name created with the hostname on the Custom Template Variables page.
api	Hardcode Selected by default	'api' This is one of the path parameters that are part of the web service URL. Provide the same value here.
version	Hardcode Selected by default	$custom.version You must provide this template variable name created with the version name on the Custom Template Variables page. This is one of the path parameters used in the web service URL.
employee	Hardcode Selected by default	'employee' This is one of the path parameters that are part of the web service URL. Provide the same value here.
%7Bid%&D	Ask for mapping Since the value of the query parameter has to be fetched accordingly and must be mapped, you must select this drop-down.	id This is the query parameter of the web service URL.

6. When done, click [Next].
The samples you entered are processed to set up the data structures for inputs and outputs for the Web Service, along with any Header Parameters you specified. The Web Service Configuration form appears.

2.2.2 Configure Service Parameters

You can now provide the data needed to configure the service. (Items that were processed to create this page are displayed in read-only form, for reference. Other elements can be edited.)

To configure the basic service parameters:

1. In the Web Service Configuration form, configure the connection:
   • Basic Parameters:

   • Title - Required. Give the service a name. (Displays in the Name column of the Services list.)
   • Operation

     Required for a SOAP service. Not present for REST.

     Choose one of the operations defined in the WSDL file.

   • Version - Required. Enter text to identify the service version
   • Pipeline Service

     Check this box for a service that provides values for use in other web services.

     Any outputs from it that are made available for mapping can be used as inputs to other web services.

     Use it, for example, for APIs that be accessed only after logging in. You create a service that logs in and retrieves the cookie value or other access key required for subsequent requests. (That "two-step service chain" will be described in more detail, shortly.)

   • Debug

     Check this box to record successful executions of a Web Service in the Audit Log, in addition to the standard recording of service errors.

   • Service Parameters:

   • URL - Optional for SOAP (used to point to a destination other than one specified by the WSDL). Required for REST.
   • Use Basic Auth - Check this box when the destination URL requires a username and password to be included in the standard http header.

   • Username - Optional. Username required to use the service, when needed
   • Password - Optional. Password required to use the service, when needed

   • Use a Pipeline Service - Check this box when the service request requires information from a prior service. (For example, a session ID or other access key.)

     Select a pipeline Web Service defined earlier for use in a two-step service chain.

   • TTL - Optional. The "Time to Live", in milliseconds.

     The amount of time the platform waits before abandoning a request.

2. When done, click [Next].

You can now proceed with the configuration of inputs and outputs, described next.

2.2.3 Set Up Inputs and Outputs

In this part of the setup process, you can simplify the service's data parameters for process designers.

Start by mapping input fields (fields going to the service):

1. In the hierarchy of fields that appears, click the [-] icon to collapse a section, click [+] to expand it.
2. For each input field, one or more of these options appears:
   • Ask for Mapping -

   (This option does not appear for a Pipeline Service.)

   Friendly Name - Give the WSDL field a name the application designer will recognize

   • Ignore - Ignore this value
   • Hardcode - Provided a hardcoded value for the field. (The application will never even see it.)
3. Click [Next]

Then map output fields (fields coming from the service):

1. In the hierarchy of fields that appears, click the [-] icon to collapse a section, click [+] to expand it.
2. For each output field, choose one of:
   • Ask for Mapping - Ask the designer to supply the name of a record field to store the value into.

   Friendly Name - Give the WSDL field a name the application designer will recognize

   • Ignore - Ignore this value
3. Click [Save]

The Web Service is now ready for use by an application designer.

2.3 Configuring a Two-Step Service Chain

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.)

2.3.1 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.

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.

2.3.2 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.

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.

2.3.2.1 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]

2.3.2.2 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]

2.4 Viewing and Modifying a Configuration

1. Go to > Developer Resources > Web Services
2. Click the Service name
3. Click [Edit]
4. Follow the steps described in the previous section to view the configuration and make changes.

2.5 Adding a New Version

1. Go to > Developer Resources > Web Services
2. Click the Service name
3. Click [Add New Version]
4. Follow the steps described earlier to add another version of the service.
   (Be sure to provide a value in the Version field.)

2.6 Testing a Service

1. Go to > Developer Resources > Web Services
2. Click the Service name
3. Click [Test Service]
4. Provide input values.
5. Click [Execute]
6. Output values are displayed

3 Working with Web Services

3.1 Invoking a Web Service in a Process

Once a Web Service has been configured, you can add it as a step in a Process:

1. Go to > Objects > {object} > Processes
2. Create a new process, or select an existing one and click the flow diagram to edit it.
   The process model editor opens.
3. From the palette, drag the element to Execute Web Service into the model
4. Fill in the parameters for this process step:
   • Name - Give the step a name
   • Web Service - Select one of the Web Services configured for the application

     If the service has a version identifier, it is displayed following the service name

     For example: Some Service [Version 2]

   • Input Mapping - For each field that goes to the service, choose one of the following, and then choose the WSDL field that the value goes into, from the list of friendly names defined in the Web Service configuration:

   • Use Object Field - Select a field from the current record
   • Use Fixed Value - Define a fixed value
   • Use Expression - Create an expression based on record fields. When the dialog opens:

     • Click Field to select a field in the record, or in a record referenced by a Lookup
     • Click the dropdown to select an operator
     • Click Function to select a Function
     • Click in the text area to enter a value
     • Click [Insert] to insert the result into the mapping field

   • Output Mapping - For each field that comes from the service, choose one of the following to specify a value:

   • Use WSDL Field - Select a WSDL output field from the list of friendly names defined in the Web Service configuration.
   • Use Expression - Create an expression based on WSDL fields. When the dialog opens:

     • Click Field to select a WSDL field
     • Click the dropdown to select an operator
     • Click Function to select a Function
     • Click in the text area to enter a value
     • Click [Insert] to insert the result into the mapping field

   Then choose one of the following to store the value:

   • Use Object Field - Stores the value in the current record.
   • Use Variable - Stores the value in a Process Variable.
     The variable can then be referenced later in a Process Model#Decision Switch.

5. Click [Save]
   When the process reaches this step, the Web Service is automatically invoked, and the specified data interchange occurs.

3.2 Logging In to a Web Service

Some Web Services require a separate log-in step before resources can be accessed. That behavior is typical of REST services, and applies to some SOAP services, as well.

For such services, create a two-step process:

• The first step invokes the service's log-in resource
• The second step invokes the data-interchange resource

The trick is to capture the login-verification data returned in the first step as one or more Process Variables, and use it in the subsequent step.

3.2.1 Example: Logging in with the AgileApps Cloud platform REST API

The AgileApps Cloud platform login resource returns the current session ID as a parameter. That value needs to be included in the session cookie when a REST resource is accessed. This example shows how the task can be accomplished.

The data structure returned by the login resource looks like this in XML:

<platform>

<login>

<sessionId>...(ID value)...

So the path to that value in the returned data structure is platform.login.sessionID

Here, an expression is created using that value, in the form it will be needed next (JSESSIONID=123456789):

The expression created in the login step is then included in the cookie header parameter when accessing a data resource:

3.3 Invoking a Web Service From a Rule

1. Create a Process that invokes the web service, like the one shown here:

   

   (If needed, add an initial step that invokes the service in order to log in.)

2. Create a Process that uses the Process Model.
3. Launch the Process from a Rule

3.4 Invoking a Web Service using an API

1. Create a Process that invokes the web service, like the one shown above.
   (If needed, add an initial step that invokes the service in order to log in.)
2. Create a Process that uses the Process Model.
3. Create an Event Rule that launches the process.
4. In the code that is using the REST or Java API, trigger the event to launch the process.