Invoke (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.

About

You can attach this policy to the following API flows:

REST
SOAP

From IBM® API Connect V5.0.8.0 and beyond, 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 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.

Note that a proxy policy ignores the Stop on error property, and that a replacement with a proxy does not occur if you have configured any catches on the invoke policy. For more information about the proxy policy, see Proxy (proxy). 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.

Important: If you are using API Connect in the cloud, then the services that you expose must be visible on the Internet, they must not be accessible only from within your corporate intranet. However, you can use TLS profiles configured in API Manager to protect the communication channel between the API Gateway in API Connect and the services that you expose on the Internet through your DMZ. You can also use the IBM Cloud Secure Gateway service to provide secure access to your on-premises services from IBM API Connect for IBM Cloud; for more information, see About Secure Gateway.

Note: The Invoke policy does not support responses with multipart form data, that is, when the response is set to Content-Type: multipart/related.

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 1. 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. Additional configuration is required to call applications that are hosted on collectives. For more information, see Modifying the assembly to call an application endpoint hosted on a collective.	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 Note: This is only a valid option when you are using it with an IBM DataPower appliance. If you are using microgateway, you must use a different value. 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
Stop on error	No	Select this check box to stop the flow and trigger a catch flow when a particular type of error is thrown. The following list shows the type of errors that can be selected: ConnectionError SOAPError OperationError The check box is selected by default, but you must also select one or more error types in the search errors field, or the flow will not stop and no catch flows will be triggered. If the check box is not selected, or no error types are selected, the flow will continue when an error is thrown during the policy execution.	boolean
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:
  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