| Insert excerpt | ||||||
|---|---|---|---|---|---|---|
|
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.
To configure When you use a Data Connector applet to exchange data with a web service, perform the following steps:
...
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.
| Info |
|---|
| 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. |
The Action field in the Action section contains one pre-selected option: Call Web Service.
The Web Service Interaction section contains the Interaction Definition text field which contains template XML.
| Code Block | ||||||||||
|---|---|---|---|---|---|---|---|---|---|---|
| ||||||||||
<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:
...
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.
| Note |
|---|
| The Data Connector provides a special type of web service called the ContactWorld Javascript Engine. For information about the ContactWorld Javascript Engine and how to use it, see Using the NewVoiceMedia Javascript Engine. |
...
<Url>http://myWebService.net/getData</Url><Url>$(JavascriptEngineUrl)</Url>...
Currently only GET or POST are supported.
| Note |
|---|
| 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>...
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
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>
...
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>
| Info |
|---|
| 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:
...
<Type>XML</Type>...
The Data Source that will hold the HTTP response code, as an integer, that the web service returns.
| Info |
|---|
| 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>...
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.
| Info |
|---|
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>
...
| Info | ||
|---|---|---|
| ||
|
...
Optionally test the contents of the Interaction Definition field in the Interaction Definition Test section. For information, see Testing your web service interaction definition.
...
| Note |
|---|
| 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 Failureyou can either define the web service interaction using XML yourself or use a template.
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.
For information about using a template, see Using a template to retrieve data from and send data to a Web Service.
| Panel | ||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| ||||||||||||||
|