Web Service Lookup Example

CSM Prompts can read an XML or JSON collection and display the values in a lookup table grid from an entire row or from selected fields in the collection. This allows users to easily select and use information from third-party web service calls.

Overview

For example, create a One-Step™ Action that calls a web service, stores the JSON result in a variable, and then uses the result to create a web service lookup table from which users can select a value. The values returned from web service and web service lookup results can be parsed to populate Business Object fields, make additional web service calls, or used as a Token in other actions.

This example uses the Edmunds Vehicle API web service. The API and any data from it were used in accordance with the Edmunds Vehicle API Terms of Service for purposes of this example only.

To create a web service lookup:

Run a One-Step Action (from a button or link).
Enter a 4-digit year into the first Prompt.
The web service returns a web service lookup table with a list of vehicle makes and models for the specified year.
Select a vehicle make and model from the web service lookup table.
The selected make, model, and year are passed back to the web service to find available styles for the vehicle.
Select a style for the specified vehicle make, model, and year.
Use the value returned from this selection to populate Business Object fields, make additional web service calls, or create a Token for use in other actions.

The configuration for this workflow is in the following sections.

Set Up a Web Service

Set up a web service that returns a list of vehicle makes, models, and styles:

On the General page, define a name, URL, and service type for the web service.
Define web service methods for makes and styles.
Important: If the web service is configured to return results as JSON or XML, ensure that JSON or XML is selected as the result type in the web service methods.
The Makes method will return a list of vehicle makes and models by year. The API Key parameter is set to the key value required to access the API site.
The Get Styles method will return a list of styles for a vehicle by make, model, and year.

Call the Web Service Using a One-Step Action

Create a One-Step Action.
Add a Call a Web Service Action that calls the Edmunds Vehicle API and returns a list of vehicle makes and models by year (the user will be prompted to enter a year).
In the step details, select the General page and define a name for the action (example: Select a make and model).
1. Select the Edmunds Vehicle API web service created in the previous step.
2. Select the Store result as check box to store the result of the web service call as a variable. Provide a name for the variable (example: Select make and model result).
Select the Method page and in the Method drop-down list, select Makes.
1. Select year (Endpoint parameter).
  Note: The parameters are based on those defined for the web service methods when the web service was set up. The API Key parameter is set to the key value required to access the API site.
2. Select the Set Value option and then right-click in the Value field (or select the Token selector) to insert a new Prompt. .
3. Create a Prompt that asks users to enter a four-digit year.
  When the One-Step Action runs, and the user enters a year into the Prompt, the value of the year is passed as a parameter to the Edmunds Vehicle API web service. The web service returns (as JSON) a list of makes and models by year, which is stored in the Select make and model result variable.

Display Results in a Web Service Lookup

Use an Update a Variable or Stored Value Action with a Prompt to display vehicle makes, models, and year (selected in the first prompt) from the web service call in a web service lookup table, and then store the user's selection in a variable.

Add an Update a Variable or Stored Value Action to the One-Step Action and define a name for the Action (example: Update Selected Make and Model).
1. Select the Variable option, and define a name for the variable (example: Selected Make and Model). Select JSON as the Data Type.
2. In the New Value field, right-click or select the Token selector to insert a new Prompt.
3. Create a Prompt that displays the makes, models, and year (selected in the first Prompt) from the web service call in a web service lookup table. Ensure the Prompt type is text. The collection to step through must be a JSON or XML data type.
  Important: To display selected fields (example: make, model, and year) in the web service lookup, you must use the exact names of the columns in the JSON returned from the web service. If you are unsure of the exact names, you can select the Use all fields from collection check box to have a list of all columns returned and reference the exact column names to specify only those you want to display in the web service lookup table.
  When the One-Step Action runs, the Prompt will display the web service lookup table with the specified fields.
  Because the Return entire row as JSON option was selected when the Prompt was created, the entire row of JSON will be returned as the result when the user selects a row in the web service lookup table. The result is stored in the Selected Make and Model variable.
```
{
"makes.id": "200000081",
"makes.name": "BMW",
"makes.niceName": "bmw",
"models.id": "BMW_3_Series",
"models.name": "3 Series",
"models.niceName": "3-series",
"years.id": "200468552",
"years.year": "2014"
}
```

Obtain Vehicle Styles from Web Service

Use another Call a Web Service Action to return a list of styles for the vehicle make and model selected in the previous section (stored in the Selected Make and Model variable).

Add another Call a Web Service Action to the One-Step Action.
In the step details, select the General page and Define a name for the Action (example: Get Vehicle Details).
1. Select the Edmunds Vehicle API web service.
2. Select the Store Result As check box to store the result of the web service call as a variable. Provide a name for the variable (example: Get Vehicle Details result).
Select the Method page and in the drop-down list, select Get Styles.
1. For each parameter (make, model, and year):
  1. Select the Set Value option.
  2. Right-click in the Set Value field or select the Token selector to insert the Selected Make and Model variable (from the previous Update a Variable or Stored Value Action).
  3. Right-click the variable for each parameter and add modifiers to return the desired values from the web service.
    Make parameter: Obtain the makes.name value from the JSON result based on the user's selection in the web service lookup table.
    Model parameter: Obtain models.name value from the JSON result based on the user's selection in the web service lookup table.
    Year parameter: Obtain years.year value from the JSON result based on the user's selection in the web service lookup table.

Display Vehicle Styles in a Web Service Lookup

After defining the Action to call the web service for a list of vehicle styles, you can have the results displayed in a web service lookup and show the user's selection in a pop-up window.

Add a Show a Popup Action to the One-Step Action.
1. In the Contents area, right-click or select the Token selector to insert a new Prompt.
2. Create a Prompt that displays a list of style ids and names for the previously selected make and model in a web service lookup table.
  When the action runs, the Prompt will display a web service lookup table with the specified fields.
  Because the Return value from single field option was selected when the Prompt was created, a single styles.name value will be displayed in the pop-up window when the user selects a row from the web service lookup table.
  This value can be used to populate Business Object fields, make additional web service calls, or create a Token for use in other actions.