Retrieving data from and sending 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.

In this page

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

If web service interaction templates are not enabled for your account, you have no templates available in your account, or you do not want to use any existing templates, you can define a web service interaction yourself.

To use a Data Connector applet to define a web service interaction, perform the following steps:

Create a Data Connector applet. For information about creating an applet, see Creating an applet. A new Data Connector applet appears.
In Interface in the Interface section, click Web Service. The Action and Web Service Interaction sections appear.
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 Successful action.

In the Action list in the Action section select Call Web Service.
The Web Service Interaction section appears, containing the Interaction Definition text field which contains template XML.

Template Interaction Definition

<ApiInteraction>
  <Request>
    <Url></Url>
    <Method></Method>
    <Headers>
      <Header>
        <Key></Key>
        <Value></Value>
      </Header>
    </Headers>
    <Body><![CDATA[
      
    ]]></Body>
  </Request>
  <Response>
    <Type></Type>
    <ResponseCodeDestination></ResponseCodeDestination>
    <Fields>
      <Field>
        <Locator></Locator>
        <Destination></Destination>
        <DataType></DataType>
      </Field>
    </Fields>
  </Response>
</ApiInteraction>

Use the template XML as a basis for your web service interaction.
Define where you want to send the request and the information you want to send in the request:

XML element	Required or optional	Description	Example
Url	Required	The address of the web service with which you want to exchange data. You must include the web protocol (HTTP:// or HTTPS://) in the URL. The Data Connector provides a special type of web service called the NewVoiceMedia Javascript Engine. For information about the NewVoiceMedia Javascript Engine and how to use it, see Using the NewVoiceMedia Javascript Engine.	<Url>http://myWebService.net/getData</Url> <Url>$(JavascriptEngineUrl)</Url>
Method	Required	Currently only GET or POST are supported. You cannot send values in the Body element if you use a GET method. You can use query string parameters in the URL instead.	<Method>POST</Method>
Headers	Optional (required if you define one or more Header elements)	All Headers defined in the Headers block are inserted as HTTP headers into the HTTP request. You can use any standard HTTP headers other than: Expect Proxy-Connection Range Transfer-Encoding You can use custom headers If the target web service uses basic access authentication, to authenticate with the web service, send Base64 encoded credentials in the Authorization header. For example: `<Header><Key>Authorization</Key><Value>Basic EncodedCredentials</Value></Header>` Each Header must have a Key and a Value tag.	<Headers> <Header> <Key>Content-Type</Key> <Value>application/json</Value> </Header> <Header> <Key>Key2</Key> <Value>Value2</Value> </Header> <Header> <Key>Key3</Key> <Value>Value3</Value> </Header> </Headers>
Header	Optional
Key	Required for each Header
Value	Required for each Header
Body	Optional	Any text within this tag is used as the body of the request message. To define XML or JSON content in the body, enclose the content in a CDATA section—that is, between <![CDATA[ and ]]>.	<Body> <![CDATA[ <?xml version='1.0' encoding='utf-8' ?> <test>Contents</test> ]]> </Body>

You can include placeholders to insert Data Source or custom configuration values into the Url element, the Key and Value elements of a Header, and the Body element. 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.

Define what you want to do with the response:

XML element	Required or optional	Description	Example
Type	Required	The expected format of the response, either XML, JSON, or NONE. Use NONE when the response can be ignored or is not valid XML or JSON.	<Type>XML</Type>
ResponseCodeDestination	Required	The Data Source that will hold the HTTP response code, as an integer, that the web service returns. You can use this value in a subsequent Data Routing applet, for example, to determine if the web service interaction was successful. Generally any code greater than 399 should be considered as a failure. For more information about standard HTTP response codes, see Wikipedia.	<ResponseCodeDestination>WebServiceResult</ResponseCodeDestination>
Fields	Optional (required if you define one or more Field elements)	A Field entry is required for each of the response values that you want to write to a Data Source. The Locator is the location of the individual response value in the response from the web service. If the response type is XML, provide an XPath query that will locate the required XML node in the response message. If the response type is JSON, provide a JSON property name, using JSON dot notation. For more information about XPath locators syntax, see Microsoft help. For more information about JSON locators, see Defining JSON locators. The Destination is the name of the Data Source that will be used to hold the response value. The DataType is the type of the Data Source that will be used to hold the response value. This must be one of the following types: String Integer Decimal Boolean Time	XML response: `<Locator>/response/client[@name="Key"]</Locator>` JSON response: `<Locator>response.client.name</Locator>` or `<Locator>response.client[0].name</Locator>` `<Destination>WebServiceResult</Destination>` `<DataType>String</DataType>`
Field	Optional
Locator	Required for each Field
Destination	Required for each Field
DataType	Required for each Field

Highlighting and autocomplete in Interaction Definition

The contents of Interaction Definition are formatted with XML or JSON highlighting as appropriate as you type.
A list of tags, based on the parent XML tag, appears when you type < to open an XML tag, or press CTRL+SPACEBAR.
To insert a CDATA wrapper, type <!.
Matching XML tags, and curly and square brackets are highlighted and autocompleted as you click in the field.
Data Sources and custom configuration settings are autocompleted as you type—if you type $ or # a list of available Data Sources or custom configuration keys appears.
Standard text-editing key combinations can be used, for example, Ctrl+A, Ctrl+C, Ctrl+X, Ctrl+V, Ctrl+Z, Ctrl+Y.
Press CTRL+J to navigate to the closing XML tag of an element.
Press CTRL+D to delete a line in the text area.

Optionally test the contents of the Interaction Definition field in the Interaction Definition Test section. For information, see Testing your web service interaction definition.
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.
To save your changes, click Update. When you save your changes, the content of the Interaction Definition field 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.

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

If enabled for your account, and 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:

Create a Data Connector applet. For information about creating an applet, see Creating an applet. A new Data Connector applet appears.
In Interface in the Interface section, click Web Service. The Action and Web Service Interaction sections appear.
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 Successful action.
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.
The Request/Response Definition section contains one or two 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 use later, 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.
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. Data Sources available in the interaction plan, $(OpeningHours) and $(Office|TimeZone), contain 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.
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 Expand source
<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>
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.
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.

In this section