Connectors task

TheConnectors 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 inIntegration Connectors.

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, seeManage access.
• Learn about the general concepts ofIntegration Connectors.
• To connect to Google Cloud services and other business applications using a connector, ensure that you haveattached a user-managed service account to your integration. If your integration does not have user-managed service account configured, then by default thedefault 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, seeManage access to service accounts.

Add a Connectors task

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

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

   Go to Application Integration

2. In the navigation menu, clickIntegrations.

   TheIntegrations 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, clickTasks to view the list of available tasks and connectors.



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

   

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

   

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

Configure the Connectors task

To configure aConnectors task, do the following:Note: Configuration details such as authentication will vary depending upon the connection type.

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

   Optionally, clickedit to rename the task name.

2. ClickConfigure connector.
3. You can either select an existing connection in the region orcreate a new connection. To configure an existing connection, complete the following steps in theConnectors Task Editor page.

   The following image shows a sample layout of theConnectors Task Editor page.

1. In theSelect connection section, select the region of the connection.
2. Choose an existing connection from the list of available connections in the selected region.
3. ClickNext.
4. From theType list, selectEntities orActions.
   • If you selectEntities, the list of supported entities for the connection is displayed in theSet entities/actions section. Select an entity followed by theOperation that you want to perform on that entity.
   • If you selectActions, the list of supported actions for the connection is displayed in theSet 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, seeConnector reference. To view the supported actions and entities for a connector, see the specific connector documentation.

   If the connector supports custom SQL queries, you can select theExecute custom query option from theActions list. For information about how to add custom SQL query for your connector, seeAction: Execute custom SQL query.

   Note: Not all connection types supportEntities orActions. If a connection type doesn't support any actions or entities, the correspondingEntities andActions lists will be empty. For more about entities and actions, seeEntities, operations, and actions.
5. ClickDone to complete the connection configuration and close the pane.

Configure task input and output variables

TheConnectors task configuration pane displaysTask Input andTask Outputvariables that are automatically generated based on theEntity and Operation orAction selected in theConfigure connector task dialog. These variables are configurable and are accessible as inputs to the current task, as outputs to subsequent tasks, or as conditionals in the current integration.

To configure theTask Input orTask Output variables, click the respective variable to open theConfigure Variable pane and perform the following steps:

1. Enter the variable value in theDefault Value field.
2. (Optional) SelectUse as an input to integration orUse as an output to integration.
3. ClickSave.

For more information about the input and output parameters of theConnectors task, seeEntity operations.

Configure authentication override

To enable the connection to accept different backend authentication dynamically during runtime, ensure that in Integration Connectors, you have selected theEnable 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 theConnectors task configuration pane.
2. Expand theTask input section. TheEnd user credentials field is set to adynamicAuthConfig variable.

   

   Then, do the following:

   1. Click thedynamicAuthConfig variable. TheEdit variable pane appears.

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

      

      To do so, follow these steps:

      1. From theVariable type list, selectInput to Integration.
      2. In theJSON schema options, you can verify the authentication type configured for the connection. Use this schema to override the authentication value when youtest the integration.

         

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

   The dynamic authentication header should be in the following JSON format:

   {"task1":{"oauth2_auth_code_flow.access_token":"token_value"},"task2":{"oauth2_auth_code_flow.userename":"username_value"}}

   In this format,taskN corresponds to the Task ID inintegrationVersion.

   

Entity operations and actions

You can perform CRUD (Create, Read, Update, Delete) operationson 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 for the various entity operations.

Input parameters

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

{"employee_first_name": "John","employee_emailID": "test-05@test.com"}

Output parameters

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

Filter clause for entity operations

You can restrict the records that are processed by theConnectors task using theFilter clause variable, which is available as aTask Input. For example, in the case of adelete operation, you can add a filter clause to delete records with a specificorderId.

A filter clause can be applied only for the following entity operations:

• List
• Delete
• Update

When you select any of these operations, theTask Input section of theConnectors task displays theFilter clause field automatically.

Add a filter clause

To add a filter clause, perform the following steps:

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

   TheConfigure Variable dialog appears.

3. Enter the filter clause (following theclause syntax) in theDefault Value field.
4. ClickSave.

Filter clause syntax and examples

A filter clause has the following format:

FIELD_NAMECONDITIONFILTER_VALUE

Use of variables in filter clause

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

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 youconfigure the connector task, in the type of action you want to perform, selectActions.
3. In theAction list, selectExecute custom query, and then clickDone.

   

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

      Default value:180 seconds.

   2. In theMaximum 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, clickEdit Custom Script. TheScript editor dialog opens.

      

   4. In theScript editor dialog, enter the SQL query and clickSave.

      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 theEmployees table that matches the values specified for theLastName column:

      SELECT * FROM Employees where LastName=?

      Note: Data manipulation language (DML) and data definition language (DDL) statements are supported.
   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.

      

      To add query parameters, do the following:

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

   TheExecute custom query action does not support array variables.

Schema refresh

1. In Integration Connectors, open theConnection details page of the connection, and then clickRefresh connection schema.
2. In Application Integration, you mustreconfigure your existing connector task for the same connection.

Inline connection creation

You can use theConnectors task to directly create a new connection inIntegration Connectors.

Before you begin

• Add a Connector task

Create new connection

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

1. Click theConnectors task element on the designer to view theConnectors task configuration pane.
2. ClickConfigure connector.

   TheConnectors Task Editor page appears.

3. Skip theRegion field.
4. ClickConnection and select theCreate Connection option from the drop-down menu.
5. Complete the following steps in theCreate Connection pane:Note: The following instructions are the generic steps to create a connection. While the majority of the steps remain the same for all connection types, a few additional steps or details related to authentication might vary.

   We recommend that you also view the respective connection type documentation inIntegration Connectors.

   1. In theLocation step, choose the location for the connection.
      1. ClickRegion and select a location from the drop-down list.
      2. ClickNext.
   2. In theConnection 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, seeAll 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.Note: Connection names must meet the following criteria:
         • Connection names can use letters, numbers, or hyphens.
         • Letters must be lower-case.
         • Connection names must begin with a letter and end with a letter or number.
         • Connection names cannot exceed 63 characters.
      4. (Optional) Enter aDescription for the connection instance.
      5. (Optional) CheckEnable Cloud Logging to store the log data for the connection instance.
      6. Service Account: Select a service account that has therequired roles.
      7. (Optional) ClickAdvanced settings to configure the connection node settings.

         For more information, see the respective connection documentation inIntegration Connectors.

      8. (Optional) Click+ ADD LABEL to add a label to the connection in the form of a key/value pair.
      9. ClickNext.
   3. In theAuthentication step, provide the authentication details for the connection.
      1. TheAuthentication 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 theConfigure authentication section of the respective connection documentation inIntegration Connectors.

      2. ClickNext.
   4. Review: Review your connection and authentication details.
   5. ClickCreate.

Best practices

• For information about the usage limits that apply to theConnectors task, seeUsage limits.
• For information about how to troubleshoot a failedConnectors task, seeUse logs to troubleshoot and trace connector failures.

Error handling strategy

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

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.

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.