See the supported connectors for Application Integration.

Connectors task

The Connectors task lets you quickly and securely connect to the various Google Cloud services and other business applications from your integration using the out-of-the-box connectors available in Integration Connectors.

For the list of all the supported connectors for Application Integration, see Connector reference.

Before you begin

  • Make sure that you have the Connectors Admin (roles/connectors.admin) IAM role granted on your Google Cloud project. For information about granting roles, see Manage access.
  • Learn about the general concepts of Integration Connectors.
  • To connect to Google Cloud services and other business applications using a connector, ensure that you have attached a user-managed service account to your integration. If your integration does not have user-managed service account configured, then by default the default service account (service-PROJECT_NUMBER@gcp-sa-integrations.iam.gserviceaccount.com) is used for authentication.
  • Ensure that your service account has the required IAM role. For information about granting roles to a service account, see Manage access to service accounts.

Add a Connectors task

To add the Connectors task in your integration, do the following:

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

    Go to Application Integration

  2. In the navigation menu, click Integrations.

    The Integrations page appears listing all the integrations available in the Google Cloud project.

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

    If you are creating a new integration:

    1. Enter a name and description in the Create Integration pane.
    2. Select a region for the integration.
    3. Select a service account for the integration. You can change or update the service account details of an integration any time from the Integration summary pane in the integration toolbar.
    4. Click Create.

    This opens the integration in the integration editor.

  4. In the integration editor navigation bar, click Tasks to view the list of available tasks and connectors.

    5. image showing connectors task

  5. If you want to configure a new connection, click and place the Connectors element in the integration editor. Then, click Configure connector to configure the connection.

    image showing connector task listing image showing connector task listing

  6. If you have an existing connection, then click the Connectors tab to view the recently created connections. You can also search for a connector, connection, or task by entering the name in the Search field.

    image showing search capability for connectors task

  7. Click and place the configured Connectors element in the integration editor. For information about how to configure a connector task, see Configure the Connectors task.

Configure the Connectors task

To configure a Connectors task, do the following:

  1. Click the Connectors task element on the designer to view the Connectors task configuration pane.

    Optionally, click to rename the task name.

  2. Click Configure connector.
  3. You can either select an existing connection in the region or create an new connection. To configure an existing connection, complete the following steps in the Connectors Task Editor page.

    The following image shows a sample layout of the Connectors Task Editor page. image showing Configure connector task dialog image showing Configure connector task dialog

    1. In the Select connection section, select the region of the connection.
    2. Choose an existing connection from the list of available connections in the selected region.
    3. Click Next.
    4. From the Type list, select Entities or Actions.
      • If you select Entities, the list of supported entities for the connection is displayed in the Set entities/actions section. Select an entity followed by the Operation that you'd want to perform on that entity.
      • If you select Actions, the list of supported actions for the connection is displayed in the Set entities/actions column. Select an action for the connection.
        • The supported entities and actions are based on the connector type. For the list of all the supported connectors for Application Integration, see Connector reference. To view the supported actions and entities for a connector, view the specific connector documentation.

        If the connector supports custom SQL query, you can select the Execute custom query option from the Actions list. For information about how to add custom SQL query for your connector, see Action: Execute custom SQL query.

    5. Click Done to complete the connection configuration and close the pane.

Configure task input and output variables

The Connectors task configuration pane displays Task Input and Task Output variables that are automatically generated based on the Entity and Operation or Action selected in the Configure connector task dialog. These variables are configurable and are accessible as inputs to the current task or as outputs to subsequent tasks, or conditionals in the current integration.

To configure the Task Input or Task Output variables, click the respective variable to open the Configure Variable pane and perform the following steps:

  1. Enter the variable value in the Default Value field.
  2. (Optional) Select Use as an input to integration or Use as an output to integration.
  3. Click Save.

For more information about the input and output parameters of the Connectors task, see Entity operations.

Configure authentication override

To enable the connection to accept different backend authentication dynamically during runtime, ensure that in Integration Connectors, you have selected the Enable Authentication Override option for your connection.

To configure the authentication override, do the following:

  1. Click the connectors task element on the designer to view the Connectors task configuration pane.
  2. Expand the Task input section. The End user credentials field is set to a dynamicAuthConfig variable.

    End user credentials End user credentials

    Then, do the following:

    1. Click the dynamicAuthConfig variable. The Edit variable pane appears.

      For overriding the authentication, you must provide the authentication values when you test the integration.

      Edit dynamic euc variable Edit dynamic euc variable

      To do so, follow these steps:

      1. From the Variable type list, select Input to Integration.
      2. In the JSON schema options, you can verify the authentication type configured for the connection. Use this schema to override the authentication value when you test the integration.

        Test integration for auth override Test integration for auth override

    Alternatively, you can pass the authentication as the HTTP header by selecting the Use HTTPS Header for Auth Config checkbox in the Task input section of the Connectors task configuration pane.

    Test integration by passing the authentication as the HTTP header Test integration by passing authentication as the HTTP header

Entity operations and actions

You can perform CRUD (Create, Read, Update, Delete) operations on the entities of a connector. Each of these entity operations has a different set of input and output parameters. The following table lists the input and output parameters of the various entity operations.

Operation name Input parameters Output parameters
List
  • listEntitiesPageSize
  • listEntitiesPageToken
  • listEntitiesSortByColumns
  • filterClause
  • connectorOutputPayload
  • listEntitiesNextPageToken
Get entityId connectorOutputPayload
Create connectorInputPayload connectorOutputPayload
Update
  • connectorInputPayload
  • entityId
  • filterClause
 connectorOutputPayload
Delete
  • entityId
  • filterClause
 N/A

Input parameters

The following table describes the input parameters for the various entity operations.

Parameter name Data type Description
entityId String

A unique identifier of the row that you want to access.

Normally, the entityId is a primary key value of a table or a dataset. If you specify a value for the entityId and the table or dataset doesn't have a primary key column, integration reports a runtime error and the Connectors task fails.

For example, to get a specific row from a MySQL table, the entityId is the primary key value in the table.
connectorInputPayload JSON The actual data to be added or updated in an entity. The following example shows the JSON snippet of a row data to be added in a table: 
{
"employee_first_name": "John",
"employee_emailID": "test-05@test.com"
}

In this example, employee_first_name and employee_emailID are the column names with the corresponding values John and test-05@test.com.
filterClause String Restricts the result of the operations based on a condition. For more information about adding a filter clause, see Add a filter for an operation.
listEntitiesPageSize Integer

Specifies the number of results that should be returned in a page.

A page is a logical grouping of the records in a result set. The concept of a page is useful when you are expecting a large number of records in the result set. If the result set is large, the Connectors task might fail, as there is a limit on the data size that the Connectors task can process. By breaking down the result set into smaller chunks, you can avoid this issue.

For example, if you are expecting 1000 records in your result set, you can set the listEntitiesPageSize to 100. So when the Connectors task runs for the first time, it returns the first 100 records, the next 100 records in the second run and so on.

listEntitiesPageToken String

A page identifier (token) that lets you access a specific page.

You can get the value of a page token from the listEntitiesNextPageToken output parameter. Because each page has a unique token, you have the flexibility to access any page you want in the result set. To understand the usage of this parameter, also read the description of the listEntitiesNextPageToken output parameter.
listEntitiesSortByColumns String array Column name by which you want to sort the result set.

Output parameters

The following table describes the output parameters for the various entity operations.

Parameter name Data type Description
connectorOutputPayload JSON The output of an operation in JSON format.
listEntitiesNextPageToken String

A system generated identifier for a page. You can think of the token as a pointer by which you can access a particular page of the result set.

If you have broken down your result set into multiple pages by setting the listEntitiesPageSize parameter, you need a mechanism to navigate through the pages. The listEntitiesNextPageToken output parameter lets you do exactly that. Every time the Connectors task runs, the system generates a token for the next page and sets the listEntitiesNextPageToken's value to the newly generated token. You can then use this token to access the next page in the result set. To access the next page, you must set the listEntitiesPageToken input parameter to the next page's token value.

For example, consider you have set the listEntitiesPageSize parameter to 2 and when then Connectors task runs for the first time, the listEntitiesNextPageToken is set to the ChoKC2VtcGxveWVlX2lkEgkRAAAAAAAA8D8YDw== token value. You can then set the listEntitiesPageToken input parameter to this token value to fetch the next page in the subsequent run of the Connectors task.

If your result set has a large number of pages, you can consider using the While Loop task to get the next page and use the Data Mapping task to automatically assign page token values to the listEntitiesPageToken input parameter after each run. Map listEntitiesNextPageToken from the last loop iteration to listEntitiesPageToken in the LIST Operation of the current loop iteration's Connectors task. The While Loop task ends when listEntitiesNextPageToken is NULL, implying that there are no more pages.

Filter clause for entity operations

You can restrict the records that are processed by the Connectors task using the Filter clause variable that is available as a Task Input. For example, in case of a delete operation, you can add a filter clause to delete records with a specific orderId.

Filter clause can be applied only for the following entity operations:

  • List
  • Delete
  • Update

When you select any of these operations, the Task Input section of the Connectors task displays the Filter clause field automatically.

Add a filter clause

To add a filter clause, perform the following steps:

  1. Click the Connectors task element on the designer to view the Connectors task configuration pane.
  2. Expand the Task Input section and click the filterClause(Connectors) string variable.

    The Configure Variable dialog appears.

  3. Enter the filter clause (following the clause syntax) in the Default Value field.
  4. Click Save.

Filter clause syntax and examples

A filter clause has the following format:

FIELD_NAME CONDITION FILTER_VALUE

Examples

  • OwnerId = '0053t000007941XAAQ'
     
  • PoNumber < 2345
     
  • OrderNumber = 00110 AND StatusCode = 'Draft'
     
  • TotalAmount > 2500
     
  • ShippingPostalCode = 94043 OR ShippingPostalCode = 77002

Use of variables in filter clause

You can't directly use an integration variable in a filter clause. If you want to use an integration variable, you must first configure a Data Mapping task to create a mapping between the integration variable and the filter clause.

The following table shows a sample mapping between an integration variable and the filterClause(Connectors) variable:

Input Output
PRIMARY_KEY_ID = ' .CONCAT(INTEGRATION_VARIABLE) .CONCAT(') filterClause(Connectors)
Where, PRIMARY_KEY_ID = ' is entered as a Value in the input row.

Action: Execute custom SQL query

To create a custom query, follow these steps:

  1. Follow the detailed instructions to add a connectors task.
  2. When you configure the connector task, in the type of action you want to perform, select Actions.
  3. In the Action list, select Execute custom query, and then click Done.

    image showing execute-custom-query-action image showing execute-custom-query-action

  4. Expand the Task input section, and then do the following:
    1. In the Timeout after field, enter the number of seconds to wait till the query executes.

      Default value: 180 seconds.

    2. In the Maximum number of rows field, enter the maximum number of rows to be returned from the database.

      Default value: 25.

    3. To update the custom query, click Edit Custom Script. The Script editor dialog opens.

      image showing custom-sql-query image showing custom-sql-query

    4. In the Script editor dialog, enter the SQL query and click Save.

      You can use a question mark (?) in a SQL statement to represent a single parameter that must be specified in the query parameters list. For example, the following SQL query selects all rows from the Employees table that matches the values specified for the LastName column: 

      SELECT * FROM Employees where LastName=?

    5. If you've used question marks in your SQL query, you must add the parameter by clicking + Add Parameter Name for each question mark. While executing the integration, these parameters replace the question marks (?) in the SQL query sequentially. For example, if you have added three question marks (?), then you must add three parameters in order of sequence.

      image showing add-query-param image showing add-query-param

      To add query parameters, do the following:

      1. From the Type list, select the data type of the parameter.
      2. In the Value field, enter the value of the parameter.
      3. To add multiple parameters, click + Add Query Parameter.

Schema refresh

All entities and actions will have a schema associated with them. For example, an action schema will have the parameter details such as; the parameter names, and its corresponding data type. The schema (metadata) for entities and actions is fetched by the connection at runtime from your backend. If there are any updates to the schema, such updates won't be automatically reflected in your existing connections; you must manually refresh the schema. To view the updated schema in your existing connector tasks, follow these steps:
  1. In Integration Connectors, open the Connection details page of the connection, and then click Refresh connection schema.
  2. In Application Integration, you must reconfigure your existing connector task for the same connection.

Inline connection creation

You can use the Connectors task to directly create a new connection in Integration Connectors.

Before you begin

Create new connection

To create a new connection from Application Integration, perform the following steps:

  1. Click the Connectors task element on the designer to view the Connectors task configuration pane.
  2. Click Configure connector.

    The Connectors Task Editor page appears.

  3. Skip the Region field.
  4. Click Connection and select the Create Connection option from the drop-down menu.
  5. Complete the following steps in the Create Connection pane:
    1. In the Location step, choose the location for the connection.
      1. Click Region and select a location from the drop-down list.
      2. Click Next.
    2. In the Connection Details step, provide details about the connection:
      1. Connector: Select the type of connector that you want to create from the drop down list. For information about the list of supported connectors, see All Integration Connectors.
      2. Connector version: Choose an available version of the selected Connector type from the drop down list.
      3. Connection Name: Enter a name for the Connection instance.
      4. (Optional) Enter a Description for the connection instance.
      5. (Optional) Check Enable Cloud Logging to store the log data of the connection instance.
      6. Service Account: Select a service account that has the required roles.
      7. (Optional) Click Advanced settings to configure the connection node settings.

        For more information, see the respective connection documentation in Integration Connectors.

      8. (Optional) Click + ADD LABEL to add a label to the connection in the form of a key/value pair.
      9. Click Next.
    3. In the Authentication step, provide the authentication details for the connection.
      1. The Authentication methods populated during this step are based on the type of connection being created.

        Different connection types use different authentication methods. For more information, see the Configure authentication section of the respective connection documentation in Integration Connectors.

      2. Click Next.
    4. Review: Review your connection and authentication details.
    5. Click Create.

Best practices

Error handling strategy

An error handling strategy for a task specifies the action to take if the task fails due to a temporary error. For information about how to use an error handling strategy, and to know about the different types of error handling strategies, see Error handling strategies.

Pricing

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

Quotas and limits

For information about quotas and limits, see Quotas and limits.

What's next