IntegrationCallout policy

This pageapplies toApigee andApigee hybrid.

The IntegrationCallout policy lets you run an Application Integration that has an API trigger. However, before running an integration, you must run theSetIntegrationRequest policy. The SetIntegrationRequest policy creates a request object and makes the object available to the IntegrationCallout policy as a flow variable. The request object has the integration details such as the API trigger name, integration project ID, integration name, and other details configured in the SetIntegrationRequest policy. The IntegrationCallout policy uses the flow variable of the request object to run the integration. You can configure the IntegrationCallout policy to save the integration run response in a flow variable.

The IntegrationCallout policy is helpful if you want to run integration in the middle of your proxy flow. Alternately, instead of configuring the IntegrationCallout policy, you can also run an integration by specifying an integration endpoint as your target endpoint. For more information, seeIntegrationEndpoint.

This policy is anExtensible policy and use of this policy might have cost or utilization implications, depending on your Apigee license. For information on policy types and usage implications, seePolicy types.

Note: You need an authentication token to run the IntegrationCallout policy. However, there is no explicitAuthentication element in the policy definition. Apigee adds an authentication token to the request under the hood. For the IntegrationCallout policy to successfully authenticate, you must deploy your API proxy with a service account that has the required IAM roles to run an integration. For information about the required roles, seeIAM roles for integrations. For more details on deploying an API proxy, seeDeploy on Apigee.

<IntegrationCallout>

Specifies the IntegrationCallout policy.

Default ValueN/A
Required?Required
TypeComplex type
Parent Element N/A
Child Elements<DisplayName>
<AsyncExecution>
<Request>
<Response>

The following table provides a high-level description of the child elements of<IntegrationCallout>:

Child ElementRequired?Description
<DisplayName>OptionalA custom name for the policy.
<AsyncExecution>OptionalSpecifies if the integration must run in synchronous mode or asynchronous mode.
<Request>RequiredThe flow variable having the request object created by the SetIntegrationRequest policy.
<Response>OptionalThe flow variable to save the integration's response.

The<IntegrationCallout> element uses the following syntax:

Syntax

<?xmlversion="1.0"encoding="UTF-8"standalone="no"?><IntegrationCalloutcontinueOnError="[true|false]"enabled="[true|false]"name=POLICY_NAME><DisplayName>POLICY_DISPLAY_NAME</DisplayName><AsyncExecution>BOOLEAN_ASYNC_EXECUTION</AsyncExecution><RequestclearPayload="[true|false]">REQUEST_FLOW_VARIABLE_NAME</Request><Response>RESPONSE_FLOW_VARIABLE_NAME</Response></IntegrationCallout>

Example

The following example shows the IntegrationCallout policy definition:

<?xmlversion="1.0"encoding="UTF-8"standalone="no"?><IntegrationCalloutcontinueOnError="false"enabled="true"name="Integration-Callout"><DisplayName>Integration-Callout-1</DisplayName><AsyncExecution>true</AsyncExecution><RequestclearPayload="true">my_request_flow_var</Request><Response>my_response_flow_var</Response></IntegrationCallout>

This element has the following attributes that are common to all policies:

AttributeDefaultRequired?Description
nameN/ARequired

The internal name of the policy. The value of thename attribute can contain letters, numbers, spaces, hyphens, underscores, and periods. This value cannot exceed 255 characters.

Optionally, use the<DisplayName> element to label the policy in the management UI proxy editor with a different, natural-language name.

continueOnErrorfalseOptionalSet tofalse to return an error when a policy fails. This is expected behavior for most policies. Set totrue to have flow execution continue even after a policy fails. See also:
enabledtrueOptionalSet totrue to enforce the policy. Set tofalse toturn off the policy. The policy will not be enforced even if it remains attached to a flow.
async  falseDeprecatedThis attribute is deprecated.

Child element reference

This section describes the child elements of<IntegrationCallout>.

<DisplayName>

Use in addition to thename attribute to label the policy in the management UI proxy editor with a different, more natural-sounding name.

The<DisplayName> element is common to all policies.

Default ValueN/A
Required?Optional. If you omit<DisplayName>, the value of the policy'sname attribute is used.
TypeString
Parent Element <PolicyElement>
Child Elements None

The<DisplayName> element uses the following syntax:

Syntax

<PolicyElement><DisplayName>POLICY_DISPLAY_NAME</DisplayName>  ...</PolicyElement>

Example

<PolicyElement><DisplayName>My Validation Policy</DisplayName></PolicyElement>

The<DisplayName> element has no attributes or child elements.

<AsyncExecution>

Specifies the mode to run the integration. You can run the integration either synchronously or asynchronously.

If set totrue, the integration runs asynchronously. And if set tofalse, the integration runs synchronously.

  • Asynchronous mode: When the request to run the integration reaches the endpoint, the endpoint immediately returns the integration execution IDs, but starts the execution of integration at the time specified by the<ScheduleTime> element. If you have not set the<ScheduleTime> element, the integration is scheduled to run immediately. Even though the integration is scheduled to run immediately, its execution may start after a few seconds. When the integration starts to execute, the following two things happen:
    • The integration returns the HTTP200 OK status code so that the caller can continue processing.
    • The IntegrationCallout policy completes.
    Once started, the integration will have a maximum time limit of 50 minutes to complete the execution.
  • Synchronous mode: When the request to run the integration reaches the endpoint, the endpoint immediately starts the execution of the integration and waits for the response. The maximum time limit to complete the execution is 2 minutes. After finishing the execution, the endpoint returns a response with the execution IDs and other response data.
Default Valuefalse
Required?Optional
TypeBoolean
Parent Element<IntegrationCallout>
Child Elements None

The<AsyncExecution> element uses the following syntax:

Syntax

<AsyncExecution>BOOLEAN</AsyncExecution>

Example

The following example sets asynchronous execution totrue:

<AsyncExecution>true</AsyncExecution>

<Request>

Specifies the flow variable having the request object created by the SetIntegrationRequest policy.The IntegrationCallout policy sends this request object to Application Integration for running the integration.

Default ValueN/A
Required?Required
TypeString
Parent Element<IntegrationCallout>
Child Elements None

The<Request> element uses the following syntax:

Syntax

<RequestclearPayload="true">FLOW_VARIABLE_NAME</Request>

Example

The following example specifies that the request object is available in themy_request_flow_var flow variable:

<RequestclearPayload="true">my_request_flow_var</Request>

The following table describes the attributes of<Request>:

AttributeRequired?TypeDescription
clearPayloadOptionalboolean

Specifies if the request object should be cleared from the memory after sending the request to run the integration.

  • If set totrue, Apigee clears the request object.
  • If set tofalse, Apigee doesn't clear the request object.

If you don't specify this attribute, the default value istrue and the request object is cleared from the memory.

<Response>

Specifies the flow variable for saving the integration's response.

If you don't specify this element, the policy saves the response in theintegration.response flow variable.

Default Valueintegration.response
Required?Optional
TypeString
Parent Element<IntegrationCallout>
Child Elements None

The output of the integration can be accessed byintegration.response.content orflow_variable.content. The<Response> element uses the following syntax:

Syntax

<Response>FLOW_VARIABLE_NAME</Response>

Example

The following example saves the response of the integration run in themy_response_flow_var flow variable:

<Response>my_response_flow_var</Response>

Error codes

This section describes the fault codes, error messages, and the fault variables set by Apigee when this policy triggers an error. This information is essential if you are developing fault rules to handle faults. To learn more, seeWhat you need to know about policy errors andHandling faults.

Runtime errors

These errors can occur when the policy executes.

Fault codeHTTP statusCause
entities.UnresolvedVariable500This error occurs if Apigee cannot resolve theintegration.project.id or theintegration.name variables.
steps.integrationcallout.ExecutionFailed500

This error can occur if the backend target service returns an HTTP error status such as4xx or5xx. The possible causes include:

  • The service account deployed with the proxy has the incorrect permissions to run the integration.
  • The integration or the API trigger does not exist.
  • Application Integration is not enabled for your Google Cloud project.
  • You have configured the<ScheduleTime> element in your SetIntegrationRequest policy and the IntegrationCallout policy has theAsyncExecution set tofalse.
steps.integrationcallout.NullRequestVariable500This error occurs if the flow variable specified in the<Request> is null.
steps.integrationcallout.RequestVariableNotMessageType500This error occurs when the flow variable specified by theRequest element is not ofmessage type.
steps.integrationcallout.RequestVariableNotRequestMessageType500This error occurs when the flow variable specified by theRequest element is not ofRequest message type.
messaging.adaptors.http.filter.GoogleTokenGenerationFailure500

This error can occur because of an incorrect service account configuration. The possible causes include:

  • The service account deployed with the proxy does not exist in your project.
  • The service account deployed with the proxy is disabled.

Fault variables

Whenever there are execution errors in a policy, Apigee generates error messages. You can view these error messages in the error response. Many a time, system generated error messages might not be relevant in the context of your product. You might want to customize the error messages based on the type of error to make the messages more meaningful.

To customize the error messages, you can use either fault rules or the RaiseFault policy. For information about differences between fault rules and the RaiseFault policy, seeFaultRules vs. the RaiseFault policy. You must check for conditions using theCondition element in both the fault rules and the RaiseFault policy. Apigee provides fault variables unique to each policy and the values of the fault variables are set when a policy triggers runtime errors. By using these variables, you can check for specific error conditions and take appropriate actions. For more information about checking error conditions, seeBuilding conditions.

The following table describes the fault variables specific to this policy.

VariablesWhereExample
fault.nameThefault.name can match to any of the faults listed in theRuntime errors table. The fault name is the last part of the fault code.fault.name Matches "UnresolvedVariable"
IntegrationCallout.POLICY_NAME.failedPOLICY_NAME is the user-specified name of the policy that threw the fault.IntegrationCallout.integration-callout-1.failed = true
For more information about policy errors, seeWhat you need to know about policy errors.

Related topics

If you want to learn more about Application Integration feature, seeApplication Integration overview

Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2025-12-17 UTC.