Web Service

 

Connects to a third-party database or endpoint (a web service) for sending and receiving information.

 

The supported web connection methods are HTTP GET, HTTP POST, SOAP, and REST. 

Note: for the GET, HTTP POST and SOAP methods, it is necessary for Content Guru to create a proxy application for communicating with the remote end point. Consult your local support desk for advice.

Properties

Web Service Section

Input Variables Section

Output Variables Section

Web Service Section

Option	Description
Request Type	Select either HTTP or HTTPS.
Web Method	Use 'HTTP GET' for retrieving data. The action cell formats the request URI automatically using its input variables (see the Output property below). For example: www.example.com/webpage.php?name1=value1&name2=value2 Data is returned using the action cell's output variables. Use 'HTTP POST' to submit and retrieve data. The action cell's input variable values are included in the body of outgoing messages and output variables are used to store the return values. Use 'SOAP' to query a remote web service API by formatting and transmitting a custom XML file using the specification defined in a WSDL (Web Service Definition Language) file provided by your organisation. The action cell's input values are sent in the XML message body and values are returned using output variables. Note: SOAP APIs are based on the WSDL file. It is necessary for Content Guru to create a proxy application, which uses this WSDL file. Your web service will then appear for selection in the action cell's SOAP Method field. Use 'REST' to send data to an external web service and to accept returned data from an external web service. The action cell JSON-encodes the input variables (see the example input variables below) and passes this to the select endpoint (see Endpoint Name below). Data is returned using the action cell's output variables. Note: The REST method is superseded by the REST API action cell.
Server Address	Applies if you are using the HTTP GET, HTTP POST, or SOAP method Enter the URL of the remote service (as a literal value preceded by =, or a string variable).
Request Path	Applies if you are using the HTTP GET, HTTP POST, or SOAP method Enter the location of the remote web service. For example, </webservices/webpage.php>. Use a literal value preceded by =, or a string variable.
Endpoint Name	Applies if you are using the REST method Select the endpoint alias to be called from the drop-down list. Note: Content Guru will add the required URLs to this field. The URL must support https (TLS 1.2). Contact your support representative for further information about adding REST endpoints for your organisation.
Timeout	Applies to all web methods Select the duration for which to wait for a response. If no response received in this time, the Timeout exit route is taken.
Output	Applies if you are using the HTTP GET or HTTP POST method To speed up lookups, specify where to look for the named output variables in the response XML received from the remote resource. For example, entering </response/response2/getvalue> will look at the bold-highlighted section in the XML tags below: <?xml version='1.0'?>   <response>     <response1>        <getvalue id='{name1}'>{value}</getvalue>        <getvalue id='{name2}'>{value}</getvalue>     </response1>     <response2>        <getvalue id='{name1}'>{value}</getvalue>        <getvalue id='{name2}'>{value}</getvalue>     </response2>   </response>

Input Variables Section

Applies to all web methods.

Use this section to build a list of variables for passing values to the database or endpoint. In the Name field, enter a label for the parameter to pass.

In the Value field, provide the value (a literal value or a variable). If the variable is empty or null, it will be sent as a whitespace character.

Note: a date value must be provided as a variable and not as a literal.

Click ADD to add the Name and Value pair to the list below.

Example for using the REST method:

These input variables are JSON-encoded and passed to the selected endpoint. In this example, the input variables hold the following data:

Input Variable name           Value

=source                            Sales

=sourceID                        1234567890

=disabled                          False

The Web Service action cell generates the following JSON code, where Type is a string which has the value 'flow_event' and Created_at is a timestamp in the format YYYY-MM-DDTHH.mm.ss.

{
"Type": "flow_event",
"Created_at": "2019-03-18T18:02:23",
"Data":{
"source": "Sales",
"sourceid": "1234567890",
"disabled": "false"
}
}

Notes: security headers are added to the request, which you can check to verify the request was made by Content Guru.

The Type, Created_at and Data fields all have the first letter capitalised. Anything in the Data field has a key value in lower case.

Input variables must contain a value - they cannot be empty or null.

Output Variables Section

Applies to all web methods

Use this section to build a list of variables for receiving information returned by the database or endpoint. In the Name field, enter a label for the parameter that is being received (this must match the parameter in the database); In the Value field, provide the variable to store the value. Click ADD to add the Name and Value pair to the list below.

Using REST

The REST method supports HTTP POST requests, but not HTTP GET requests.

Your organisation provides the endpoint callback URI, which must be HTTPS, to protect the authentication credentials in transit.

Each webhook notification will be signed by Content Guru via an X-Hub-Signature header. This allows you to verify that the notification came from Content Guru by decoding the signature.

The value of this X-Hub-Signature header will be computed by creating a signature using the body of the JSON request and a secret value provided by you. The signature is the hexadecimal representation of a SHA-256 signature computed using the HMAC algorithm. The X-Hub-Signature header value starts with the string sha256= followed by the signature.

The event will also contain a timestamp attribute that you can validate, if required.

The Web Services action cell takes the JSON response from the external web service and decodes it into the specified Output Variables. The response must be flat (not nested). The JSON response must also follow these rules:

• JSON response must be surrounded by curly braces {}
• JSON response must be written in key/value pairs
• Keys must be strings, and values must be a valid JSON data type (string, number or Boolean)
• Keys and values must be separated by a colon
• Each key/value pair must be separated by a comma.

For example, if the external web service responds with the following, the output variables, the output variables listed below could be added to hold the values.

{
"id": "234567",
"name": "John Smith",
"sourceid": "400400",
"salesid": "Home Insurance"
}

To store this data, you could add the following output variables:

=id              szid

=name         szname

=sourceid     szsourceID

=salesid      szSalesID

This would be stored in the following output variables as:

Output Variable name        Output Variable value

id                                    234567

name                               John Smith

sourceID                          400400

salesID                            Home Insurance

The following is an example of a signed request.

POST https://example.org/hooks

X-Hub-Signature: sha256=cd34f2878b4d5c1932cca961745d8e82ae23b436813ae8e9e2a0faf6f86a0dec

Accept: application/json

Content-Type: application/json

{
"Type": "flow_event",
"Created_at": "2019-03-18T18:02:23",
"Data":{
"source": "Sales",
"sourceid": "1234567890",
"disabled": "false"
}
}

The following is an example of the C# code you must provide to compute the X-Hub-Signature.

private const string Sha256Prefix = "sha256=";
private string GenerateSignature(string _payload, string _secret)
{
var secret = Encoding.UTF8.GetBytes(_secret);
var payloadBytes = Encoding.UTF8.GetBytes(_payload);

using (var hmacsha256 = new System.Security.Cryptography.HMACSHA256(secret))

{
var hash = hmacsha256.ComputeHash(payloadBytes);
var hashString = ToHexString(hash);
var signature = Sha256Prefix + hashString
}
return signature;
}

public static string ToHexString(byte[] bytes)
{
StringBuilder builder = new StringBuilder(bytes.Length * 2);
foreach (byte b in bytes)
{
builder.AppendFormat("{0:x2}", b);
}
return builder.ToString();
}

Exit Points

Exit Point	Description
Complete	This is taken if the web message has been sent and a response received.
Timeout	This is taken if no response is received within the timeout period specified in Timeout.
Request Failed	This is taken if there is an error with the request.