Using local environment variables with REST nodes

The REST request nodes support a number of local environment message tree variables, which you can use to dynamically alter the values that are set in the node properties.

The following table shows elements in the LocalEnvironment.Destination.REST.Request message tree, which can be used to override properties in the RESTRequest and RESTAsyncRequest nodes. Any properties that are set by the local environment variables will apply to both the RESTRequest and RESTAsyncRequest nodes.

The table includes examples of how to set the values by using ESQL; however, you can also set them by using transformation nodes, such as the Mapping node. To access the LocalEnvironment from a Mapping node, see Customizing a message map to include a message assembly component.
Table 1. Input local environment properties
Element name Type Description
Operation string The value is the name of the operation to invoke in the REST API. This environment variable overrides the Operation property on the node. For example:
SET OutputLocalEnvironment.Destination.REST.Request.Operation = 'updateCustomerByID';
Parameters.parameter_name string Specify values to use for the parameters of the operation. The values that are specified in the LocalEnvironment override any literal values or XPath/ESQL expressions that are specified in the Parameters table on the node. For example:
SET OutputLocalEnvironment.Destination.REST.Request.Parameters.max = 10;
SET OutputLocalEnvironment.Destination.REST.Request.Parameters.filter = 'Fred Bloggs';
Note: If the values are XPath/ESQL expressions, the values are passed to the remote REST API as string literals (and not evaluated as XPath/ESQL expressions).

To define the REST parameters and set their values in a message map, use the Add User Defined function to add the parameter_name element, and then provide a mapping to set its value. For more information, see Configuring the local environment tree Variables folder by using the Add User Defined function.

To specify an array parameter, define the parameter multiple times. For example, an array property that is called list with values 'a', 'b', and 'c', can be defined as:

SET OutputLocalEnvironment.Destination.REST.Request.Parameters.list[1] = 'a';
SET OutputLocalEnvironment.Destination.REST.Request.Parameters.list[2] = 'b';
SET OutputLocalEnvironment.Destination.REST.Request.Parameters.list[3] = 'c';
To specify an object parameter, specify the object properties and their values as children of the element. For example, an object parameter called the parameter multiple times. For example, an array property that is called color with values red = 100, green = 200, and blue = 300, can be defined as:

SET OutputLocalEnvironment.Destination.REST.Request.Parameters.colour.red = 100;
SET OutputLocalEnvironment.Destination.REST.Request.Parameters.colour.green = 200;
SET OutputLocalEnvironment.Destination.REST.Request.Parameters.colour.blue = 300;
ContentType string The value is the value of the Content-Type header to send in the request to the REST API. This environment variable overrides the Content-Type property on the node. For example:
SET OutputLocalEnvironment.Destination.REST.Request.ContentType = 'application/vnd.ibm-demo+json';
Accept string The value is the value of the Accept header to send in the request to the REST API. This environment variable overrides the Accept property on the node. For example:
SET OutputLocalEnvironment.Destination.REST.Request.Accept = 'application/json';
SecurityIdentity string The value must be the name of a security identity that is defined with the mqsicredentials, ibmint set credential, or mqsisetdbparms command. Do not include the "rest::" prefix. This environment variable overrides the Security identity property on the node. For example:
SET OutputLocalEnvironment.Destination.REST.Request.SecurityIdentity = 'myApiKey';
UserID string If this environment variable is specified, it overrides all the values that are specified by the LocalEnvironment.Destination.REST.Request.SecurityIdentity override and the Security identity property on the node.

If the LocalEnvironment.Destination.REST.Request.UserID environment variable is specified, the LocalEnvironment.Destination.REST.Request.Password environment variable is also required.
Password string If this environment variable is specified, it overrides all the values that are specified by the LocalEnvironment.Destination.REST.Request.SecurityIdentity override and the Security identity property on the node.

If the LocalEnvironment.Destination.REST.Request.Password environment variable is specified, the LocalEnvironment.Destination.REST.Request.UserID environment variable is also required.
APIKey string If this environment variable is specified, it overrides all the values that are specified by the LocalEnvironment.Destination.REST.Request.SecurityIdentity override and the Security identity property on the node.

The LocalEnvironment.Destination.REST.Request.APIKey environment variable can be specified either alone or in conjunction with the LocalEnvironment.Destination.REST.Request.UserID and LocalEnvironment.Destination.REST.Request.Password environment variables.
BearerToken string

If this environment variable is specified, it overrides all the values that are specified by the LocalEnvironment.Destination.REST.Request.SecurityIdentity override and the Security identity property on the node.

The LocalEnvironment.Destination.REST.Request.BearerToken environment variable can be specified either alone or in conjunction with the LocalEnvironment.Destination.REST.Request.BearerToken environment variable.
Timeout integer The time (in seconds) that the node waits for the REST API to process the operation. This environment variable overrides the Request timeout (sec) property on the node. For example:
SET OutputLocalEnvironment.Destination.REST.Request.Timeout = 300;
BaseURL string This environment variable overrides the Base URL override property on the node, and the base URL specified in the Swagger document containing the definitions of the REST API. For example:
SET OutputLocalEnvironment.Destination.REST.Request.BaseURL = 'https://my-prod-server.ibm.com/customerdb/v1';
ProxyURL string This environment variable overrides the HTTP(S) proxy location property on the node. For example:
SET OutputLocalEnvironment.Destination.REST.Request.ProxyURL = 'http://my-proxy-server.ibm.com';
FollowRedirection boolean This environment variable overrides the Follow HTTP(S) redirection property on the node. For example: 
SET OutputLocalEnvironment.Destination.REST.Request.FollowRedirection = TRUE;
KeepAlive boolean This environment variable overrides the Enable HTTP 1/1 keep-alive property on the node. For example: 
SET OutputLocalEnvironment.Destination.REST.Request.KeepAlive = FALSE;
Compression string This environment variable overrides the Compression property on the node. Valid values are:
  • gzip
  • zlib-deflate
  • raw-deflate
For example: 
SET OutputLocalEnvironment.Destination.REST.Request.Compression = 'zlib-deflate';
Protocol string This environment variable overrides the Protocol property on the node. Valid values are:
  • TLS
  • TLSv1
  • TLSv1.2
  • TLSv1.3
  • SSL_TLS
  • SSL_TLSv2
For example: 
SET OutputLocalEnvironment.Destination.REST.Request.Protocol = 'TLSv1.2';
AllowedCiphers string This environment variable overrides the Allowed SSL Ciphers property on the node. For example: 
SET OutputLocalEnvironment.Destination.REST.Request.AllowedCiphers = 'SSL_RSA_FIPS_WITH_3DES_EDE_CBC_SHA';
HostnameChecking boolean This environment variable overrides the Enable SSL certificate hostname checking property on the node. For example: 
SET OutputLocalEnvironment.Destination.REST.Request.HostnameChecking = FALSE;
KeyAlias string This environment variable overrides the SSL client authentication key alias property on the node. For example: 
SET OutputLocalEnvironment.Destination.REST.Request.KeyAlias = 'myClientCertificate';
EnableCRLCheck boolean This environment variable overrides the Enable certificate revocation list checking property on the node. For example: 
SET OutputLocalEnvironment.Destination.REST.Request.EnableCRLCheck = TRUE;
AcceptCompressedResponses string This environment variable overrides the Accept compressed responses by default property on the node. For example: 
SET OutputLocalEnvironment.Destination.REST.Request.AcceptCompressedResponses = TRUE;
ServicePrincipalName string Specifies the Service Principal Name (SPN) to use when the integration node negotiates the Kerberos security protocol. For example: 
SET OutputLocalEnvironment.Destination.REST.Request.ServicePrincipalName = 'HTTP/iib.iibservice2.com:7800';
SecuritySchemes.security_scheme.SecurityIdentity string Specifies the name of a security identity to use for the specified security scheme. The specified security identity is used only for the specified security scheme.

If this environment variable is specified, it overrides the LocalEnvironment.Destination.REST.Request.SecurityIdentity override and the Security identity property on the node.

The name of the security scheme corresponds to the name of a Security Scheme Object in a Security Definitions Object in the Swagger document containing the definitions of the REST API.

The value must be the name of a security identity defined with the mqsicredentials, ibmint set credential, or mqsisetdbparms command. Do not include the "rest::" prefix. For example: 

SET OutputLocalEnvironment.Destination.REST.Request.SecuritySchemes.petstore_auth.SecurityIdentity = 'myIdentity3'
SecuritySchemes.security_scheme.UserID string Specify the user ID to use for the specified security scheme when using HTTP Basic Authentication. The specified user ID is used only for the specified security scheme.

If this environment variable is specified, it overrides the user ID specified in a security identity using either the LocalEnvironment.Destination.REST.Request.SecuritySchemes.security_scheme.SecurityIdentity or LocalEnvironment.Destination.REST.Request.SecurityIdentity overrides, and also the Security identity property on the node.

The name of the security scheme corresponds to the name of a Security Scheme Object in a Security Definitions Object in the Swagger document containing the definitions of the REST API. For example: 
SET OutputLocalEnvironment.Destination.REST.Request.SecuritySchemes.security_scheme.UserID='bob'
SecuritySchemes.security_scheme.Password string Specify the password to use for the specified security scheme when using HTTP Basic Authentication. The specified password is used only for the specified security scheme.

If this environment variable is specified, it overrides the password that is specified in a security identity using either the LocalEnvironment.Destination.REST.Request.SecuritySchemes.security_scheme.SecurityIdentity or LocalEnvironment.Destination.REST.Request.SecurityIdentity overrides, and also the Security identity property on the node.

The name of the security scheme corresponds to the name of a Security Scheme Object in a Security Definitions Object in the Swagger document containing the definitions of the REST API. For example:
SET OutputLocalEnvironment.Destination.REST.Request.SecuritySchemes.petstore_auth.Password='myPassword'
SecuritySchemes.security_scheme.APIKey string Specify the API key to use for the specified security scheme when using HTTP Basic Authentication. The specified API key is used only for the specified security scheme.

If this environment variable is specified, it overrides the API key that is specified in a security identity using either the LocalEnvironment.Destination.REST.Request.SecuritySchemes.security_scheme.SecurityIdentity or LocalEnvironment.Destination.REST.Request.SecurityIdentity overrides, and also the Security identity property on the node.

The name of the security scheme corresponds to the name of a Security Scheme Object in a Security Definitions Object in the Swagger document containing the definitions of the REST API. For example:
SET OutputLocalEnvironment.Destination.REST.Request.SecuritySchemes.petstore_auth.APIKey='438438920909329039032'
SecuritySchemes.security_scheme.BearerToken string

Specify the bearer token to use for the specified security scheme when using HTTP Bearer Authentication. The specified bearer token is used only for the specified security scheme.

If this environment variable is specified, it overrides the bearer token that is specified in a security identity using either the LocalEnvironment.Destination.REST.Request.SecuritySchemes.security_scheme.SecurityIdentity or LocalEnvironment.Destination.REST.Request.SecurityIdentity overrides, and also the Security identity property on the node.

The name of the security scheme corresponds to the name of a Security Scheme Object in a Security Definitions Object in the openapi document containing the definitions of the REST API. For example: 
SET OutputLocalEnvironment.Destination.REST.Request.SecuritySchemes.petstore_auth.BearerToken='token123'
UserContext mixed content Specify context data to be stored by the RESTAsyncRequest node. The data can later be accessed by the RESTAsyncResponse node for the matching request.

You can use the user context to specify data that will be passed from the RESTAsyncRequest node to the RESTAsyncResponse node. To store user context data, prior to the RESTAsyncRequest node, either set a value in the OutputLocalEnvironment.Destination.REST.Request.UserContext environment variable or create and populate child nodes below it.

For example, to set the values by using an ESQL expression:
SET OutputLocalEnvironment.Destination.REST.Request.UserContext = 'Some important information';
SET OutputLocalEnvironment.Destination.REST.Request.UserContext.Name.FirstName = 'Fred';
SET OutputLocalEnvironment.Destination.REST.Request.UserContext.Name.Surname = 'Bloggs';
SET OutputLocalEnvironment.Destination.REST.Request.UserContext.MyData.Binary = CAST('A piece of data' AS BLOB CCSID 1208);

You can use a Mapping node to set a value, by mapping to the mixed child element OutputLocalEnvironment.Destination.REST.Request.UserContext.mixed. To use a Mapping node to create sub-elements, use user-defined elements or cast xsd:any and map to them. For more information, see RESTAsyncRequest node.

To access the user context data after a RESTAsyncResponse node, read the value or children of the LocalEnvironment.REST.Response.UserContext environment variable.
QueryStringDoNotPercentEncodeCharacters String Specifies those characters in the query string that are not to be percent encoded while the URI is built.
For example, to specify that the comma and greater than symbols are not to be percent encoded:
SET OutputLocalEnvironment.Destination.REST.Request.QueryStringDoNotPercentEncodeCharacters = ',>';

The default set of characters not to be percent encoded is asterisk (*), minus (-), period (.), and underscore (_).
The following table shows the data that is written by the RESTRequest node to the LocalEnvironment when propagating an output message:
Table 2. Output local environment properties generated by the RESTRequest node
Element Type Description
LocalEnvironment.WrittenDestination.REST.Method string The HTTP method used when invoking the operation in the REST API.
LocalEnvironment.WrittenDestination.REST.URL string The URL used when invoking the operation in the REST API.
LocalEnvironment.WrittenDestination.REST.RequestHeadersSize integer The size of the request headers sent to the REST API.
LocalEnvironment.WrittenDestination.REST.RequestBodySize integer The size of the request body that is sent to the REST API.
LocalEnvironment.WrittenDestination.REST.StatusCode integer The HTTP status code in the response from the REST API.
LocalEnvironment.WrittenDestination.REST.ResponseHeadersSize integer The size of the response headers received from the REST API.
LocalEnvironment.WrittenDestination.REST.ResponseBodySize integer The size of the response body received from the REST API.
LocalEnvironment.WrittenDestination.REST.TotalRequestTime integer The total elapsed time invoking the operation in the REST API.
LocalEnvironment.WrittenDestination.REST.ResponseCode string

The HTTP status code, or status code range defined on responses section the invoked operation in the OpenAPI document. If the status code is not in the list of expected response codes, then the status code as a string is as follows:

For example, if the responses section lists status codes 200, and 2XX, then a response with StatusCode of 200 will have a ResponseCode of 200, but a response of StatusCode 204 will have a ResponseCode of 2XX, and a response with a StatusCode of 300 will have a ResponseCode of 300.
LocalEnvironment.WrittenDestination.REST.ResponseCodeExpected boolean

True if the HTTP status code for the response appeared in the list of expected response codes that are defined on the operation in the OpenAPI document.

For example, if the responses section lists status codes 200, and 2XX, then a response with StatusCode of 200 or 204 will have a ResponseCodeExpected of TRUE, but a response with StatusCode of 300 will have a ResponseCodeExpected of FALSE.
The following table shows the data that is written by the RESTAsyncRequest node when propagating an output message:
Table 3. Output local environment properties generated by the RESTAsyncRequest node:
Element Type Description
LocalEnvironment.WrittenDestination.REST.Method string The HTTP method used when invoking the operation in the REST API.
LocalEnvironment.WrittenDestination.REST.URL string The URL used when invoking the operation in the REST API.
LocalEnvironment.WrittenDestination.REST.RequestHeadersSize integer The size of the request headers sent to the REST API.
LocalEnvironment.WrittenDestination.REST.RequestBodySize integer The size of the request body that is sent to the REST API.
LocalEnvironment.WrittenDestination.REST.CorrelationID blob The correlation ID used to correlate the request and response between the RESTAsyncRequest and RESTAsyncResponse nodes.
The following table shows the data that is written by the RESTAsyncResponse node when propagating an output message:
Table 4. Output local environment properties generated by the RESTAsyncResponse node:
Element Type Description
LocalEnvironment.REST.Response.CorrelationID blob The correlation ID used to correlate the request and response between the RESTAsyncRequest and RESTAsyncResponse nodes.
LocalEnvironment.REST.Response.StatusCode integer The HTTP status code in the response from the REST API.
LocalEnvironment.REST.Response.ResponseHeadersSize integer The size of the response headers received from the REST API.
LocalEnvironment.REST.Response.ResponseBodySize integer The size of the response body received from the REST API.
LocalEnvironment.REST.Response.UserContext mixed content The information that was stored in the OutputLocalEnvironment.Destination.REST.Request.UserContext can be retrieved by the response thread.
LocalEnvironment.REST.Response.ResponseCode string

The HTTP status code, or status code range defined on responses section the invoked operation in the OpenAPI document. If the status code is not in the list of expected response codes, then the status code as a string is as follows:

For example, if the responses section lists status codes 200, and 2XX, then a response with StatusCode of 200 will have a ResponseCode of 200, but a response of StatusCode 204 will have a ResponseCode of 2XX, and a response with a StatusCode of 300 will have a ResponseCode of 300.
LocalEnvironment.REST.Response.ResponseCodeExpected boolean

True if the HTTP status code for the response appeared in the list of expected response codes that are defined on the operation in the OpenAPI document.

For example, if the responses section lists status codes 200, and 2XX, then a response with StatusCode of 200 or 204 will have a ResponseCodeExpected of TRUE, but a response with StatusCode of 300 will have a ResponseCodeExpected of FALSE.