Using a template to retrieve data from and send data to a Web Service

When using a Data Connector applet with a web service interface, the applet is sometimes referred to as a Web Service Data Connector or WSDC.

Web Service is an interface available to Data Connector applets. Using the Web Service interface in a Data Connector, you can get data from and send data to an external web service. For more information about a Data Connector applet, see Data Connector applet.

When you use a Data Connector applet to exchange data with a web service, you can either define the web service interaction using XML yourself, or use a template, if available. For information about defining the web service interaction using XML, see Defining a web service interaction using XML to retrieve data from and send data to a Web Service.

How do I use a template to define a web service interaction to exchange data with a web service?

If your account manager has created one or more templates for you, you can use a template to define your web service interaction. If you need a template or templates, contact your account manager.

The templates may require request parameter values or return response values, both, or neither. If the template requires or returns any values, you must define these values in the Request/Response Definition section.

To use a template in a Data Connector applet, perform the following steps:

  1. Create a Data Connector applet. For information about creating an applet, see Creating an applet. A new Data Connector applet appears.
  2. In Interface in the Interface section, click Web Service. The Action and Web Service Interaction sections appear.

  3. Optionally select the applet that the call is routed to if the interface fails in the Interface Failure list.

    An interface failure occurs when the request does not receive a response from the web service. A timeout or a DNS lookup failure, for example, might cause an interface failure. Do not confuse an interface failure with a response with a HTTP error status code. For more information about status codes, see Step 6: Successful action later in this page.
  4. In the Action list in the Action section select the template you wish to use. If the template requires request parameter values or returns response values, the Request/Response Definition section appears. If no Request/Response Definition section appears go to step 6.

  5. The Request/Response Definition section contains the following areas:
    • Request. If present, the request area contains one or more request parameters. Specify a value for each of the available parameters.

      You can include placeholders to insert Data Source or custom configuration values into the request parameters. For more information, see Using a Data Source value in a Web Service Interface request or Using a custom configuration value in a Web Service Interface request.

    • Response. If present, the response area contains one or more response values that the web service returns. Specify the locator for each of the response values. The value or values are stored in Data Sources for later use, if required, in your interaction plan. The names of the Data Sources are defined in the template. You will need to know the names of the Data Sources to use them.
    • Resulting Data Sources. If the web service returns one or more response values, the Resulting Data Sources section appears. Resulting Data Sources displays the created data sources and the data type.

    In the following example, the selected template calls a web service that returns the opening times of a shop in the relevant time zone. The web service requires values for the Time and Time Zone request parameters and this can be set in the 'Request/Response Definition' section using Data Sources available in the interaction plan containing the opening hours and time zone respectively . The web service formats the specified opening hours in the specified time zone and returns a JSON response. The required response value is located using JSON dot notation—in this example, result.FormattedTime. This value is stored in a Data Source for use later in the interaction plan. Resulting Data Sources displays the created data sources—in this example, formattedTime and HttpResponseCode—and their data types—String and Integer respectively.

    The example template corresponds to the example Request/Response Definition section in the applet. The template shows the request, which requires values for the Time and Time Zone parameters, and the response, which stores the specified response value (result.FormattedTime) in a Data Source called formattedTime.

    Example template
    <ApiInteraction>
        <Request>
            <Url>http://example.com/</Url>
            <Method>POST</Method>
            <Headers>
                <Header>
                    <Key>timeKey</Key>
                    <Value>%(Time)</Value>
                </Header>
                <Header>
                    <Key>timeZoneKey</Key>
                    <Value>%(Time Zone)</Value>
                </Header>
            </Headers>
            <Body></Body>
        </Request>
        <Response>
            <Type>JSON</Type>
            <ResponseCodeDestination>HttpResponseCode</ResponseCodeDestination>
            <Fields>
                <Field>
                    <Locator>%(Result Locator)</Locator>
                    <Destination>formattedTime</Destination>
                    <DataType>String</DataType>
                </Field>
            </Fields>
        </Response>
    </ApiInteraction>
    
  6. In the Successful Action list click the applet that the interaction is routed to next.

    A successful action indicates that the web service returned a response. The returned response might be an HTTP error status code. You can check the actual response in subsequent applets, such as a Data Router applet. Use the returned ResponseCodeDestination value in the response, which you save in a Data Source, to determine what you do with the call next.
  7. To save your changes, click Update. When you save your changes, the content of the Request/Response Definition section is validated. Any errors appear at the top of the page and the applet is not saved until you correct the errors and click Update again.

If the request is successful (we receive a response), the interaction is routed to the applet in Successful Action.
If the request fails (we do not receive a response), the interaction is routed to the applet in Interface Failure.

Support and documentation feedback

For general assistance, please contact Customer Support.

For help using this documentation, please send an email to docs_feedback@vonage.com. We're happy to hear from you. Your contribution helps everyone at Vonage! Please include the name of the page in your email.