Send to REST Service Action

SmartIQ includes the ability to send form data to a REST service, via the "Send to REST Service" action.

The action provides three outputs:

• Status (the HTTP response such as "OK", "CREATED")
• Response (the HTTP response body, if any)
• Output Path Data (the results, as a value or snippet, of the Output Path against the Response)

Action Configuration

The Send to REST Service action can be added to a project in Design, either on the Finish page or as part of a Workflow transition.

The input parameters for the action are as follows:

📘

Important

Is not required to provide a JSON Template to use this Action. Simply use the Body Request Action Input and provide a JSON Schema using Request Schema.
It is recommended to use JsonEncode() Formula to encode User inputs (Do not encode the whole JSON payload as it will result in a runtime error.
For example:

• Formula to encode user input: JsonEncode([q1])
• Formula to generate JSON to be used in Body Request Action Input: =Concat("{""text"":""",[q2.3],"""}") resolves to: {"text":"Encoded text \"here\""} for example.

Including Body Request

Request Body using a Document

The action accepts an optional body document to be sent as the content of the request, this should be included as an SmartIQ template within the project, mapping placeholders to the appropriate questions and attached as an Action Document.

📘

Document types

The Action will automatically detect the document extension (JSON or XML) configure the request headers appropriately (application/json or application/xml).

🚧

Number of Document

Only a single JSON or XML body document can be provided. If more than one is supplied, either explicitly through "Custom" action document settings, or implicitly through multiple templates being present in the project and not deactivated by conditions, the REST Service action will throw an error.

Request Body using a String

Alternatively, designers can provide the body request as a String using the Action Input Request Body in combination with Request Schema, note that this feature is only available for JSON payloads. This feature provides more flexibility on when the action will run as there's no need to generate a document.

The ability to include a schema within the request allows designers to:

• Restrict the number of parameters used in the request.
• Ensures that the request is in accordance with the schema.
• Prevent unintentional JSON elements from being included.

📘

SECURITY CONSIDERATION

It is recommended that user inputs (Text Fields for example) are properly encoded using the JsonEncode() formula, this will not only prevent ambiguous characters to be fixed but also prevet malicious inputs.

Let's pretend we have a REST API that allows to create new customers in a cloud CRM, that accepts the following JSON request:

{
    "name":"Intelledox",
    "address":"8 Wiluna St, Canberra ACT 2609",
    "phone": "(02) 6280 6244",
    "region": "APAC",
    "tier": "Gold",
    "loginDetails":{
        "username":"usernameHere",
        "password":"passwordHere"
    }
}

which full schema looks similar to

{
  "definitions": {},
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "http://example.com/root.json",
  "type": "object",
  "title": "The Root Schema",
  "required": [
    "name",
    "address",
    "phone",
    "region",
    "tier",
    "loginDetails"
  ],
  "properties": {
    "name": {
      "$id": "#/properties/name",
      "type": "string",
      "title": "The Name Schema",
      "default": "",
      "examples": [
        "Intelledox"
      ],
      "pattern": "^(.*)$"
    },
    "address": {
      "$id": "#/properties/address",
      "type": "string",
      "title": "The Address Schema",
      "default": "",
      "examples": [
        "8 Wiluna St, Canberra ACT 2609"
      ],
      "pattern": "^(.*)$"
    },
    "phone": {
      "$id": "#/properties/phone",
      "type": "string",
      "title": "The Phone Schema",
      "default": "",
      "examples": [
        "(02) 6280 6244"
      ],
      "pattern": "^(.*)$"
    },
    "region": {
      "$id": "#/properties/region",
      "type": "string",
      "title": "The Region Schema",
      "default": "",
      "examples": [
        "APAC"
      ],
      "pattern": "^(.*)$"
    },
    "tier": {
      "$id": "#/properties/tier",
      "type": "string",
      "title": "The Tier Schema",
      "default": "",
      "examples": [
        "Gold"
      ],
      "pattern": "^(.*)$"
    },
    "loginDetails": {
      "$id": "#/properties/loiginDetails",
      "type": "object",
      "title": "The Logindetails Schema",
      "required": [
        "username",
        "password"
      ],
      "properties": {
        "username": {
          "$id": "#/properties/loginDetails/properties/username",
          "type": "string",
          "title": "The Username Schema",
          "default": "",
          "examples": [
            "usernameHere"
          ],
          "pattern": "^(.*)$"
        },
        "password": {
          "$id": "#/properties/loginDetails/properties/password",
          "type": "string",
          "title": "The Password Schema",
          "default": "",
          "examples": [
            "passwordHere"
          ],
          "pattern": "^(.*)$"
        }
      }
    }
  }
}

As described earlier, user inputs should be properly encoded, for example, if a user provides SmartIQ "Australia" for the name, the formula will properly encode the character ".

Similarly, if the user provides SmartIQ "loginDetails":{"username":"usernameHere","password":"passwordHere"} as the Name, the full string will be included as the actual name string by using JsonEncode instead of including the JSON string as part of the request.

In the same vein, the usage of the schema in combination with JsonEncode() formula allows restricting the usage of specific parameters just by removing them in the schema.

Attachments

If an attachment is to be included with the rest service, you can use two methods:

1. If your request body uses a JSON document then add the appropriate JSON placeholder onto the attachment answer - this will insert the uploaded/generated document into the JSON as base 64

2. Alternatively attach the document to the REST action and set the "Send as multipart" input

Custom headers

Custom headers, if required by the service, can be supplied using the Custom Header action parameter. Zero or more headers may be specified as a key-value pair, and will be sent as part of the REST request.

Using the Status and Response outputs

The Status and Response outputs can be referenced by subsequent Actions, for example to drive the display of a message to the user, or to store the response body in a database for later reference.

Using an Output Path and the Output Path Data

A path to a value or node in the Response to the REST call can be specified using the Output Path parameter.

Possible path formats are JSONPath for JSON responses or XPath for XML responses

JSONPath

JSONPath expressions always refer to a JSON structure in the same way as XPath expression are used in combination with an XML document. Since a JSON structure is usually anonymous and doesn't necessarily have a "root member object" JSONPath assumes the abstract name $ assigned to the outer level object.

JSONPath expressions in SmartIQ use the dot–notation (JSONPath uses a 0 based index):

$.store.book[0].title

An example Output Path Data value in this case might be "The Da Vinci Code"

or if the Response only returns a single node you can leave out the index.

$.store.book.title

If you use a non indexed call (like the one just above) against an array or a response with many nodes you will get all the relevant title values as a | separated string

An example Output Path Data value in this case might be "The Da Vinci Code|The Lord of the Rings|Anne Frank Diary of a Young Girl"

If you call a path that is an node rather than a value, you will get a JSON snippet in return.
For example an Output Path of:

$.address

Might result in a JSON snippet like this as the Output Path Data value, because the path does not have a simple value.

{ "street": "Kulas Light", "suite": "Apt. 556", "city": "Gwenborough", "zipcode": "92998-3874", "geo": { "lat": "-37.3159", "lng": "81.1496" } }

XPath

XPath uses a 1 based index.

/bookstore/book[1]

An example Output Path Data value in this case might be "The Da Vinci Code"

or if the Response only returns a single node you can leave out the index.

/bookstore/book

If you use a non indexed call (like the one just above) against an array or a response with many nodes you will get all the relevant title values as a | separated string

An example Output Path Data value in this case might be "The Da Vinci Code|The Lord of the Rings|Anne Frank Diary of a Young Girl"

If you call a path that is an node rather than a value, you will get an XML snippet in return.
For example an Output Path of:

/CUSTOMER

Might result in an XML snippet like this as the Output Path Data value, because the path does not have a simple value.

<ID>18</ID><FIRSTNAME>Sylvia</FIRSTNAME><LASTNAME>Fuller</LASTNAME><STREET>158 - 20th Ave.</STREET><CITY>Paris</CITY>

Retrieving header values

The value of a HTTP header in the received response can be set as an output by specifying an output path in the form:

header=HeaderName

If the specified header is present in the response, its value will be returned as the action output. If the header is not present, the output will be blank.

Sample project

The following section will walk through constructing a project to send some REST data to the https://jsonplaceholder.typicode.com/ test service.

Sample JSON schema

{
  "$schema": "http://json-schema.org/draft-04/schema#", 
  "definitions": {}, 
  "id": "http://example.com/example.json", 
  "properties": {
    "body": {
      "description": "An explanation about the purpose of this instance.", 
      "id": "/properties/body", 
      "type": "string"
    }, 
    "title": {
      "description": "An explanation about the purpose of this instance.", 
      "id": "/properties/title", 
      "type": "string"
    }, 
    "userId": {
      "description": "An explanation about the purpose of this instance.", 
      "id": "/properties/userId", 
      "type": "integer"
    }
  }, 
  "type": "object"
}

Project setup

1. Create a new project in Design
2. Import the example.schema.json document as a project template
3. Create some Text Input questions and map their Answers to the template placeholders
4. Add a "Send to REST Service" action to the project's Finish page
5. Supply parameters for the action as follows:

• URL: https://jsonplaceholder.typicode.com/posts
• HTTP Method: POST

6. Optionally, add an Output Path value of $[4].title to get an Output Path Data value which should match the title of the 5th post in the Response.
7. Optionally, set up the Action Documents to pass only the correct document to the Action. If there are no other JSON or XML templates in the project this step is unnecessary, as the default "All" setting will work fine
8. For Delete of the resource created in Step 5 supply following parameters to the action with no action document

• URL: https://jsonplaceholder.typicode.com/posts/{UserIdCreated}
• HTTP Method: DELETE

Troubleshooting Modes

To troubleshoot the problems in Send to REST Service action, make sure to check Troubleshooting Mode in the project Publish Options.

To log more detailed troubleshooting data including all REST parameters and values, check Show Variables and Show Invisible Datasources. Also in AppSettings.json file under produce, make sure to add "ShowDatasourceTroubleshootingErrors": "True" under AppSettings.

"AppSettings": {
    "ShowDatasourceTroubleshootingErrors": "True"
  },