Connectors task

Stay organized with collections Save and categorize content based on your preferences.

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

The Connectors task lets you use any of the supported connections that were created in the connectors UI. By using a connection, you can easily call various Google Cloud services and third-party business applications from your integrations.

Before you begin

Before you can use the Connectors task in your Apigee Integration, you must create a connection using the Connectors UI in the Cloud console. Once a Connector is configured, you can use the Connectors task to create a connection of that type in your integration.

The following connectors are available:

  • Active Directory
  • Apache Cassandra
  • Apache Kafka
  • Apache CouchDB
  • BigQuery
  • Box
  • Pub/Sub
  • Cloud Spanner
  • Cloud SQL - MySQL
  • Cloud SQL - PostgreSQL
  • Cloud SQL - SQL Server
  • CockroachDB
  • Elasticsearch
  • Email
  • Jira Cloud
  • LDAP
  • MariaDB
  • MongoDB
  • Dynamics NAV
  • MySQL
  • PayPal
  • Oracle DB
  • PostgreSQL
  • Redis
  • Salesforce
  • ServiceNow
  • SFTP
  • Splunk
  • SQL Server
  • Twilio
  • Workday
  • Zendesk
  • Configure the Connectors task

    This section describes the general steps required to configure the Connectors task in Apigee Integration. Configuration details such as authentication will vary depending upon the connection type.

    To configure the Connectors task:

    1. In the Apigee UI, select your Apigee Organization.
    2. Click Develop > Integrations.
    3. Select an existing integration or create a new integration by clicking CREATE INTEGRATION.

      If you are creating a new integration:

      1. Enter a name and description in the Create Integration dialog.
      2. Select a Region for the integration from the list of supported regions.
      3. Click Create.

      This opens the integration in the integration designer.

    4. In the integration designer navigation bar, click +Add a task/trigger > Tasks to view the list of available tasks.
    5. Click and place the Connectors element in the integration designer.
    6. Click the Connectors task element on the designer to view the Connectors task configuration pane.
    7. Optionally, click the to edit the task name. This enables you to change the task name from the generic Connectors to a meaningful name for your integration.
    8. On the Configuration tab in the Configuration section, click the Configure task button to open the Configure connector task pane.
      1. In the Connection column, choose the connection type you created in the Connectors UI from the list of available connections.
      2. Once a connection is chosen, the Type column appears. Select either an Entity or Action from the list of available Entities and Actions.
        • An Entity can be thought of as an object, or a collection of properties, in the connected application or service, that can be exposed to an integration through the Connector interface.

          Selecting an Entity from the available list generates a list of available Operations that are available for the Entity.

          Select an Operation from the available list. You can restrict the number of records for an operation by adding a filter. For more information, see Add a filter for an operation.

        • An Action is a first class function that is made available to the integration through the Connector interface. Functions are defined in the connected application or service and define a change or series of changes that can be made to an entity or entities.

          Select an Action from the available list.

      3. Click Done to complete the connection configuration and close the pane.
    9. The Connectors task configuration pane also displays Task Input and Task Output variables automatically generated based on the Entity and Operation or Action selected in the previous step. These variables are configurable and are accessible as inputs to the current task or outputs to subsequent tasks or conditionals in the current integration.

      To configure the Task Input or Task Output variables, click on 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 the Use as an input to integration checkbox or the Use as an output to integration, as desired.
      3. Click Save.
      For the description of all the input and output parameters, see Configuration properties.

    Configuration properties

    The Connectors task lets you perform CRUD (Create, Read, Update, Delete) operations on the entities. Each of these entity operations have a different set of input and output parameters. The following table describes 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

    This section 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, integrations reports a runtime error and the Connectors task fails.

    For example, to get a specific row from a MySQL table, the entityId will be a primary key value in the table. Similarly, to update a specific row in a BigQuery dataset, the entityId will be a primary key value in the dataset.

    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(s) by which you want to sort the result set. If you want to sort the result set by more than one column, specify multiple column names as comma separated values.

    Output parameters

    This section 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 For Each Loop task to repeatedly call the Connectors task and use the Data Mapping task to automatically assign token values to the listEntitiesPageToken input parameter after each run.

    Add a filter for an operation

    You can restrict the records that will be processed by the Connectors task by adding a Filter clause in the Task Input. For example, in case of a delete operation, you can add a filter to delete records with a specific orderId. The 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.

    To add a filter, perform the following steps:

    1. In the Task Input section, click filterClause (Connectors).
    2. In the Configure Variable window, enter the filter clause in the Default Value field.

      For examples of filter clauses, see Filter clause examples.

    3. Click Save.

    Filter clause examples

    You can think of filter as a WHERE clause in a SQL query. A filter clause has the following format:

    <FIELD_NAME> <CONDITION> <FILTER_VALUE>

    The following are examples of a filter clause:

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

    Retry on failure

    You can configure various retry strategies to handle errors in a task. The retry strategies allow you to specify how to rerun the task or integration in case of an error. For more information, see Error handling strategies.