SetIntegrationRequest policy

You're viewing Apigee X documentation.
View Apigee Edge documentation.

policy icon

Overview

The SetIntegrationRequest policy lets you create a request object for an integration that you want to run. In the policy, you must configure the details of the API trigger and the input parameters required to run the integration. When you run the SetIntegrationRequest policy, it creates a request object and saves it in a flow variable. The request object has all the information required to run the integration. At this stage, the integration is still not run. To run the integration, you must either call the IntegrationCallout policy or set an IntegrationEndpoint. Both the IntegrationCallout policy and IntegrationEndpoint require the request object to run the integration.

<SetIntegrationRequest>

Specifies the SetIntegrationRequest policy.

Default Value N/A
Required? Required
Type Complex type
Parent Element N/A
Child Elements <ApiTrigger>
<DisplayName>
<IntegrationName>
<Parameters>
<ProjectId>
<Request>
<ScheduleTime>

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

Child Element Required? Description
<ApiTrigger> Required Name of the API trigger to call in the integration.
<DisplayName> Optional A custom name for the policy.
<IntegrationName> Optional Name of the integration to run.
<Parameters> Optional Input parameters of the integration.
<ProjectId> Optional Name of the Google Cloud Project which has the integration that you want to run.
<Request> Optional Name of the flow variable to save the request object.
<ScheduleTime> Optional The time at which the integration must be run.

The SetIntegrationRequest policy uses the following syntax:

Syntax

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<SetIntegrationRequest continueOnError="[true|false]" enabled="[true|false]" name="Set-Integration-Request">
  <DisplayName>POLICY_DISPLAY_NAME</DisplayName>
  <ProjectId ref="PROJECT_ID_FLOW_VARIABLE_NAME">GOOGLE_CLOUD_PROJECT_ID</ProjectId>
  <IntegrationName ref="INTEGRATION_FLOW_VARIABLE_NAME">INTEGRATION_NAME</IntegrationName>
  <!-- Example: api_trigger/my_test1_API_1 -->
  <ApiTrigger ref="API_TRIGGER_FLOW_VARIABLE_NAME">API_TRIGGER_NAME</ApiTrigger>
  <ScheduleTime>VALUE</ScheduleTime>
  <Parameters>
    <Parameter name="PARAMETER_NAME" type="PARAMETER_TYPE">PARAMETER_VALUE</Parameter>
    <ParameterArray name="ARRAY_NAME" type="ARRAY_TYPE">
      <Value>PARAMETER_VALUE_1</Value>
      <Value>PARAMETER_VALUE_2</Value>
      <Value>PARAMETER_VALUE_3</Value>
    </ParameterArray>
  </Parameters>
  <Request>REQUEST_FLOW_VARIABLE_NAME</Request>
</SetIntegrationRequest>

Example

The following example shows the SetIntegrationRequest policy definition:

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<SetIntegrationRequest continueOnError="false" enabled="true" name="Set-Integration-Request">
  <DisplayName>Set Integration Request Policy</DisplayName>
  <ProjectId ref="my_projectid_var">apigee_staging_1</ProjectId>
  <IntegrationName ref="my_integration_ref">integration_1</IntegrationName>
  <ApiTrigger ref="my_api_trigger_ref">API-Trigger-2</ApiTrigger>
  <ScheduleTime>2022-01-15T01:30:15Z</ScheduleTime>
  <Parameters>
    <Parameter name="my_str_param" type="string">someText</Parameter>
    <ParameterArray name="my_array_param" type="integer">
      <Value>1</Value>
      <Value>2</Value>
      <Value>3</Value>
    </ParameterArray>
  </Parameters>
  <Request>my_request_var</Request>
</SetIntegrationRequest>

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

Attribute Default Required? Description
name N/A Required

The internal name of the policy. The value of the name 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.

continueOnError false Optional Set to false to return an error when a policy fails. This is expected behavior for most policies. Set to true to have flow execution continue even after a policy fails.
enabled true Optional Set to true to enforce the policy. Set to false to turn off the policy. The policy will not be enforced even if it remains attached to a flow.
async   false Deprecated This attribute is deprecated.

Child element reference

This section describes the child elements of <SetIntegrationRequest>.

<DisplayName>

Use in addition to the name 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 Value N/A
Required? Optional. If you omit <DisplayName>, the value of the policy's name attribute is used.
Type String
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.

<ProjectId>

Specifies the name of the Google Cloud Project.

Apigee assigns the value you specify for this element to the integration.project.id flow variable.

Default Value N/A
Required? Optional
Type String
Parent Element <SetIntegrationRequest>
Child Elements None

The <ProjectId> element uses the following syntax:

Syntax

<ProjectId ref="PROJECT_ID_FLOW_VARIABLE_NAME">GOOGLE_CLOUD_PROJECT_ID</ProjectId>

Example

The following example configures the policy to use the my_projectid_var flow variable to fetch the project ID, and if the flow variable fails to resolve at runtime, use apigee_staging_1 as the project ID:

<ProjectId ref="my_projectid_var">apigee_staging_1</ProjectId>

The following table describes the attributes of <ProjectId>:

Attribute Required? Type Description
ref Optional String Specifies the flow variable from which Apigee should read the Google Cloud Project ID. You can set the <ProjectId> element in one of the following ways:
  • <ProjectId>val</ProjectId>: Use val as the project ID.
  • <ProjectId ref="refval"/>: Resolve refval dynamically to determine the project ID. Apigee reports an exception if the resolved project ID is invalid or if refval is unresolved.
  • <ProjectId ref="refval">val</ProjectId>: Resolve refval dynamically to determine the project ID. Apigee reports an exception if the resolved project ID is invalid. If refval does not resolve, use val as the project ID.

<IntegrationName>

Specifies the integration to run.

Apigee assigns the value you specify for this element to the integration.name flow variable.

The integration name must meet the following naming requirements:

  • Must start and end with letters or numbers.
  • Cannot have spaces.
  • Cannot have two consecutive dash or underscore characters.
Default Value N/A
Required? Optional
Type String
Parent Element <SetIntegrationRequest>
Child Elements None

The <IntegrationName> element uses the following syntax:

Syntax

<IntegrationName ref="INTEGRATION_FLOW_VARIABLE_NAME">INTEGRATION_NAME</IntegrationName>

Example

The following example configures the policy to use the my_integration_ref flow variable to fetch the integration name, and if the flow variable fails to resolve at runtime, use integration_1 as the integration name:

<IntegrationName ref="my_integration_ref">integration_1</IntegrationName>

The following table describes the attributes of <IntegrationName>:

Attribute Required? Type Description
ref Optional String Specifies the flow variable from which Apigee should read the integration name. You can set the <IntegrationName> element in one of the following ways:
  • <IntegrationName>val</IntegrationName>: Use val as the integration name.
  • <IntegrationName ref="refval"/>: Resolve refval dynamically to determine the integration name. Apigee reports an exception if the resolved integration name is invalid or if refval is unresolved.
  • <IntegrationName ref="refval">val</IntegrationName>: Resolve refval dynamically to determine the integration name. Apigee reports an exception if the resolved integration name is invalid. If refval does not resolve, use val as the integration name.

<ApiTrigger>

Specifies the API trigger to run.

You must specify the API trigger name in the api_trigger/API_TRIGGER_NAME format.

Apigee assigns the value you specify for this element to the integration.api.trigger flow variable.

If you have specified the <IntegrationName>, only the API trigger of that integration is run. However, if you have not specified the <IntegrationName>, all the integrations that have the specified API trigger are run.

Default Value N/A
Required? Required
Type String
Parent Element <SetIntegrationRequest>
Child Elements None

The <ApiTrigger> element uses the following syntax:

Syntax

<ApiTrigger ref="FLOW_VARIABLE_NAME">API_TRIGGER_NAME</ApiTrigger>

Example

The following example configures the policy to use the my_api_trigger_ref flow variable to fetch the API trigger name, and if the flow variable fails to resolve at runtime, use api_trigger/API-Trigger-2 as the API trigger name:

<ApiTrigger ref="my_api_trigger_ref">api_trigger/API-Trigger-2</ApiTrigger>

The following table describes the attributes of <ApiTrigger>:

Attribute Required? Type Description
ref Optional String Specifies the flow variable from which Apigee should read the API trigger name. You can set the <ApiTrigger> element in one of the following ways:
  • <ApiTrigger>val</ApiTrigger>: Use val as the API trigger name.
  • <ApiTrigger ref="refval"/>: Resolve refval dynamically to determine the trigger name. Apigee reports an exception if the resolved API trigger name is invalid or if refval is unresolved.
  • <ApiTrigger ref="refval">val</ApiTrigger>: Resolve refval dynamically to determine the trigger name. Apigee reports an exception if the resolved API trigger name is invalid. If refval does not resolve, use val as the trigger name.

<ScheduleTime>

Specifies the time at which the integration must run.

If the time is less or equal to the current time, the integration runs immediately. You must specify the time in the yyyy-mm-ddThh:mm:ssZ format where Z is the UTC timezone. For example, if you specify 2022-01-15T01:30:15Z, the integration is scheduled to run on 1-15-2022 at 1:30:15 UTC. You can also specify the timezone using an offset from UTC. For example, if you specify 2022-01-15T01:30:15-08:00, the integration is scheduled to run on 1-15-2022 at 1:30:15 PST. For more information about the time format, see Combined date and time representations.

Default Value N/A
Required? Optional
Type String
Parent Element <SetIntegrationRequest>
Child Elements None

The <ScheduleTime> element uses the following syntax:

Syntax

<ScheduleTime>VALUE</ScheduleTime>

Example

The following example schedules the integration to run at 2022-01-15T01:30:15Z:

<ScheduleTime>2022-01-15T01:30:15Z</ScheduleTime>

<Parameters>

Specifies the input parameters required to run the integration.

You can specify separate individual parameters or a parameter array. To specify individual parameters, use the <Parameter> element. To specify a parameter array, use the <ParameterArray> element.

Default Value N/A
Required? Optional
Type Complex type
Parent Element <SetIntegrationRequest>
Child Elements <Parameter>
<ParameterArray>

The <Parameters> element uses the following syntax:

Syntax

<Parameters>
  <Parameter name="PARAMETER_NAME" type="PARAMETER_TYPE">PARAMETER_VALUE</Parameter>
  <ParameterArray name="ARRAY_NAME" type="ARRAY_TYPE">
    <Value>PARAMETER_VALUE_1</Value>
    <Value>PARAMETER_VALUE_2</Value>
    <Value>PARAMETER_VALUE_3</Value>
  </ParameterArray>
</Parameters>

Example

The following example initializes the my_str_param parameter and the my_array_param parameter array:

<Parameters>
  <Parameter name="my_str_param" type="string">someText</Parameter>
  <ParameterArray name="my_array_param" type="integer">
    <Value>1</Value>
    <Value>2</Value>
    <Value>3</Value>
  </ParameterArray>
</Parameters>

<Parameter>

Specifies an individual input parameter.

You can specify multiple <Parameter> elements within the <Parameters> element.

Default Value N/A
Required? Optional
Type String
Parent Element <Parameters>
Child Elements None

The <Parameter> element uses the following syntax:

Syntax
<Parameter name="PARAMETER_NAME" type="PARAMETER_TYPE">PARAMETER_VALUE</Parameter>
Example

The following example declares the my_str_param parameter as a string and sets the value to someText.

<Parameter name="my_str_param" type="string">someText</Parameter>

The following table describes the attributes of <Parameter>:

Attribute Required? Type Description
name Required String Name of the parameter.
type Required String Data type of the parameter. The supported types are integer, string, boolean, double, and json.

<ParameterArray>

Specifies an input parameter array.

You can specify multiple <ParameterArray> elements within the <Parameters> element.

Default Value N/A
Required? Optional
Type Complex type
Parent Element <Parameters>
Child Elements <Value>

The <ParameterArray> element uses the following syntax:

Syntax
<ParameterArray name="ARRAY_NAME" type="ARRAY_TYPE">
  <Value>PARAMETER_VALUE_1</Value>
  <Value>PARAMETER_VALUE_2</Value>
  <Value>PARAMETER_VALUE_3</Value>
</ParameterArray>
Example

The following example declares the my_array_param parameter array as an array of integers and sets the value of the array elements:

<ParameterArray name="my_array_param" type="integer">
  <Value>1</Value>
  <Value>2</Value>
  <Value>3</Value>
</ParameterArray>

The following table describes the attributes of <ParameterArray>:

Attribute Required? Type Description
name Required String Name of the parameter array.
type Required String Data type of the parameter array. The supported types are integer, string, boolean, and double.
<Value>

Specifies the value of an array element in a parameter array.

You must specify each element of the array in an separate <Value> element.

Default Value N/A
Required? Optional
Type String
Parent Element <ParameterArray>
Child Elements None

The <Value> element uses the following syntax:

Syntax
<ParameterArray name="ARRAY_NAME" type="ARRAY_TYPE">
  <Value>PARAMETER_VALUE_1</Value>
  <Value>PARAMETER_VALUE_2</Value>
  <Value>PARAMETER_VALUE_3</Value>
</ParameterArray>
Example

The following example declares the my_array_param parameter array with values 1, 2, and 3:

<ParameterArray name="my_array_param" type="integer">
  <Value>1</Value>
  <Value>2</Value>
  <Value>3</Value>
</ParameterArray>

<Request>

Specifies the flow variable name for saving the request.

After the policy executes, it creates a new request message object, and saves the object in the FLOW_VARIABLE_NAME variable which you can query to read the request.

If you do not specify a flow variable name, the policy saves the request in the request message, overriding the existing request message if any.

Default Value request
Required? Optional
Type String
Parent Element <SetIntegrationRequest>
Child Elements None

The <Request> element uses the following syntax:

Syntax

<Request>FLOW_VARIABLE_NAME</Request>

Example

The following example saves the request object in the my_request_var flow variable:

<Request>my_request_var</Request>

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, see What you need to know about policy errors and Handling faults.

Runtime errors

These errors can occur when the policy executes.

Fault code HTTP status Cause
steps.setintegrationrequest.InvalidResolvedFlowVariable 500

This error occurs because Apigee cannot resolve the flow variable specified in the ref attribute of the ProjectId, IntegrationName, or ApiTrigger elements. The flow variables fail to resolve if they have an invalid value, such as a null, an empty string, or an invalid value for the type.

A valid values for each element type is as follows:

  • ProjectId: See the naming requirements for Project ID in the Before you begin section.
  • InegrationName: See the naming requirements for the IntegrationName element.
  • ApiTrigger: The name should start with api_trigger/.
steps.setintegrationrequest.RequestVariableNotMessageType 500 This error occurs when the flow variable specified by the Request element is not of message type.
steps.setintegrationrequest.RequestVariableNotRequestMessageType 500 This error occurs when the flow variable specified by the Request element is not of Request message type.

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, see FaultRules vs. the RaiseFault policy. You must check for conditions using the Condition 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, see Building conditions.

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

Variables Where Example
fault.name The fault.name can match to any of the faults listed in the Runtime errors table. The fault name is the last part of the fault code. fault.name Matches "UnresolvedVariable"
SetIntegrationRequest.POLICY_NAME.failed POLICY_NAME is the user-specified name of the policy that threw the fault. SetIntegrationRequest.set-integration-request-1.failed = true
For more information about policy errors, see What you need to know about policy errors.

Related topics

If you want to learn more about Apigee's Integration feature, see What is Apigee Integration?