Integration with External Web Service

Overview

Webservice references are web services that can be integrated into a Flow. To add a web service within the Portal, navigate to the folder System > Flow Management > External Services and click the Add WebService Reference button, then supply the necessary details.
To call a web service method as part of a Flow, in the Flow Designer, locate the appropriate component under Integration> External WebServices > [WebService Reference Name], and place it in the Flow's workspace.

Example

This example Flow will integrate an external web service that verifies a phone number is valid. A user will input the phone number in a Form, which will serve as input to the web service. If the phone number is valid, the Flow will proceed. Otherwise, the user is redirected back to the original Form.

Begin by defining the external web service. In the Portal, navigate to the folder System > Integrations > External Services and click the ADD WEBSERVICE REFERENCE button on the bottom Action bar.

In the resulting Add ExternalWebServicesReference pop-up, define the settings for the web service reference, beginning with the Name - "Validate Phone Number."

Next, define the URL for the web service - http://ws.cdyne.com/phoneverify/phoneverify.asmx. Because WSDL defines the web service, select the checkbox for Specify WSDL. WSDL-defined web services can describe the methods that users can use. The benefit of this ability will be noticeable when designing the Flow.

For now, note that selecting Specify WSDL raises the WSDL > SourceType field with two dropdown options:

• when URL is selected, WSDL > From URL is displayed, which automatically defaults to industry-standard values.
  Other web service configurations may differ, so be sure to consult the appropriate API references before adding new references.
• when File is selected, WSDL > From File is displayed, providing a dialog to upload a .wsdl file.

This completes the external web service reference configuration. Click SAVE SERVICE REFERENCE to save changes. The web service is now ready for Integration with a Flow.

Begin building the example Flow in a Designer Folder. Create a new Flow named External Web Services Flow, and open it for editing.

The Flow will begin with a Form in which the user inputs a phone number. From the Flow Designer's startup window, expand Flows, Rules, Forms, and Reports > Forms [Interaction], select a [Pick or Create Form] step, and click ADD to place it into the workspace after the Start step.

Click on the Form and select Pick or Create Form from the Properties panel. Name the Form and click Create.

The simple Form will contain a button, a label for "Phone Number," and a text field that will take in the string phone number value. Begin by expanding the Action category from the Toolbox, and drag and drop a Button component into the workspace. Configure its properties as follows:

From the Toolbox, expand the Data category and drag and drop a Label component into the workspace.
Next, click on the Toolbox tab and drag and drop a Text Box component next to the label. Configure as follows:

Save and close the Form. Connect the Start step to the Form.
In the Steps panel, expand the category Integration > Web Services > Validate Phone Number. Using the reference created earlier, the platform has contacted the Check Phone Number web service and retrieved a list of available methods. Each method is represented as a component that can be dragged into a Flow.

Drag and drop the Check Phone Number component into the workspace following the Form. Connect the Verify path out of the Form to the Check Phone Number component.

Click on the Check Phone Number component. It is necessary to configure two inputs for the step, the License Key and Phone Number. First, set the input for the License Key field. This particular service requires data in the field; however it can be sample data (and not a valid license). Select the Mapping Type of Constant for License Key and type in the value "12345" in the Value field.
Next, configure the Phone Number field. Set the Mapping Type to Select Value for Phone Number, and select PhoneNumber [String]. Click Done to save and close.

In this example, configure a Form to show attributes of the phone number should the service return that the number is valid. In the Steps panel, expand Forms [Interaction], and drag and drop a [Pick or Create Form] step into the workspace after the Check Phone Number step. Click on the Form and select Pick or Create Form from the Properties panel. Name the form "Display Phone Information" and click Create.

Begin configuring the Form by adding a Button component, from the Toolbox > Action category; name the button OK.
Next, add a Label component that states, "Is this phone number valid?" Then, begin adding Data Values to the Form.

The Data panel contains components that represent each piece of data returned by the web service. Navigate to Data > Flow Data > Valid, and drag and drop the Valid component into the workspace; select the Label of Data Value option, then press the Enter key to set the control. This will create a label on the Form that is populated with the value for "Valid." Repeat this for the TelecomCity, TelecomCountry, and TelecomZip data options.

Save and close the Form. Connect the Done path of the Check Phone Number step to the Display Phone Information form. Connect the Failed path of the Check Phone Number step to the End step.

Lastly, it is necessary to map the output of the Check Phone Number step to the input on the Display Phone Information form. Click on the Display Phone Information form, and from the Properties tab, select Edit Input Mappings.

Drag and drop the value on the left to the respective input field on the right. Click OK when complete.

Debug

Save the Flow. Click the Debug Flow link at the top of the workspace to test the Flow.
Enter a valid phone number and click OK.

Notice the results in the following Form.