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
Input
Can be any message for triggering the request.
Outputs
Output
The response of the request including the incoming message.
{
"value":{
//...incoming message
},
"result":{
//...response
}
}```
Prior to version 4.35.0 the incoming message was not included.
```json
{
//...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 that 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.