Accept an XML response
In this example, you will create a workflow that delivers a motivating "word of the day" message to a Slack channel, initiated by a public web form. The Merriam-Webster dictionary API A programming interface that defines how software can be interacted with by other software. returns the definition of a word in XML format, so you will create a serverless function A service that allows you to run code without provisioning and managing a web serve to host it. Examples include Amazon Web Services and Microsoft Azure. to translate the XML into JSON JavaScript Object Notation: a data format based on JavaScript that is commonly used for API request parameters and responses. for Nintex Automation Cloud to use. |
The complete OpenAPI Specification A standard, language-agnostic description of RESTful APIs that can be read by both humans and machines. Formerly known as Swagger., serverless code and icon for this example are available here. You can test the example using our provided serverless functions*, or write your own.
Nintex Automation Cloud only accepts application/json, but not all APIs provide their response The return from a third-party API after a request has been made by the client. in this format. A serverless function can sit between Nintex Automation Cloud and the API, sending the request An attempt to use a feature or operation of a third-party API. to the API and processing the returned data into JSON format before passing it back to Nintex Automation Cloud.
Instead of defining your OpenAPI Specification to match the API you want to use, you now define it to match your serverless function: that serverless function becomes the Xtension A set of instructions for Nintex Automation Cloud to use third-party API functionality with Nintex workflows. An Xtension may include workflow actions, start events, forms or file control., and automatically passes the call through to the API with the authentication Identifying the requestor of the API using techniques such as a username and password, an API key, or OAuth2.0. credentials, and passes the response in JSON back to the workflow. In the Workflow designer, the Xtension looks just like any other Xtension.
Create the serverless function
Step 1: Register for authentication
The serverless function passes the authentication details through to the API as if Nintex Automation Cloud was connecting directly to it. To register an API key:
- Sign up to DictionaryAPI.org at this link.
- Request an API key for the Collegiate Dictionary.
- Record the Key somewhere safe: it identifies you to the Dictionary API, and should be kept secret.
Step 2: Examine the API response
Once you have registered for an API key, you can preview the response by:
- Pasting this link into your browser followed by your API key:
http://www.dictionaryapi.com/api/v1/references/collegiate/xml/motivation?key=
For example:http://www.dictionaryapi.com/api/v1/references/collegiate/xml/motivation?key=123456 - Examining the API documentation at http://www.dictionaryapi.com/products/api-collegiate-dictionary.htm.
The API returns XML.
<entry_list version="1.0">
<entry id="motivation">
<ew>motivation</ew>
<subj>PS</subj>
<hw>mo*ti*va*tion</hw>
<sound>
<wav>motiva04.wav</wav>
<wpr>+mO-tu-!vA-shun</wpr>
</sound>
<pr>ˌmō-tə-ˈvā-shən</pr>
<fl>noun</fl>
<def>
<date>1873</date>
<sn>1 a</sn>
<dt>:the act or process of <fw>motivating</fw></dt>
<sn>b</sn>
<dt>:the condition of being <fw>motivated</fw></dt>
<sn>2</sn>
<dt>:a motivating force, stimulus, or influence :
<sx>incentive</sx>
<sx>drive</sx>
</dt>
</def>
<uro>
<ure>mo*ti*va*tion*al</ure>
<sound>
<wav>motiva05.wav</wav>
<wpr>+mO-tu-!vA-shu-n/ul</wpr>
</sound>
<pr>-shnəl, -shə-nᵊl</pr>
<fl>adjective</fl>
</uro>
<uro>
<ure>mo*ti*va*tion*al*ly</ure>
<fl>adverb</fl>
</uro>
</entry>
</entry_list>
Step 3: Build the function
Create a function in a language supported by your serverless function provider to convert the XML into a simple JSON structure. In this example, we have written a Microsoft Azure serverless function in C#.
#r "Newtonsoft.Json"
using System.Net;
using System.Xml;
using Newtonsoft.Json;
public static async Task<HttpResponseMessage> Run(HttpRequestMessage req, TraceWriter log)
{
log.Info($"C# HTTP trigger function processed a request. RequestUri={req.RequestUri}");
// the api key to be used against the Dictionary API
string apiKey = req.GetQueryNameValuePairs()
.FirstOrDefault(q => string.Compare(q.Key, "APIKEY", true) == 0)
.Value;
// the word to check
string word = req.GetQueryNameValuePairs()
.FirstOrDefault(q => string.Compare(q.Key, "word", true) == 0)
.Value;
var worddef = await GetWordDefinition(word, apiKey);
return req.CreateResponse(HttpStatusCode.OK, worddef, "application/json");
}
/// <summary>
/// The getdef() method calls the API and retrieves the definition as JSON.
/// </summary>
/// <param name="word">The word looked up in the dictionary.</param>
/// <param name="key">The Dictionary.com API Key.</param>
/// <returns></returns>
public static async Task<Word> GetWordDefinition(string word, string apiKey)
{
// established variables used in the method to make the call
string endpointroot = "http://www.dictionaryapi.com/api/v1/references/collegiate/xml/";
string apifrag = "?key=";
string dictionarycall = endpointroot + word + apifrag + apiKey;
// Call the dictionary API and read the response back
HttpClient client = new HttpClient();
var request = new HttpRequestMessage(HttpMethod.Post, dictionarycall);
request.Headers.Add("cache-control", "no-cache");
var response = await client.SendAsync(request);
string wordres = await response.Content.ReadAsStringAsync();
// Retrive the values from the response
XmlDocument wordxml = new XmlDocument();
wordxml.LoadXml(wordres);
XmlNode root = wordxml.DocumentElement;
XmlNode nodename = root.SelectSingleNode("/entry_list/entry[1]/ew");
XmlNode nodepart = root.SelectSingleNode("/entry_list/entry[1]/fl");
XmlNode nodedefinition = root.SelectSingleNode("/entry_list/entry[1]/def/dt[1]");
// Instantiate a word object and assign the values from the response.
Word wordobj = new Word();
wordobj.name = nodename.InnerXml;
wordobj.part = nodepart.InnerXml;
wordobj.definition = nodedefinition.InnerXml;
return wordobj;
}
/// <summary>
/// The word object holds the key attributes for a word definition.
/// </summary>
internal class Word
{
public string name { get; set; }
public string part { get; set; }
public string definition { get; set; }
}
Create the Xtension
Build an OpenAPI Specification that provides the parameters required by your serverless function, and accepts its response:
- The specification uses HTTPS to access your serverless function host The domain name of the third-party API's URL. at the base path you've defined, and produces application/json.
- The specification provides the API key An authorization code passed in an API request, either inside the header or as a parameter, to identify the requester. in the query Part of the URL that does not fit into the path structure, and provides additional information or parameters for the request. The query is prefaced by a question mark (?) in the URL, for example: http://example.com?color=blue..
- The specification sends the word to be defined in the query.
- The specification accepts a JSON object with three string properties in the response: the word, the part of speech the word represents, such as a noun or verb, and its definition.
You may want to use Nintex Specification Extensions to modify the names of some configuration fields, or hide them altogether.
{
"swagger": "2.0",
"info": {
"version": "1.0.0",
"title": "Get Definition"
},
"schemes": [ "https" ],
"host": "prdhlpsmpfncwus01.azurewebsites.net",
"basePath": "/api",
"paths": {
"/DictionaryConnector": {
"post": {
"tags": [ "Websters Dictionary API" ],
"summary": "Get a word definition.",
"description": "Returns a definition for a word.",
"operationId": "getDefinition",
"x-ntx-summary": "Get a word definition",
"parameters": [
{
"name": "word",
"in": "query",
"description": "The word to define",
"x-ntx-summary": "Word to define.",
"required": true,
"type": "string"
}
],
"produces": [ "application/json" ],
"security": [
{
"dictionaryApiKey": []
}
],
"responses": {
"200": {
"description": "Successful response with definition object.",
"schema": {
"title": "definition object",
"type": "object",
"properties": {
"word": {
"type": "string",
"x-ntx-visibility": "internal"
},
"part": {
"type": "string",
"x-ntx-visibility": "internal"
},
"definition": {
"type": "string",
"x-ntx-summary": "Definition"
}
}
}
}
}
}
}
},
"securityDefinitions": {
"dictionaryApiKey": {
"type": "apiKey",
"name": "APIKEY",
"in": "query"
}
}
}
Create the workflow
Step 1: Add your Xtension
Import the OpenAPI Specification you created into Nintex Automation Cloud:
- Open your Nintex Automation Cloud tenancy.
- Click Xtensions in the dashboard to open the Xtensions page.
- Click in the Private connector list.
- Click Choose a file. Navigate to the OpenAPI Specification on your computer.
- Wait for Nintex Automation Cloud to validate the file.
- Click Next.
- Nintex Automation Cloud detects the API key security
template.
- Click Next.
- Edit the Name of the Xtension, which becomes the name of the action group in the Workflow designer.
- Edit the Description of the Xtension. This appears in the Private connector list in the Xtensions page.
- Select or upload an icon for the Xtension. This is displayed for each action or event in the Workflow designer.
- Click Publish.
Step 2: Create the workflow
The workflow will retrieve a definition from the dictionary API, and use that definition to create a motivating "word of the day" message to deliver to a Slack channel.
For more information on creating workflows, see the Workflow Designer.
To create the workflow:
- Click Create workflow in your Nintex Automation Cloud tenancy.
- Configure the Start event to be a Public web
form with one text variable for the word to look up.
For more information on designing forms in Nintex Automation Cloud, see Design a form.
- Drag a Get a word definition action after the Start event.
- Connect to the Get a word definition action with your API key.
- Configure the Get a word definition action with:
- The public web form variable in the Word to define field.
- A new variable to hold the Definition result.
- Drag a Post a message action from the Slack action group after the Get a word definition action.
For more information, see Slack - Post a message. - Configure the Post a message action with the Slack channel you want to post the message to.
- Configure the Post a message action to send the Definition variable in a motivating message.
- Click Test to test the workflow.
- Save or publish the workflow.
Tip: If you want to troubleshoot an Xtension, select Development as the Assigned Use when you publish the workflow. Development workflows display more detailed error messages in their instance details. Republish your workflow as Production when you're ready to use it.
* The serverless function in this example is provided on an as-is basis for this demonstration only, and is not suitable for a production environment. Example serverless functions are not covered by the Nintex service level agreement.