Query as a web service

 Use this action to issue a Web Service query.

The query is called from the server and will not be visible to the survey participant. It may be used to obtain information that is freely available on the Internet that you can then reference in your survey.

Depending on the success of the call, you may choose to run one or more scripts to handle the response and store any data returned by the web service within the survey. You can interrogate the information returned in AskiaScript by parsing the XML or using JSON to interpret the response. 

For example, you could use this action to convert a monetary amount given in a foreign currency into dollars or euros by querying a webpage providing current market rates for international currencies. If the web page you are querying returns a whole table of currencies and exchange rates, you could then use askiascript to parse this information and find the specific exchange rate you require before applying this as a conversion factor to the value given by the survey participant, so that your survey data contains only dollar or euro amounts, as you choose. 

Click the above image to enlarge the view.

The following options should be specified:

• Request method
• URL
• Headers
• Body
• Response, which may be either
  • Set with body response
  • Advanced: offering a choice of askiascripts to be speficied, one for success and the other for when the web service call results in an error

Request method

By default, the request method for your query is GET. You may replace by selecting an alternative method from the drop-down menu. The following HTTP and WebDAV compliant methods are offered:

GET

POST

PUT

PATCH

DELETE

COPY

HEAD

OPTIONS

LINK

UNLINK

PURGE

LOCK

UNLOCK

PROPFIND

VIEW

URL

Enter the URL for the web resource you wish to query, complete with any parameters, qualifiers or query strings that the remote service may support or require. 

Headers

[to be described]

Body

[to be described]

Response

Choose between:

• Set with body response or
• Advanced

These are described below.

Set with body response

Set with body response

Advanced (response)

Two text fields are provided for you to provide two alternative AskiaScripts to handle the response:

• Script on success: specify a script here to extract and store data in your survey when the web service call was successful (i.e. it did not result in an error). 
• Script on error: you may optionally specify a script here to handle the situation when your web service call returned an error.

Related askiascript commands and keywords

There are several askiascript commands and keywords that have been created or adapted to assist in interpreting data returned from web service queries. Principal among these are:

CurrentHttpResponse - A global object that contains the response of a query web service routing. It offers the following properties and methods:

• Headers - Returns a dictionary with all the headers of the response.
• StatusCode - Returns the status code of the response as number.
• Body - Returns the body of the response as string.

MethodResult object properties:

• Success - Returns True when the operation succeed, otherwise it return False and chance is to have an ErrorMessage which indicates the reason of failure.
• ErrorCode - Returns the code of failure. It's always DK when the Success is True, or when there is no error code provided by the API that throw the exception.
• ErrorMessage - Returns the reason of failure. It will be empty when Success is True, but will normally contain a value when False

New Variant basic type methods:

• LoadJSON() - Use the JSON string in argument to initialize the value of the variant.
• ToBoolean() - Converts whatever value is inside the variant to a boolean.
• ToNumber() - Converts whatever value inside the variant to a number.
• ToDate() - Converts whatever value inside the variant to a date.
• ToString() - Converts whatever value inside the variant to a string.
• ToArray() - Converts whatever value is inside the variant to an array of variants.
• ToNumberArray() - Converts whatever value is inside the array to an array of numbers.
• ToStringArray() - Converts whatever value is inside the array to an array of strings.
• ToDictionary() - Converts whatever value is inside the variant to a dictionary.
• InnerTypeOf() - Returns the type of the basic value hold by the Variant.

Array Object methods:

• LoadJSON() - Use the JSON string in argument to initialize the value of the variant array.
• RemoveDuplicates() - Remove the duplicates values of the array.

Dictionary object properties and methods:

• Count - Returns the number of key/value pairs within the dictionary.
• Keys - Returns the list of sorted keys within the dictionary.
• Values - Returns the list of values within the dictionary.
• ContainsKey() - Indicates if the key exist in the dictionary.
• RemoveKey() - Remove the key/value pair associated with the specified key.
• Set() - Add or update the dictionary with the specified key and value.
• LoadXML() - Use the XML string in argument to set or reset all the dictionary keys.
• LoadJSON() - Use the JSON string in argument to initialize the value of the dictionary.