Defining a Web Service Call Element
Workflow Manager 2020
If you first set up a web service connection to an external server, you may create a workflow step which populates a combo box or grid with data values obtained using a web service call. When you select Web Service Call from the Data type list on the Data Element Details view, up to five new fields appear:
| • | Web service name—Select a web service that was defined on the External Web Service Administration page. See Managing External Web Services for more information. |
| • | Web method—Once you choose a web service, the set of all available web methods automatically populates the Web Method field. Choose the method which will return the data you want to display. |
| • | UI Type—Determine whether the data you are returning should be displayed in a grid or in a combo box. |
| • | Persisted Column—Enter a column name or names, separated using semicolon, which identifies a unique row item or record. |
For example, in the below figure, columns like Country and Sales Rep have multiple entries with same values (USA and Fuller respectively). To identify and fetch a unique row item or record, you can enter one of these column names, County; Order No or Sales Rep; Order No or only Order No in the Persisted Column.
By entering these column names in the Persisted Column, you are allowing the Web Service Call data element to consider these column names as primary keys and fetches the unique row item or record based on the user selection.
Important:If you are not entering a column name or combination of column names, which doesn't have multiple entries with same value in the Persisted Column as explained in the above example, you might end up fetching a wrong row item or record.
Sample Web Services Grid Results
Persisted Column for UI Type-Grid
| • | Parameters—If the web method takes parameters, the Parameters field will appear, listing the parameters which need to be supplied. |
Parameters for a Web Service Call Data Type
For each parameter, choose an option from the Value Type field. You may select one of:
| • | User Defined—You will hard code a value for this parameter in the corresponding Value field. |
| • | Built-in: UserName, Built-in: Domain, or Built-in: Domain\UserName—The value of the parameter will be set to the account name, domain or combination of the two, respectively, of the person completing the workflow. |
| • | Data element: elementName—The value of the parameter will be set to the value entered by the consumer in one of the other data elements defined in this template. Each of the data elements defined in template appears in the list for you to select. |
Tip:Be careful that the values you specify for your parameters have an appropriate type. For example, if the web service method expects an integer value for a parameter, but you supply a string value, you may cause an exception. This is particularly important if your parameter values will be specified by the consumer, in a different data element. In that instance, you may need to put a mask on that data element, to ensure that the consumer specifies data in the correct format.
| • | Web Method details URL—Enter a URL which will display more information about the items returned by your web method. The URL must include a placeholder which will be replaced by the ID of the item chosen by the consumer. |
For example, assume this data element calls a web method which returns a list of end-users belonging to your organization and displays them in a grid. You want to display a window with more information about the end-users, such as their full name, contact details and job titles, when your workflow consumer clicks on one in the grid. You create an ASPX page called UserInfo.aspx to display this information, which takes the ID of the selected end-user in the database as a query string parameter. In this example, you would enter a value like http://<serverID>/UserInfo.aspx?UserID={0} into the Web Method details URL field, where the {0} placeholder would be replaced by the selected end-user ID at run time.
Tip:The first field returned by the web method will be used to uniquely identify each record presented in either the grid or the combo box. Ensure the data in this field is unique.
Defining UI Types for Web Service Call Element
If you first set up a web service connection to an external server, you may create a workflow step which populates a combo box or grid with data values obtained using a data element with the data type of Web Service Call.
Grid
To retrieve a data record with multiple fields, you set the UI Type field of a Web Service Call data element to Grid.
When you set UI Type to Grid, in the workflow request a text box with a Click to Select link will be displayed. When you click this hyperlink, a new browser window opens, from which you are prompted to select one record. After selection, the selected record will be listed in the text box.
Data Entry Form for a Web Service Call Data Element with a UI Type of Grid
Combo Box
If the web service method returns a list of key value pairs, you should set the UI Type field of the Web Service Call data element to Combo Box.
In the workflow request, the user will be prompted to select a value from the drop down list.
Data Entry Form for a Web Service Call Data Element with a UI Type of Combo Box
See Also
Including a Customer Acceptance Phase or Last Phase
Defining Specialized Data Elements, Workflow Phases, and Workflow Steps