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:

  1. Sign up to DictionaryAPI.org at this link.
  2. Request an API key for the Collegiate Dictionary.
  3. 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:

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:

  1. Open your Nintex Automation Cloud tenancy.
  2. Click Xtensions in the dashboard to open the Xtensions page.
  3. Click  in the Private connector list.
  4. Click Choose a file. Navigate to the OpenAPI Specification on your computer.
  5. Wait for Nintex Automation Cloud to validate the file.
  6. Click Next.
  1. Nintex Automation Cloud detects the API key security template.
  2. Click Next.
  1. Edit the Name of the Xtension, which becomes the name of the action group in the Workflow designer.
  2. Edit the Description of the Xtension. This appears in the Private connector list in the Xtensions page.
  3. Select or upload an icon for the Xtension. This is displayed for each action or event in the Workflow designer.
  4. 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:

  1. Click Create workflow in your Nintex Automation Cloud tenancy.
  2. 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.

  3. Drag a Get a word definition action after the Start event.
  4. Connect to the Get a word definition action with your API key.
  5. 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.
  6. 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.
  7. Configure the Post a message action with the Slack channel you want to post the message to.
  8. Configure the Post a message action to send the Definition variable in a motivating message.
  9. Click Test to test the workflow.
  10. 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.