Web Services Integration

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.

A Web Service whose connections are specified using the Web Service Description Language (WSDL) can be integrated into the platform without programming, by performing a few configuration steps.

In addition, the interface defined by the WSDL can be simplified by the IT admin, so it more closely matches the application:

• Ignore fields that are not needed
• Hardcode data for fields whose values are fixed
• Create more friendly names for the remaining fields defined in the WSDL

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

Once done, an application designer can add a step in a Process to utilize the Web Service. The designer then uses the application-friendly names to:

• Map current record fields to and from WSDL input and output fields
• Specify fixed values or expressions for WSDL input fields
• Define expressions that operate on WSDL output fields and store the results in the record

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

Managing Web Service Configurations

Setting Up a SOAP Web Service

Start by uploading the WSDL file:

1. Download the WSDL file for the service the application will connect to.
   (Web Services managed by the WebMethods integration server are recommended.)
2. Go to > Developer Resources > Web Services
3. Click [New Web Service]
   The SOAP tab is active, by default.
4. 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]
5. In the form that opens, configure the service connection:
   • Basic Parameters:

   • Title - Required. Give the service a title. (Displays in the Name column of the Services list.)
   • Operation - Required. Choose one of the operations defined in the WSDL file
   • Version - Required. Enter text to identify the service version
   • Login Service - Check this box for a service that exists only to log in to a remote server. It will then be available for use in a two-step connection, which will be described in a moment.

   • Service Parameters:

   • URL - Optional. Use this field to point to a destination other than one defined in the WSDL file
   • Username - Optional. Username required to use the service, when needed
   • Password - Optional. Password required to use the service, when needed
   • TTL - Optional. The "Time to Live", in milliseconds. (The amount of time the platform will wait before abandoning a request.)

6. Click [Next]

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

Setting Up a REST Web Service

1. Go to > Developer Resources > Web Services
2. Click [New Web Service]
3. Click the REST tab.
4. Configure the service connection:
   • Header Parameters

     Specify a comma separated list of parameters that will be specified as inputs to the service.

     When the HTTP resource is accessed, those values are included in the request header, rather than in the request body.

     For example, to access an AgileApps Cloud platform REST API, the header needs to include a session cookie, and it can optionally specify the data format to return (XML or JSON), so the header variables would be: Cookie,Accept.

   • Content Type

     Specify the type of content that will be sent to the service (XML or JSON).

     The same type of data should used when entering sample Request and Response data in the sections that follow.

   • URL

     Specify the URL for the REST resource.

     Note: For a service that requires an initial login, you'll need to set up two services: One for the login resource, and one for the data resource you intend to access.

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

   • 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. Click [Process REST]
   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.

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

Configuring Inputs and Outputs for the Web Service

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 -

   • 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.)
   • Username - Supply the Username value defined in the initial configuration step when Basic Auth was specified for the service.($username).
   • Password - Supply the Password value defined in the initial configuration step when Basic Auth was specified for the service ($password).
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.

Setting Up a Two-Step Web Service

Some Web Services do not require login, or allow login credentials to be supplied along with the service request. For them you configure a single-step service, using either the SOAP or REST process explained earlier. Other REST services (like the platform's REST APIs), require a separate login step. That two step configuration procedure is described here.

Logging in generally sets up a valid session. The session ID is then included in subsequent requests as an authentication mechanism, for as long as the session remains valid. (It will typically timeout after a period of inactivity.) The details will vary from service to service, but that is the general picture.

Note: 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.

To configure a Web Service that requires a prior login step:

1. Set up a Web Service that will be used to log in to the remote server.
   • In the first configuration page, select Login Service.
   • Configure the inputs to the service
   • For the outputs that need to be included in subsequent requests, __TBD__.

2. Set up the Web Service that will be used to make the service request.
   • Check the Login Service box.
   • Select the
   • For the inputs that need to be provided by the login service, __TBD__.
   • Configure other inputs and outputs normally.

3. Click [Save]

Viewing and Modifying a Configuration

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

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

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

Working with Web Services

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, and then choose the record field to store the value in:

   • 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

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

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.

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:

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

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.