Version: 4.49.0-beta

HTTP request 2

The HTTP request component allows you to execute HTTP requests.

It supports methods GET, POST, PUT, DELETE, and PATCH and has built-in support for basic and bearer token authentication. It also features so-called hooks, which allow you to execute JavaScript code before and after the request is made.

Configuration

General

Request method

The request method used when sending the request. (default: GET)

URL

The URL to send the request to.

Configure header

Enables you to configure headers.

headers is a JSON object with the header name as the key and the header value as the value.

Configure body

Enables you to configure the request body.

Body as

The type of the body. (default: json).

When using the binary option, the localReference is required in the body.

When using the form-data option, at least one of the multipartText or multipartBinary is required in the body.

There is an example for both scenarios at the end of this section.

Hooks

A hook lets you execute plain JavaScript code within a sandbox making it secure and safe.

It has the same functions as the code component with a few additions:

ctx gives you access to the context of the message. This allows you to access the incoming message and the response using ctx.value and ctx.result respectively.

setMethod(method: string); is used to set the method of the request.

setURL(url: string, query: string); is used to set the URL of the request.

setHeader(key: string, value: string); is used to set a header of the request.

setResponseType(responseType: string); is used to set the response type of the request.

setBody(body: string); is used to set the body of the request.

setJSONBody(body: object); is used to set the body of the request as JSON.

setFormBody(body: object); is used to set the body of the request as form data.

setMultipartBody(body: object); is used to set the body of the request as multipart form data.

await request(url: string, options: object); executes a request. The options can be used to overwrite the configured options and can contain nearly all configuration options.

Example options object:

{
  "method": "GET",
  "url": "https://example.com",
  "headers": {
    "Content-Type": "application/json"
  },
  "body": {
    "hello": "world"
  },
  "bodyAs": "json", // options: json, binary, form-data, text and x-www-form-urlencoded
  "responseType": "json", // options: json, xml, text, buffer, content-store and file-store
  "requestTimeout": 1000,
  "responseTimeout": 1000,
  "followRedirects": true,
  "maxRedirects": 10,
  "authType": "none", // options: none, basic, bearer, oauth and ntlm
}

note

When authType is set in the options, the component will use the configured authentication settings.

setLocal(key: string, value: any); use to set a local variable in the context of message. This can be used to share data between the two hooks.

getLocal(key: string); use to get a local variable in the context of message.

Before hook

The before hook is triggered before the request is sent. It allows you to modify the request before it is sent. The following functions are available in the before hook to help you do dynamic requests:

After hook

The after hook is triggered after the request is made. It allows you to post-process the response before it is send.

note

Recursive functions for traversing a directory structure are possible, but not recommended. Use multiple instances of the component instead. An example can be found in the Alfresco source accelerator.

Calling done

Because JavaScript allows you to write code asynchronously, you need to call the done function when your code is done. When you are not using any asynchronous syntax, the done call should be at the end of your script.

// your code
done();

note

In cases where you are calling return in the global scope, you need to call done before the return statement.

Authentication

Type

The type of authentication used. Options: 'basic', 'bearer' (default: none).

For basic authentication, the username and password are required.

For bearer authentication, the token is required.

For NTLM authentication, the username and password are required. Domain and workstation are optional.

Rate limit

Request limit

The max amount of requests during the interval.

Interval

The interval in milliseconds in which the requests happen.

Max concurrent

The maximum concurrent executions per message.

Response

Resolve body only

If enabled it will only resolve the body of the response. This works for the output of the component. The response body won't be resolved within the after-hook yet. When using the body there, make sure to explicitly look up ctx.result.body.

Type

The type of response. (default: json)

TLS Options

Allow Invalid Certificated

When set to true, the server certificate is not verified. Verification happens at the connection level, before the HTTP request is sent. This setting can be useful when your server is using self-signed certificates. (default: false)

Certificate Authority File

One or more certificate authorities to trust when making a TLS connection. In order to access the local filesystem, the XILL4_WORKDIRS environment variable must be set to the path of the directory to be accessed.

Example: ./ca.pem

Mutual TLS

When enabled, the client certificate and key are used to authenticate the client to the server. (default: false)

Client Certificate File

The client certificate file. In order to access the local filesystem, the XILL4_WORKDIRS environment variable must be set to the path of the directory to be accessed.

Example: ./client.pem

Client Key File

The client key file. In order to access the local filesystem, the XILL4_WORKDIRS environment variable must be set to the path of the directory to be accessed.

Example: ./client.key

XML Parser Options

Allow Boolean Attributes
Allows attributes without value. By default boolean attributes are ignored. When set to true:

<hello checked>
  world
</hello>

will be parsed to:

{
  hello: {
    "@_checked": true,
    "#text": "world"
  }
}

Always Create Text Node
Force rendering a tag with text-node. Otherwise, it creates a property with the tag name and assign the value directly.
Example:

<hello>
  world
</hello>

With alwaysCreateTextNode set to false:

{
  hello: "world"
}

With alwaysCreateTextNode set to true:

{
  hello: {
    "#text": "world"
  }
}

Parse Comments
Comments are parsed with prop name @_comments.
Example:

<hello>
  <!--world-->
</hello>

Will parse to:

{
  hello: {
    "@_comments": "world"
  }
}

Ignore Attributes
Attributes are ignored by the parser. By default set to true. This also means that any configuration regarding attributes will not apply.

Parse Attribute Value
Force parsing the attribute value. This is relevant when attribute values have another type than string.
Example:

<hello attr="true">
  world
</hello>

With parseAttributeValue to false:

{
  hello: {
    "@_attr": "true"
  }
}

With parseAttributeValue to true:

{
  hello: {
    "@_attr": true
  }
}

Parse Tag Value
Force parsing the tag value. Same logic applies as with parseAttributeValue.

Preserve Order
Used to keep the order of tags in the result object.

Remove NS Prefix
Remove namespace string from tag and attribute names.
Example:

<ns:hello ns:attr="true">
  world
</ns:hello>

Will parse to:

{
  "hello": {
    "@_attr": "true"
  }
}

Unpaired Tags
Unpaired Tags are the tags which don't have matching closing tag. Eg <br> in HTML. You can parse unpaired tags by setting the unpaired tags separated by a comma (,).
Example:

<hello>
  world
  <br>
</hello>

With unpairedTags set to br will parse to:

{
  hello: {
    "#text": "world",
    unpaired: ""
  }
}

Timeout

Request timeout

The request timeout in milliseconds. The time in which the headers need to be received.

Response timeout

The response timeout in milliseconds. The total time for the request.

Redirects

Follow redirects

If enabled it will follow redirects.

Maximum number of redirects to follow

The maximum number of redirects to follow.

Content Store

Enable Content Store / Enable lookup function

If enabled, the component create a connection to the Content Store. This allows the component to read and write files from and to the Content Store and enables the use of the lookup function. For more information about the lookup function, see the Code component.

Connection string

A MongoDB connection string.

Example: mongodb://<username>:<password>@localhost:27017/<databaseName>

Here <databaseName> is the database to use.

Use TLS

Whether or not to use TLS in case your mongoDB requires TLS.

Allow Invalid Certificates

Checking this will disable certificate validation. Warning: specifying this option in a production environment makes your application insecure and potentially vulnerable to expired certificates and to foreign processes posing as valid client instances.

Certificate Authority File

IOne or more certificate authorities to trust when making a TLS connection. In order to access the local filesystem, the XILL4_WORKDIRS environment variable must be set to the path of the directory to be accessed.

Example: .\ca.pem

Inputs

Name: Input
- Description: Can be any message for triggering the request.

Outputs

Name: Output
- Description: The response of the request including the incoming message.
- Example:
```
{
  "value":{
    //...incoming message
  },
  "result":{
    //...response
  }
}
```
  Prior to version 4.35.0 the incoming message was not included.
```
{
  //...response
}
```

Downloading files

When the response body has a stream and it needs to be downloaded to the content store, set the responseType to content-store and make sure content store is enabled in the settings of the component. It will result in a response object with localReference. This refers to the id of the saved binary in the content store.

Uploading files

To upload a file, you can set bodyAs to binary or form-data. When using form-data, you can also add other form fields.

Example body when uploading a file using binary and the file source is a file path:

{
  "externalReference" : "C:\\Users\\xill\\Desktop\\test.txt",
}

Example body when uploading a file using binary and the file source is the Content Store:

{
  "localReference" : "f02a73168ae19095d70f8f0ebc84cd135add4ccf8e008a9723a53c4865609f13ceed0079b8f56f92f1906843c8891e3165d198645c3bd33df5a224665a1060d1",
}

Example body when uploading a file using form-data and the file source is a file path:

{
  "multipartText" : {
    "field1" : "value1",
    "field2" : "value2"
  },
  "multipartBinary":{
    "field3" : "C:\\Users\\xill\\Desktop\\test.txt",
  }
}

note

With form-data a key is not unique and can be used multiple times. To do this you can wrap the key value pairs in an array.

{
  "multipartText" : [
    {"field1" : "value1"},
    {"field1" : "value2"}
  ],
  "multipartBinary":[
    {"field3" : "C:\\Users\\xill\\Desktop\\test.txt"}
    {"field3" : "C:\\Users\\xill\\Desktop\\test2.txt"}
  ]
}

Example body when uploading a file using form-data and the file source is the Content Store.

{
  "multipartText" : {
    "field1" : "value1",
    "field2" : "value2"
  },
  "multipartBinary":{
    "field3" : {
      "localReference" : "f02a73168ae19095d70f8f0ebc84cd135add4ccf8e008a9723a53c4865609f13ceed0079b8f56f92f1906843c8891e3165d198645c3bd33df5a224665a1060d1",
      "fileName" : "test.txt"
    }
  }
}

Notice how field3 now is an object with a localReference property and a mandatory fileName property. This is because the filename can't be derived from the binary.

In case that the keys are not unique you can wrap the fields in array.

{
  "multipartText" : [
    {"field1" : "value1"},
    {"field1" : "value2"}
  ],
  "multipartBinary": [
    {
      "field3" : {
        "localReference" : "f02a73168ae19095d70f8f0ebc84cd135add4ccf8e008a9723a53c4865609f13ceed0079b8f56f92f1906843c8891e3165d198645c3bd33df5a224665a1060d1",
        "fileName" : "test.txt"
      }
    },
    {
      "field3" : {
        "localReference" : "f02a73168ae19095d70f8f0ebc84cd135add4ccf8e008a9723a53c4865609f13ceed0079b8f56f92f1906843c8891e3165d198645c3bd33df5a224665a1060d1",
        "fileName" : "test2.txt"
      }
    }
  ]
}

Multi-part form data

When using form-data as the bodyAs value, at least one of multipartTextor multipartBinary is required. This property should be an object with the field names as keys and the field values as values.

HTTP request 2

Configuration​

General​

Hooks​

Before hook​

After hook​

Calling done​

Authentication​

Rate limit​

Response​

TLS Options​

XML Parser Options​

Timeout​

Redirects​

Content Store​

Enable Content Store / Enable lookup function​

Inputs​

Outputs​

Downloading files​

Uploading files​

Multi-part form data​

Configuration

General

Hooks

Before hook

After hook

Calling done

Authentication

Rate limit

Response

TLS Options

XML Parser Options

Timeout

Redirects

Content Store

Enable Content Store / Enable lookup function

Inputs

Outputs

Downloading files

Uploading files

Multi-part form data