Making Requests

In order to make a request you have to specify at least an URL. All other directives are not required.

Request specification

Key	Type	Description
url	IML String	Specifies the URL that should be called.
encodeUrl	Boolean	Default: true. Specifies if the URL should be auto encoded or not.
method	IML String	Specifies the HTTP method, that should be used when issuing a request.
headers	IML Flat Object	A single level (flat) collection, that specifies request headers.
qs	IML Flat Object	A single level (flat) collection that specifies request query string parameters.
ca	IML String	Custom Certificate Authority
body	Any IML Type	Specifies a request body.
type	String	Specifies how data are serialized into body.
temp	IML Object	Creates/updates the temp variable
condition	IML String or Boolean	Determines if to execute current request or never.
repeat	IML Object	Repeats a request under a certain condition with a predefined delay in milliseconds. The maximum number of repeats can be bounded by the repeat.limit.
aws	AWS Parameters Specification	Collection of parameters for AWS signing
followRedirects	Boolean	Default: true. Follow HTTP 3xx responses as redirects
followAllRedirects	Boolean	Default: true. Follow non-GET HTTP 3xx responses as redirects
gzip	Boolean	Default: flase. Add an Accept-Encoding header to request compressed content encodings from the server (if not already present) and decode supported content encodings in the response.
response	Response Specification	Collection of directives controlling processing of the response.
pagination	Pagination Specification	Collection of directives controlling pagination logic.
log	IML Flat Object	A single level (flat) collection that contains logging options.

url

Required: yes

This directive specifies the request URL.

It must be always present. The trigger does not support request-less/static mode, because it makes no sense for this particular module.

encodeUrl

Required: no Default: true

This directive controls the encoding of URLs. It is on by default, so if you have any special characters in your URL, they will be automatically encoded. But there might be situations where you don’t want your URL to be encoded automatically, or you want to control what parts of the URL are encoded. To do this, set this flag to false.

For example, you might have a URL component that includes a / and it must be encoded as %2F, but Apps treat your slashes as URL path delimiters by default. I.e. you need the URL to look like https://example.com/Hello%2FWorld, but instead, it looks like https://example.com/Hello/World, which is a totally different URL. So the obvious solution would be to just use {{encodeURL(parameters.component)}}. But when you do that, you will receive %252F, because your URL is encoded twice: once by you in your IML expression, and the second time by Apps. To disable this behavior, set this flag to false.

method

Required: no Default: GET Values: GET, POST, PUT, DELETE, PATCH (and other HTTP methods)

This directive specifies the HTTP method that will be used to issue the request. Possible values are GET (default), POST, DELETE, PUT, PATCH etc. You can specify the method with an IML expression based on module parameters, like so:

{
    "url": "http://example.com/entity",
    "method": "{{if(parameters.create, 'POST', 'PUT')}}" 
}

headers

Required: no

This directive specifies headers that will be sent with the request. All header names are case insensitive, so x-requested-with is the same as X-Requested-With.

Example:

{
    "url": "http://example.com/data",
    "headers": {
        "X-Item-Id": "{{parameters.id}}"
    }
}

qs

Required: no

This directive specifies the query string to use when making the request.

Note: When specifying this directive, the original query string specified in the URL will be lost. The qs directive takes precedence over the query string specified in the URL. Example:

{
    "url": "http://example.com?foo=bar&baz=qux",
    "qs": {
        "foo": "foobar",
        "hello": "world"
    }
}

This will issue a request to this URL: http://example.com?foo=foobar&hello=world. Notice that all the parameters from the original URL were replaced by the parameters specified in qs directive.

Note 2: When specifying qs as an empty object, it means that you want to erase all query string parameters. Example:

{
    "url": "http://example.com?foo=bar&baz=qux",
    "qs": {}
}

This will issue a request to this URL: http://example.com. Notice that all the query string parameters from the original URL were removed. That is because qs directive takes precedence over url query string parameters. If you want to specify query string parameters in url, you should remove the qs directive.

ca

Required: no

This directive allows you to enter your Self-Signed Certificate.

The value should be the PEM encoded self-signed certificate.

Example:

Certificate

-----BEGIN CERTIFICATE-----
xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy
zzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzz
adfadsfasdfnaludfhjkasdfadsfadfadfabas
iouqrpoernqepcqoweiqjcqponopqqfowepfqo
-----END CERTIFICATE-----

Module

Communication

{
    "url": "https://www.example.com",
    "qs": {},
    "ca": "-----BEGIN CERTIFICATE-----\nxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx\nyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy\nzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzz\nadfadsfasdfnaludfhjkasdfadsfadfadfabas\niouqrpoernqepcqoweiqjcqponopqqfowepfqo\n-----END CERTIFICATE-----",
    "body": {},
}

Rows in the certificate should be also in the app using

body

Required: no

This directive specifies the request body when the method directive is set to anything except GET. If the body is specified and the method directive is set to GET - body is ignored and appropriate Content-Type headers are not set.

Example:

{
    "url": "http://example.com/post",
    "body": {
        "first_name": "{{parameters.firstName}}",
        "last_name": "{{parameters.lastName}}"
    }
}

Note: If you want to specify an XML request body, you can specify it as a string that will use IML expressions to pass values to XML nodes. Example:

{
    "url": "http://example.com/post",
    "body": "<request><rows><row><column name=\"first_name\">{{parameters.firstName}}</column><column name=\"last_name\">{{parameters.lastName}}</column></row></rows></request>"
}

Note: If you need to send a JSON string inside a JSON object, use createJSON() function.

type

Required: no Default: json Values: json, urlencoded, multipart/form-data, text (or string or raw), binary.

This directive specifies how the request body will be encoded and sent with the request, when the method is anything but GET: POST, PUT, etc.

When the method is GET this directive will be ignored.

Note: When using text (or string or raw) the body should be a string. If it is not, it will be converted to the string.

Note 2: When using json or multipart/form-data or urlencoded the appropriate value of Content-Typeheader will be set automatically based on what type you have specified.

temp

Required: no

The temp directive specifies an object, which can be used to create custom temporary variables. It also creates a temp variable in IML, through which you then access your variables. The temp collection is not persisted and will be lost after the module is done executing.

This directive is executed prior to everything else: before condition, url, qs, body or any other directive. This makes it a good place to store some values that you need receptively.

When you have multiple requests, this directive is also useful for passing values between requests.

Note: When specifying temp directives in different requests and in the response section (response.tempdirective), the contents of the temp collection are not overwritten, but instead merged. Example:

[
    {
        "temp": {
            "foo": "bar"
        },
        "response": {
            "temp": {
                "foo": "baz",
                "hello": "world"
            }
        }
    },
    {
        "temp": {
            "param1": "bar-{{temp.foo}}", // will be "bar-baz"
            "param2": "hello, {{temp.hello}}" // will be "hello, world"
        },
        "response": {
            "temp": {} // will have the following properties:
                       // temp.foo == "baz"
                       // temp.hello == "world"
                       // temp.param1 == "bar-baz"
                       // temp.param2 == "hello, world"
        }
    }
]

condition

Required: no Default: true

This directive specifies whether to execute the request or not.

If this directive is not specified - the request will always be executed.

If the value of this directive is false, then the request will not be executed, and the flow will go to the next request, if present, or return nothing.

When you need to return some data when the condition is false, you are able to specify the condition directive as an object, in which case it will have the following properties:

Key	Type	Description
condition	IML String	Specifies if to execute the request or not.
default	Any IML Type	Specifies the module output when the condition is false.

repeat

Required: no

The repeat directive repeats a request as long as the test condition evaluates to true. The condition is evaluated after each request. There can be defined a delay between each request. The maximum number of repeats can be bounded by the limit.

The temp directive must be used within repeat in common cases. Reason: The condition expression has no access to body.data directly, therefore the response must be stored to temp object first, then use temp in condition expression.

Key	Type	Description
condition	IML String	A condition expression evaluated after each request iteration. If this condition evaluates to true, the request is called again after specified delay. When condition evaluates to false, the repetition is finished. Note: The condition has access to `temp` object only, not to `body`.
delay	Number	Specifies the delay between two repeates in miliseconds.
limit	Number	Specifies the maximum number of iterations. Optional. Not limited if not specified.

{
    "url": "...",
    ...,
    "response": {
        "temp": {...},  // Store response data to be able to access it in `condition`
        "output": null
    },
    "repeat": {
        "condition": "{{expression}}",  // Condition returning boolean
        "delay": 1000,                  // Delay in miliseconds
        "limit": 10                     // Max iterations
    }
}

delay and limit must be hard-coded. They do not support {{ }}.

Strongly recommended to set the limit to prevent infinite loop.

Common use case:

The needs to wait until some server process is finished. Common flow for this case is:

1. Request an API to initiate some server task.

2. Periodically check the status of the task and wait until task is done. Directive repeat helps you here.

3. Download the task result.

Example:

{
    "url": "/api/pdf-generate/status/{{temp.documentID}}",
    "method": "GET",
    "response": {
        // Store the response data into `temp` for `repeat` directive beeing able to access it
        "temp": {
            "status": "{{body.data.status}}"
        },
        "output": null
    },
    "repeat": {
        "condition": "{{temp.status === 'waiting' || temp.status === 'processing'}}",
        "delay": 20000,
        "limit": 50
    },

aws

It is sometimes very tedious and hard to generate AWS signatures. So we have provided a helper directive, that will simplify this task. Below are all the properties that you can use to customize the signature generation.

Key	Type	Description
key	IML String	AWS key
secret	IML String	AWS secret
session	IML String	AWS session. Note that this only works for services that require session as part of the canonical string
bucket	IML String	AWS bucket, unless you’re specifying your bucket as part of the path, or the request doesn’t use a bucket
sign_version	IML String	Default: 2. AWS sign version. Must be either 2 or 4.
service	IML String	AWS service name. Condition: sign_version must be 4.

followRedirect

Required: no Default: true

This directive specifies whether to follow GET HTTP 3xx responses as redirects or never.

This parameter allows only static input true or false.

Mapping "followRedirect": "{{parameters.followRedirect}}" is not supported.

followAllRedirect

Required: no Default: true

This directive specifies whether to follow non-GET HTTP 3xx responses as redirects or never.

This parameter allows only static input true or false.

Mapping "followAllRedirect": "{{parameters.followAllRedirect}}" is not supported.

log

Required: yes

This directive specifies logging options for both the request and the response.

{
    "url": "http://example.com/post",
    "headers": {
        "authorization": "Bearer {{connection.accessToken}}"
    },
    "log": {
        "sanitize": ["request.headers.authorization"]
    }
}

sanitize

An array of paths to sanitize when logging a request or response. Sanitizing sensitive information such as tokens, API keys or passwords is mandatory. See the following example to sanitize the request authorization header:

{
    "url": "http://example.com/post",
    "headers": {
        "authorization": "Bearer {{connection.accessToken}}"
    },
    "log": {
        "sanitize": ["request.headers.authorization"]
    }
}

You can sanitize the response in the same fashion:

{
    "url": "http://example.com/post",
    "log": {
        "sanitize": ["response.body.access_token"]
    }
}

Each item of sanitizing directive is defined in dot notation and is case insensitive. You can access nested structures of response bodies as well.