Connections¶

Introduction¶

A connection, created using a connector, establishes access to an endpoint. Once a connection is configured, you can create instances of activities associated with that connection to be used either as sources (to provide data in an operation) or as targets (to consume data in an operation).

Create or Edit a Connector Connection¶

A new connection is created using a connector from one of these locations:

• The design component palette's Connections tab (see Design Component Palette).
• The Global Connections page (see Create a Global Connection in Global Connections).

An existing connection can be edited from these locations:

• The design component palette's Connections tab (see Design Component Palette).
• The project pane's Components tab (see Component Actions Menu in Project Pane Components Tab).
• The Global Connections page (see Edit a Global Connection in Global Connections).

Configure a Connector Connection¶

Each user interface element of a typical connection configuration screen is described below. Many connectors use a similar configuration screen. Connectors that use a different screen are documented with images showing that particular interface. This example, common to many connectors, shows a Dynamics 365 Sales connection:

• Connection Name: Enter a name to use to identify the connection. The name must be unique for each connection and must not contain forward slashes (/) or colons (:). This name is also used to identify the endpoint, which refers to both a specific connection and its activities.

• Authentication: Select to specify the authentication settings. Documentation on the available fields is typically available under the Connection String Options section of documentation for each individual connector. In this example, see Authentication for Dynamics 365 Sales.

• Azure Authentication: This example shows Azure-specific authentication settings. Connectors can have connector-specific authorization requirements and options, and this example shows the location of the Azure-specific settings. Documentation on the available fields is typically available under the Connection String Options section of documentation for each individual connector. For this example, see Azure Authentication for Dynamics 365 Sales.

• OAuth: Select to specify the OAuth settings. Documentation on the available fields is typically available under the Connection String Options section of documentation for each individual connector. For example, see OAuth for Dynamics 365 Sales. See also the section below on configuring OAuth connections.

• SSL: Select to specify the SSL settings. Documentation on the available fields is typically available under the Connection String Options section of documentation for each individual connector. For example, see SSL for Dynamics 365 Sales.

• Use Proxy Settings: Select to use Private Agent proxy settings.

• Advanced Configurations: Select to specify advanced configuration properties as key-value pairs. Documentation on the available keys and values is typically available under Advanced Configurations in the Connection String Options section of documentation for each individual connector. For example, see Advanced Configurations for Dynamics 365 Sales.

• Test: Click to verify the connection using the specified configuration.

• Save Changes: Click to save and close the connection configuration.

• Discard Changes: After making changes to a new or existing configuration, click to close the configuration without saving. A message asks you to confirm that you want to discard changes.

• Delete: After opening an existing connection configuration, click to permanently delete the connection from the project and close the configuration (see Component Dependencies, Deletion, and Removal). A message asks you to confirm that you want to delete the connection.

Configure OAuth Connections¶

For certain connectors, it is possible to configure a connection using OAuth by using specific configuration properties. The connector documentation indicates if the connector supports OAuth connections and links to this section.

After selecting OAuth, you will be able to specify the configuration in the fields that are displayed.

For these connectors, two scenarios are supported. In either scenario, you will need to use a third-party tool (such as Postman or a similar tool) to obtain the required access token or tokens from the endpoint involved. Both of these scenarios work only for single-agent groups. These are Agent Groups that consist of a single agent.

• Scenario 1: Using an OAuth access token that expires after a set period of time.

  With this configuration, you supply an OAuth access token that lasts for set period of time, as determined by the particular endpoint. The connector will use the token to make the connection. The connection, however, will no longer work once the access token expires. You would configure the Advanced Configurations for the connector to use the token by setting these properties:

  Configuration Property	Value
  Initiate OAuth	OFF
  OAuth Access Token	Set to the value of the OAuth access token obtained from the endpoint

• Scenario 2: Using an OAuth access token combined with an OAuth refresh token to enable automatic refresh of access.

  With this configuration, the connector will use a refresh token to obtain a new access token once the current access token has expired. This is generally the best method of configuring OAuth.

  You supply an OAuth access token and an OAuth refresh token, as determined by the particular endpoint. You would configure the Advanced Configurations for the connector to use these tokens by setting these properties:

  Configuration Property	Value
  Initiate OAuth	REFRESH
  OAuth Access Token	Set to the value of the OAuth access token obtained from the endpoint
  OAuth Refresh Token	Set to the value of the OAuth refresh token obtained from the endpoint

Next Steps¶

After a connector connection has been created, you place an activity type on the design canvas to create activity instances to be used either as sources (to provide data in an operation) or as targets (to consume data in an operation).

Menu actions for a connection and its activity types are accessible from the project pane and design component palette. For details, see Actions Menus in Connector Basics.

The available activity types depends on the individual connector. For many connectors, these activities are available:

• Query: Retrieves an object from an endpoint and is intended to be used as a source in an operation. (Generically documented as Query Activities.)

• Create: Creates an object in an endpoint and is intended to be used as a target in an operation. (Generically documented as Create Activities.)

• Update: Updates an object in an endpoint and is intended to be used as a target in an operation. (Generically documented as Update Activities.)

• Delete: Deletes an object from an endpoint and is intended to be used as a target in an operation. (Generically documented as Delete Activities.)

• Execute: Executes a procedure in an endpoint and is intended to be used as a target in an operation. (Generically documented as Execute Activities.)