Invoke

Apply the Invoke policy to call another service from within your assembly. The response from the backend is stored either in the variable message.body or in the response object variable if it is defined. The policy can be used with JSON or XML data, and can be applied multiple times within your assembly.

Gateway support

Table 1. Table showing which gateways support this policy, and the corresponding policy version
Gateway	Policy version
DataPower® Gateway (v5 compatible)	1.0.0
DataPower API Gateway	2.0.0

This topic describes how to configure the policy in the assembly user interface; for details on how to configure the policy in your OpenAPI source, see invoke.

About

You can attach this policy to the following API flows:

REST
SOAP

Users might notice that the last invoke in their policy is replaced by a proxy. The replacement is sometimes done automatically by the IBM® API Connect DataPower Gateway to improve performance. The proxy is functionally equivalent to the invoke, but the API caller might notice the following differences when proxy is used.

If the HTTP request made by the invoke or proxy gets a redirect (3xx) response:
- invoke returns the response from following the redirect response.
- proxy does not follow 3xx responses, and the redirect response is returned.
The IBM API Connect test tool shows that proxy was used, but invoke appears in the Analytics latency records.
The response from the proxy can contain different whitespace or escaping than a response from invoke. Despite the differences in the response, it is still valid.

If you want to prevent replacement of the last invoke in the assembly with proxy, you can set the API property api.properties.x-ibm-gateway-optimize-invoke to false. For more information, see API properties

Note:

The Invoke policy does not support responses with multipart form data, that is, when the response is set to Content-Type: multipart/related.
The Invoke policy always uses chunked encoding, which is not supported by the HTTP 1.0 protocol.

Properties

The following table lists the policy properties, indicates whether a property is required, specifies the valid and default values for input, and specifies the data type of the values.

Table 2. Invoke policy properties
Property label	Required	Description	Data type
Title	Yes	The title of the policy. The default value is `invoke`.	string
Description	No	A description of the policy.	string
URL	Yes	Specifies a URL for the target service. For a SOAP API, a URL is added by default. Where possible, the Invoke URL value is pre-supplied from information that is defined in the imported WSDL.	string
TLS profile	No	Specifies a TLS profile to use for the secure transmission of data.	string
Timeout	Yes	The time to wait before a reply back from the endpoint (in seconds). The default value is `60`.	integer
Username	No	The username to use for HTTP Basic authentication.	string
Password	No	The password to use for HTTP Basic authentication.	string
HTTP Method	Yes	The HTTP method to use for the Invoke. Valid values are: Keep GET POST PUT DELETE PATCH HEAD OPTIONS The default value is `GET`. However, if set to `Keep`, or the property is removed from the source, the HTTP method from the incoming request is used.	string
Compression	No	Select this check box to enable Content-Encoding compression on upload. The check box is cleared by default.	boolean
Cache Type	No	The cache type determines whether to cache documents, honoring or overriding the HTTP Cache Control directives received in the response from the target URL. This property takes effect only when a response is received, otherwise the policy always returns the non-expired response that was previously saved in cache. Valid values are: Protocol The cache behavior is determined by the Cache-Control headers on the response, in accordance with RFC 7234. To optimize performance, if the gateway receives more than one request for a resource that is not in the cache but could be cached when the response from the target URL is received, the gateway sends only one request to the target URL; the remaining requests are not processed until the response from the first request has been received and the cache behavior has been determined from this response. If the response indicates that caching is possible, the gateway responds to all waiting requests with the cached resource. If the response indicates that caching is not possible, the gateway sends all waiting requests to the target URL. Use this option only if you expect that responses from the target URL can be cached, in which case it should improve performance and limit the demand on the target URL. If, however, the target URL never indicates that the gateway should cache its response, performance might be impaired when compared to the No Cache option. No Cache Responses from the target URL are not cached on the gateway regardless of any caching headers returned. In this case, every request from the client is sent to the target URL. Use this option if you do not want to cache any of the backend responses on the gateway, or if it is unlikely that a response from the target URL will allow caching through the Cache-Control header settings. Time to Live This option is similar to the Protocol option except it allows you to specify the amount of time that you want the successful response from the invoke or proxy to remain in the cache. Use this option only if you expect that responses from the target URL can be cached. The default value is Protocol.	string
Time to Live	No	Specifies the amount of time in seconds that the response stays in the cache. Applies only if the property Cache type is set to `Time to Live`. Enter a value in the range 5 - 31708800. The default value is `900`.	integer
Cache key	No	Specifies the unique identifier of the document cache entry. If omitted, the entire URL string is used as the key.	string
Inject proxy headers	No	If you select this check box, the `invoke` policy injects the `X-Forwarded-For`, `X-Forwarded-To`, `X-Forwarded-Host`, and `X-Forwarded-Proto` headers to the request that is sent to the target URL. The check box is cleared by default.	boolean
Decode Request Params	No	If you select this check box, any request parameters that are referenced by a variable definition on the target URL of the invoke policy are URL-decoded. The check box is cleared by default.	boolean
Queryparam Encode	No	If you select this check box, all "+" characters in the query parameter values of the target URL are encoded to %2F. The check box is cleared by default.	boolean
Keep Payload	No	If you select this check box, the invoke policy sends a payload on an `HTTP DELETE` method. The check box is cleared by default.	boolean
Restrict to HTTP 1.0 (policy version 2.0.0 only)	No	If you select this check box, HTTP transactions are restricted to version 1.0. The check box is cleared by default.	boolean
Allow chunked uploads	No	If you select this check box, chunked-encoded documents are sent to the server. When the HTTP 1.1 protocol is used, the body of the document can be delimited by either `Content-Length` or chunked encoding. While all servers can interpret `Content-Length`, many applications fail to understand chunked-encoded documents. For this reason, `Content-Length` is the standard method. The use of `Content-Length` interferes with the ability of the DataPower Gateway to fully stream. If you must stream full documents to the target server, enable this property. When enabled, the server must be RFC 2616 compatible. Unlike all other HTTP 1.1 features that can be negotiated down at run time, you must know beforehand that the target server is RFC 2616 compatible. The check box is selected by default. Note: Chunked encoding is not supported by the HTTP 1.0 protocol.	boolean
Header control	No	Specifies the headers in `message.headers` that you want to copy to the target URL. To prevent headers from being copied, complete the following steps: Select Blacklist. Click Add blacklist. In the empty field that is displayed, enter the header name. To add further headers, repeat the previous steps. To specify headers that you want to be copied, complete the following steps: Select Whitelist. Click Add whitelist. In the empty field that is displayed, enter the header name. To add further headers, repeat the previous steps. The values that you specify are in regular expression format. For example, to specify the Content-Type header, enter `^Content-Type$` By default, Blacklist is selected, with no blacklist entries, meaning that all headers are copied.	string
Parameter control	No	Specifies the parameters in the incoming request that you want to be copied to the target URL. To prevent parameters from being copied, complete the following steps: Select Blacklist. Click Add blacklist. In the empty field that is displayed, enter the parameter name. To add further parameters, repeat the previous steps. To specify parameters that you want to be copied, complete the following steps: Select Whitelist. Click Add whitelist. In the empty field that is displayed, enter the parameter name. To add further parameters, repeat the previous steps. The values that you specify are in regular expression format. For example, if the incoming request is `http://apigw/org/sandbox/petstore/base?petid=100&display=detailed` and you specify a white list entry of `^petid$`, the target URL at run time will be `http://myhost/mypath?storeid=3&petid=100` By default, Whitelist is selected, with no whitelist entries, meaning that no parameters are copied.	string
Stop on error	No	Select the errors that, if thrown during the policy execution, cause the assembly flow to stop. If there is a `catch` flow configured for the error, it is triggered to handle the error thrown. If an error is thrown and there are no errors selected for the Stop on error setting, or if the error thrown is not one of the selected errors, the policy execution is allowed to complete, and the assembly flow continues.	string
Response object variable	No	The name of a variable that will be used to store the response data from the request. By default, the invoke response, that is the body, headers, statusCode and statusMessage, is saved in the variable `message`. Use this property to specify an alternate location to store the invoke response. This variable can then be referenced in other actions, such as Map. Note: If you want the response to be saved in `message`, leave the Response object variable property blank, do not supply the value `message`.	string

Example

- invoke:
    version: 2.0.0
    title: get the account status
    target-url: https://example.com/accounts/{id}?status={status}
    cache-response: time-to-live
    cache-putpost-response: true
    tls-profile: MyTLSProfile
    verb: POST
    timeout: 60
    compression: false 
    username: MyUser
    password: MyPassword
    stop-on-error:
      - ConnectionError
      - OperationError