Integrate an API that returns XML

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 APIA 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 functionA 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 JSONJavaScript Object Notation: a data format based on JavaScript that is commonly used for API request parameters and responses. for Nintex Workflow Cloud to use.

The complete OpenAPI SpecificationA 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.

Summary

Nintex Workflow Cloud only accepts application/json, but not all APIs provide their responseThe 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 Workflow Cloud and the API, sending the requestAn 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 Workflow 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 custom connectorA set of instructions for the Nintex Workflow Platform to use third-party API functionality with Nintex workflows. A custom connector may include workflow actions, start events, forms or file control., and automatically passes the call through to the API with the authenticationIdentifying 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 custom connector looks just like any other custom connector.

Create the serverless function

Step 1: Register for authentication

The serverless function passes the authentication details through to the API as if Nintex Workflow 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 custom connector

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 custom connector

Import the OpenAPI Specification you created into Nintex Workflow Cloud:

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

To create the workflow:

  1. Click Create workflow in your Nintex Workflow 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 Workflow 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.
  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. Publish your workflow.

Tip: If you want to troubleshoot a custom connector, 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.

Step 3: Test the workflow

  1. Click Workflow in your Nintex Workflow Cloud tenancy.
  2. Click meatballs on the workflow you created.
  3. Click Manual start.
  1. Type the word you want to define in the field.
  2. Press Start to deliver a motivating word-of-the-day message.

* 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.