Cloud Pub/Sub trigger

TheCloud Pub/Sub trigger lets you run your integration based on the events inyourPub/Sub middleware.

Using this trigger, you can execute an integration whenever a publisher writes a message to your chosen topic. The topic can exist in the same Google Cloud project as the integration, or in a different Google Cloud project. When this trigger executes, it also writes the published message to theCloudPubSubMessage output variable. Based on your requirements, you can use this variable in your downstream triggers or tasks.

To learn how to create a sample integration using Application Integration and the Cloud Pub/Sub trigger trigger, seeListen to Cloud Pub/Sub topic and send an email.

Using this trigger, you can execute an integration whenever a publisher writes a message to your chosen topic. When this trigger executes, it also writes the published message to theCloudPubSubMessage output variable. Based on your requirements, you can use this variable in your downstream triggers or tasks.

Note: The topic that you configure for the trigger must be available in the same Google Cloud project as your integration. Application Integration does not supportCloud Pub/Sub trigger executions across different Google Cloud projects.

Before you begin

Ensure that you perform the following tasks in your Google Cloud project before configuring theCloud Pub/Sub trigger.

• Assign theProject IAM Admin (roles/resourcemanager.projectIamAdmin) to the user creating this trigger.
• Enable thePub/Sub API for the Google Cloud project that has your integration.

If the Pub/Sub API is protected by a service perimeter, ensure that you define the followingIAM roles to manage these service perimeters:

• Access Context Manager Admin (roles/accesscontextmanager.policyAdmin)
• Access Context Manager Editor (roles/accesscontextmanager.policyEditor)
• Access Context Manager Reader (roles/accesscontextmanager.policyReader)
• Confirm that you have a Pub/Sub topic. To create a new Pub/Sub topic:
  1. Go to the Pub/Sub topics page in theCloud console.

     Go to the Pub/Sub topics page

  2. ClickCreate a topic.
  3. In theTopic ID field, provide a unique topic name.
  4. ClickSave.
  Note: You don't have to create a subscription for the trigger to work. Application Integration automatically creates a subscription for a topic when you publish your integration, and you can view all your subscriptions in thePub/Sub subscription page.

  Starting with the Application IntegrationDecember 01 2023 release, you will be billed for your subscriptions as per thePub/Sub billing rates. Subscriptions for your existing Cloud Pub/Sub trigger will continue to work as before, and they aren't billed. However, if you update the topic of an existing Cloud Pub/Sub trigger, Pub/Sub billing will be applied to the updated Cloud Pub/Sub trigger.

For more information about managing access using IAM roles, seeAccess control.

For information on granting roles to principals, seeGranting, changing, and revoking access.

Add a Cloud Pub/Sub trigger

To add aCloud Pub/Sub trigger to a new or existing integration, follow the steps below:

1. In the Google Cloud console, go to theApplication Integration page.

   Go to Application Integration

2. In the navigation menu, clickIntegrations

   TheIntegrations List page appears listing all the integrations available in the Google Cloud project.

3. Select an existing integration or clickCreate integration to create a new one.

   If you are creating a new integration:

   1. Enter a name and description in theCreate Integration pane.
   2. Select a region for the integration.Note: TheRegions dropdown only lists the regions provisioned in your Google Cloud project. To provision a new region, ClickEnable Region. SeeEnable new region for more information.
   3. Select a service account for the integration. You can change or update the service account details of an integration any time from theinfoIntegration summary pane in the integration toolbar.Note: The option to select a service account is displayed only if you have enabled integration governance for the selected region.
   4. ClickCreate.

   The newly created integration opens in theintegration editor.

4. In theintegration editor navigation bar, clickTriggers to view the list of available triggers.
5. Click and place theCloud Pub/Sub trigger element to the designer.

Configure a Cloud Pub/Sub trigger

Click theCloud Pub/Sub trigger element in the integration editor to view the trigger configuration pane, and then do the following tasks:

1. Specify the topic the trigger should listen to in thePub/Sub topic field in the following format:

   projects/PROJECT_ID/topics/TOPIC_ID

   To view all the available topics in your Google Cloud project, see theTopic name column inTopics. You can also select a topic from a different Google Cloud project.

   Replace the following:
   • PROJECT_ID: the Google Cloud project where your topic is created.
   • TOPIC_ID: the ID of your Pub/Sub topic. The topic can be in the same Google Cloud project as that of your integration, or can be present in a different Google Cloud project.
2. Select the service account which you want to use to invoke the integration. You can also choose aconfig variable that you have created in the integration. The value of the config variable must be a service account email address with the following format:SERVICE_ACCOUNT_NAME@project-id.iam.gserviceaccount.com. For example,application-integration-invoke@project123.iam.gserviceaccount.com.

   For information about how to create a config variable, seecreate a variable, and about how to create a service account, seeCreating a service account.

   If you choose a config variable, you must grant the required roles to the service account that the config variable refers to. For more information about how to grant roles, seeRequired IAM roles.

   If there are no service accounts, create a service account by clickingCreate new in theService account list.

   Note:Starting with the Application IntegrationDecember 01 2023 release, when you configure the Cloud Pub/Sub trigger, you must specify a service account for the trigger. Your existing Pub/Sub triggers, that don't have any service account associated with them, will continue to work as before. However, if you want to modify any of the existing Pub/Sub triggers, you must configure a service account to continue using those triggers.

By default, theexpiration period option for subscriptions is set tonever expire. If you want to set the expiration to another value, in the Google Cloud console, go to thePub/Sub subscription page and edit the subscription.

IAM roles required for service accounts

ClickingGrant when selecting a service account, automatically provides the following roles to the various service accounts.

Service account	IAM role granted
Application Integration's default service account:service-PROJECT_NUMBER@gcp-sa-integrations.iam.gserviceaccount.com	Pub/Sub Editor (roles/pubsub.editor) Service Account User (roles/iam.serviceAccountUser) If the Pub/Sub topic's Google Cloud project is different from the integration's Google Cloud project, the default service account needs Pub/Sub Editor role in the topic's Google Cloud project.
Service account that you select for this trigger	Application Integration Invoker (roles/integrations.integrationInvoker)

Trigger Output

For each event, theCloud Pub/Sub trigger generates aCloudPubSubMessage output variable which you can use in your downstream tasks. The variable is in JSON format and has thePubsubMessage structure.

Create subscription with filter for your integration

If you want to set a filter for the Pub/Sub subscription to process specific events in your integration, follow these steps:

1. Publish the integration with the Cloud Pub/Sub trigger configured. This step creates the subscription in the integration project.
2. In the Google Cloud console, go to theSubscriptions page.

   Go to Subscriptions

3. Open the subscription and copy all the details including the subscription name.
4. Delete the existing subscription.
5. Create a new subscription with all the details of the deleted subscription–including the subscription name–that you copied in step 3 and alsoadd a filter in the new subscription.

   The newly created subscription triggers the integration with filtered messages.

SLA exclusions

The Cloud Pub/Sub trigger is dependent on thePub/Sub product. As this dependency is external to the Application Integration, theApplication Integration Service Level Agreement (SLA) terms and conditions are applicable only when the Cloud Pub/Sub trigger successfully starts the execution of anactive integration.

Use Pub/Sub triggers with VPC Service Controls

When you configure a Pub/Sub trigger in Application Integration and attempt to publish the integration, the creation of the required Pub/Sub subscription fails if the Pub/Sub API is protected by aservice perimeter in VPC Service Controls.

Service perimeters enforce security boundaries around your Google Cloud resources, and these policies can prevent Application Integration from creating the necessary Pub/Sub subscription during integration publishing.

To successfully configure and publish a Pub/Sub trigger in these scenarios, perform the following steps:

1. Temporarily remove the Pub/Sub API from the service perimeter:
   1. In the Google Cloud console, go to theVPC Service Controls page.

      Go to VPC Service Controls

   2. Select the Google Cloud project that contains the Pub/Sub topic to be used in the integration.
   3. (Optional) If no access policy is configured for the selected project, the messageNo VPC Service Perimeters found in current scope will appear. In this case, clickSwitch to organization scope to navigate to the organization level.
   4. On theVPC Service Controls page, in the table, click the name of the service perimeter that you want to modify.
   5. On theService perimeter details page, clickEdit.
   6. In theRestricted services pane, filter and select thepubsub.googleapis.com service.
   7. ClickdeleteRemove Selected.
   8. ClickSave. In the confirmation dialog, clickConfirm to remove the Pub/Sub API from your VPC Service Controls service perimeter.
2. Add and configure the Pub/Sub trigger in your integration.
3. Publish the integration.
4. Add the Pub/Sub API back to the service perimeter:
   1. Go to theVPC Service Controls page.

      Go to VPC Service Controls

   2. On theVPC Service Controls page, in the table, click the same service perimeter that you modified earlier.
   3. On theService perimeter details page, clickEdit.
   4. In theRestricted services pane, clickaddAdd services.
   5. Filter and select thepubsub.googleapis.com service.
   6. ClickAdd selected services.
   7. ClickSave. In the confirmation dialog, clickConfirm to add the Pub/Sub API back to your VPC Service Controls service perimeter.

Pricing

The Cloud Pub/Sub trigger and Salesforce trigger don't require you to create aconnector. However, if you use theConnectors task to connect to Pub/Sub or Salesforce, then you are billed for the connector usage. For information about pricing, seeApplication Integration pricing.

Considerations

• The maximum size of a Pub/Sub message is 10 MB. To understand all the limitations of Pub/Sub, seePub/Sub quotas and limits.
• It is possible that Pub/Sub writes the same message more than once to a topic. To understand this behavior of Pub/Sub, seeAt-Least-Once delivery. Therefore, you must design your integration to be idempotent so that it doesn't allow a message to be written more than once to a topic.

  Themessage_id field in the message header uniquely identifies a Pub/Sub message.

• Application Integration now lets you publish messages to Pub/Sub topics. You can use ordering keys to achieve First-In, First-Out (FIFO) message processing. When you set an ordering key in thePublish Pub/Sub Message task, messages are received in the correct order. This improves reliability for integrations that need ordered message processing. To learn more about how to use ordering keys when you publish messages, seeUsing ordering keys.
• If you unpublish an integration, the Pub/Sub subscription is not deleted to prevent loss of messages. However, if you delete the published version or all the integration versions of an integration, then the Pub/Sub subscription is also deleted.

Quotas and limits

For information about quotas and limits, seeQuotas and limits.

What's next

• Learn aboutall tasks and triggers.
• Learn how totest and publish an integration.
• Learn abouterror handling.
• Learn aboutintegration execution logs.