Integration with External Web Service
Last Updated: 05/02/2018
Introduced in Version: 2.0
Webservice references represent web services which can be integrated into a flow in a number of ways. To add a web service within the portal, navigate to the folder System > Flow Management > External Services, click the Add WebService Reference button, and 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 your flow in the workspace.
Our 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 >Administration> Integrations > External Services and click the button Add WebService Reference.
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 our webservice – http://ws.cdyne.com/phoneverify/phoneverify.asmx.
Because the web service is defined by WSDL, select the checkbox for Specify WSDL. WSDL-defined web services are able to 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 two new fields – WSDL > SourceType and WSDL > From URL – which are automatically defaulted to industry-standard values. Other web service configurations may differ, so be sure to consult the appropriate API references before adding new references.
This completes our external web service reference configuration. Click OK to save our changes.
The web service is now ready for integration with a flow.
Begin building our example flow in a Designer Folder. Create a new flow named External Web Services Flow, and open it for editing.
This opens our example flow in the Flow Designer.
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 Flow]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 OK.
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 work space.
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 Toolbox panel, expand the category Integration > Web Services > Validate Phone Number. Using the reference we 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 OK 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, we will 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 true license). Select the Mapping Type of Constant for LicenseKey and type in the value “12345” in the Value field.
Next, configure the Phone Number field. Set the Mapping Type of Select Value for Phone Number. Click the Browse button for the Path field, and select PhoneNumber. Click OK.
In the example, we want to present a form showing attributes of the phone number should the service return that the number is valid. Therefore, from the Toolbox panel, expand Forms [Interaction], and drag and drop a [Pick or Create Flow] 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 OK.
Begin configuring the form by adding a Button component, from the Toolbox > Action category. Name the button OK. The screenshot below shows the completed form configuration.
Next, add a Label component.
The Data panel contains components that represent each piece of data returned by the web service. Expand Flow Data > Valid, and drag and drop the [create] label (value) option into the workspace. This will create a label on the form that is populated with the value for “Valid.” Repeat for the TelecomCity, TelecomCountry, and TelecomZip data options.
Save and close the form. Connect the Done path of the Check Phone Numberstep to the Display Phone Information form. Connect the Failed path of the Check Phone Numberstep to the End step.
Lastly, it is necessary to map the output of the of the Check Phone Number step to the input on the Display Phone Information form. Click on the Display Phone Information form and from its Actions menu, select Show Mapping Editor.
Drag and drop the value on the left to the respective input field on the right. Click OK when complete.
Save the flow. Click the Debug Flow link at the top of the workspace to test the flow.
Enter a phone number that is valid and click OK.
Notice the results in the following form.