Skip to main content

DCM Endpoints

DCM Endpoints and Properties

The DCM endpoints are divided into 2 groups: DCM endpoints for users and DCM endpoints for admins. All DCM endpoints require TLS to be configured on the Server.

To learn more about the objects relations and how to use them in the API, go to the Objects Relations section.

For more information about data connections, visit the DCM - Server and Data Connection Manager: Server UI help pages.DCM - ServerData Connection Manager: Server UI

What Is a DCM Connection?

A DCM Connection is composed from its own parameters and two types of subobjects: DataSource (there is always just one) and Credentials (in common scenarios there are zero, one or two credentials. In rare cases there could be even more, the number is connector-specific). Each Credential has a different credRole inside the Connection. DCM API works on Connections as whole objects including DataSource and Credentials.

DCM Endpoints for Users

These endpoints can be used by users with API access:

Note

  • All API endpoints return individual user data (each user can only see and manage their own connections).

  • All examples are in PowerShell.

Get Connection

To get a Connection record, use the GET {baseURL}/v3/dcm/connections/{id} endpoint. The endpoint returns all information about the Connection, including the related Data Source and Credentials as well as the sharing information.

Properties

id (string): Required. Enter the ID of the DCM Connection on which you want to obtain information.

curl --location --request GET 'https://localhost/webapi/v3/dcm/connections/d8cc5fca-86cc-4e7e-93a3-d500cca9a3f3' `
  --header 'Authorization: Bearer BearerTokenGoesHere'

Get Connection as Referenced in Workflows

To get a Connection record as it is referenced in workflows, use the GET {baseURL}/v3/dcm/connections/lookup endpoint. The endpoint returns all information about the Connection, including the related Data Source and Credentials as well as the sharing information.

Note

The ConnectionID used in this endpoint is different from the ID used in other DCM endpoints. ID is used to reference various DCM objects, while ConnectionID is only used in workflows to reference DCM Connection for specific users.

Properties

connectionId (string): Required. Enter the DCM ConnectionID on which you want to obtain information.

curl --location --request GET 'https://localhost/webapi/v3/dcm/connections/lookup?connectionId=d8cc5fca-86cc-4e7e-93a3-d500cca9a3f3' `
  --header 'Authorization: Bearer BearerTokenGoesHere'

Share Connection

To share a Connection for Server execution with specified users or groups, use the PUT {baseURL}/v3/dcm/connections/{id}/sharing/execution endpoint.

Note

As this is a PUT endpoint, it overwrites the existing sharing, rather than adding additional users or user groups to the existing list. The provided list of users and groups can’t be empty. In order to remove existing sharing, use the DELETE endpoint.

Properties

  • id (string): Required. Enter the DCM Connection ID you want to share with other users or groups.

  • sharingContract (body): Required. To update execution sharing, the sharingContract parameter is required. Both arrays are required while only one can be left empty.

    • userIds (string array): Enter a list of all user IDs to share the connection with. Leave an empty array if no users to share with (only userGroups).

    • userGroupIds (string array): Enter a list of all user group IDs to share the connection with. Leave an empty array if no user groups to share with (only users).

curl --location --request PUT 'https://localhost/webapi/v3/dcm/connections/d8cc5fca-86cc-4e7e-93a3-d500cca9a3f3/sharing/execution' `
  --header 'Authorization: Bearer BearerTokenGoesHere' `
  --header 'Content-Type: application/json' `
  --data '{
    "userIds": [
      "61d57bea3c15317e1a48205b",
      "61d564361d6d5da7ad461a32"
    ],
    "userGroupIds": [
      "d5da7ad4"
    ]
  }'

Unshare Connection

To unshare a Connection, use the DELETE {baseURL}/v3/dcm/connections/{id}/sharing/execution endpoint.

Properties

id (string): Required. Enter the DCM Connection ID you want to unshare from all users and groups.

curl --location --request DELETE 'https://localhost/webapi/v3/dcm/connections/d8cc5fca-86cc-4e7e-93a3-d500cca9a3f3/sharing/execution' `
  --header 'Authorization: Bearer BearerTokenGoesHere'

Create or Update Connection

To create or update a Connection, use the POST {baseURL}/v3/dcm/connections endpoint.

Single endpoint serves both create and update functions, differentiated by whether object IDs are included in the request. The reuse of existing data sources or credentials is currently unsupported when creating new connections.

Properties

  • id (string): Optional. Enter a connection ID if you wish to update an existing connection. Skip if you wish to create a new connection.

  • name (string): Required. Enter the name of your connection.

    Note

    There are multiple “names” inside a DCM Connection:

    • Connection.name: The name of the Connection itself. Admins interact with this name via the API.

    • Connection.dataSource.object.name: Data Source name visible on the Data Sources tab in the UI.

    • Connection.credentials.<credRole>.object.name: Credential names visible on the Credentials tab in the UI.

    For more details, see the What is a DCM Connection? section.

  • schemaName (string): Required. This is the identifier for a DCM schema, which is used to render and validate the associated parameters in the DCM UI. Each connector defines its own set of supported DCM schemas. The selected connection schema also specifies which DataSource and Credential schemas must be used for the DataSource and Credential sections of the connection. For more details, see What is a DCM Connection? and How is a Connector Related to a DCM Connection?

  • allowInSdks (boolean): Optional. Makes the Connection accessible to Python SDK tools.

  • parameters (object): Required. This property holds configuration details specific to the schema and technology you are connecting to.

    Note

    There are several different parameters objects in a DCM connection structure, each used in a different context:

    • Connection.parameters: For the overall connection (not yet visible in UI, coming soon).

    • Connection.dataSource.object.parameters: For the Data Source part of the connection.

    • Connection.credentials.<credRole>.object.parameters: For each Credential role.

    • Connection.credentials.<credRole>.object.secrets.<secretType>.parameters: For credential secrets, per secret type.

    Each parameters object has its own structure and required fields, which depend on the technology and schemaName defined in that part of the connection. They are independent and can (and often do) contain different fields.

    The parameters property is required but may be provided as empty objects ({}) if no parameters are needed for a given schema.

    Tip: 

    To determine the correct fields for any parameters object:

    1. Create a DCM Connection in the Alteryx Server UI for your target technology.

    2. Query the Connection via API: GET /v3/dcm/connections/{id}

    3. Review the structure and fields returned for each parameters object in the response.

    This is the most reliable way to discover the required and available fields for your specific data source or credential.

    Because parameters fields are data source and credential specific, a comprehensive example for every technology isn’t practical in this documentation. Please use the above workflow to get up-to-date, source-specific examples.

  • dataSource (object): Required. The data source used for the connection, describing the data source instance host and additional parameters, as seen in DCM UI.

    • object (object): Required.

      • id (string): Enter a data source ID if you wish to update an existing connection. Skip if you wish to create a new connection. Using an existing data source when creating new connections is currently unavailable.

      • name (string): Required. Enter a name for the data source.

      • schemaName (string): Required. Enter the schema name of the selected data source. For a detailed description, refer to the Connection.schemaName property.

      • parameters (object): Required. Parameters for the DataSource part of the connection. See Connection.parameters property for more details. Provide empty object {} if no parameters are needed.

  • credentials (object): Required. Key value pairs of <credRole>: object. <credRole>s are defined by the selected DCM schema. The object has just one property named “object" which then contains all the Credential properties. Some connections may not require any credentials, while others may have multiple nested Credential objects.

    From the examples below, you can see that the SQLServer (MSSQL) Username-Password authentication uses main <credRole>. Reshift connection with Identity Pool authentication and Snowflake with OAuth authentication use oauthApplication and oauthTokens <credRoles> for their credentials.

    For more details, see What is a DCM Connection? and How is a Connector related to DCM Connection?

    • object (object): Defines properties of Credential parts of the Connection.

      • id (string): Enter a credential ID if you wish to update an existing connection. Skip if you wish to create a new connection. Using an existing credential when creating new connections is currently unavailable.

      • name (string): Required. Enter the name of your credential.

      • schemaName (string): Required. Enter the schema name of the selected credential.

      • parameters (object): Required. Parameters for the Credential parts of the connection. See Connection.parameters property for more details. Provide empty object {} if no parameters are needed.

Create a SQL Server DCM Connection Using UserName-Password Credentials 

curl --location --request POST 'https://localhost/webapi/v3/dcm/connections' `
  --header 'Authorization: Bearer BearerTokenGoesHere' `
  --header 'Content-Type: application/json' `
  --data '{
    "name": "MSSQL DEV Admin",
    "schemaName": "database-odbc-dsn-mssql",
    "parameters": {},
    "dataSource": {
      "object": {
        "name": "SQL Server DEV",
        "schemaName": "database-odbc-dsn-mssql",
        "parameters": {
          "dsn": "sql server"
        }
      }
    },
    "credentials": {
      "main": {
        "object": {
          "name": "SQL Server Admin Credentials",
          "schemaName": "username_password",
          "parameters": {},
          "userName": "admin",
          "secrets": {
            "password": {
              "value": {
                "text": "password"
              },
              "parameters": {}
            }
          }
        }
      }
    }
  }'

Create an ODBC DCM Connection to Redshift Using OAuth Authentication with AWS IAM / Cognito 

curl --location --request POST 'https://localhost/webapi/v3/dcm/connections' `
  --header 'Authorization: Bearer BearerTokenGoesHere' `
  --header 'Content-Type: application/json' `
  --data '{
    "name": "Connection Name",
    "schemaName": "database-odbc-redshift-simba-oauth-iam-identitypool",
    "allowInSdks": false,
    "parameters": {},
    "dataSource": {
        "object": {
            "name": "DataSource Name",
            "schemaName": "database-odbc-redshift-simba",
            "drvName": "Simba Amazon Redshift ODBC Driver",
            "host": "##### (my-database-host.redshift.amazonaws.com)",
            "parameters": {
                "allowSelfSignedServerCert": false,
                "checkCertRevocation": false,
                "database": "#####",
                "minTLS": 2,
                "port": 5439,
                "sslMmode": "require",
                "useSystemTrustStore": false
            }
        }
    },
    "credentials": {
        "oauthApplication": {
            "object": {
                "name": "Application Credential Name",
                "schemaName": "database-redshift-aws-oauth-iam-identitypool-application",
                "userName": "##### (Client Secret)",
                "parameters": {
                    "accountId": "#####",
                    "authorityURL": "##### (https://my-authorization-host.amazoncognito.com)",
                    "awsRegion": "##### (us-west-2)",
                    "dbUser": "#####",
                    "identityPoolId": "#####",
                    "redirectURI": "##### (http://localhost:5634)",
                    "userPoolId": "#####"
                },
                "secrets": {
                }
            }
        },
        "oauthTokens": {
            "object": {
                "name": "Tokens Credential Name",
                "schemaName": "aws-oauth-iam-identitypool-tokens",
                "parameters": {},
                "secrets": {
                }
            }
        }
    }
}'

Create a Snowflake DCM Connection with OAuth 2.0 Client Credentials 

curl --location --request POST 'https://localhost/webapi/v3/dcm/connections' `
  --header 'Authorization: Bearer BearerTokenGoesHere' `
  --header 'Content-Type: application/json' `
  --data '{
    "name": "Connection Name",
    "schemaName": "database-odbc-snowflake-simba-oauth-generic-configurable",
    "allowInSdks": false,
    "parameters": {},
    "dataSource": {
        "object": {
            "name": "DataSource Name",
            "schemaName": "database-odbc-snowflake-simba",
            "drvName": "Simba Snowflake ODBC Driver",
            "host": "##### (my-domain.snowflakecomputing.com)",
            "parameters": {
                "database": "#####",
                "schema": "#####",
                "warehouse": "#####"
            }
        }
    },
    "credentials": {
        "oauthApplication": {
            "object": {
                "name": "Application Credential Name",
                "schemaName": "generic-configurable-oauth-application",
                "userName": "##### (Client Id)",
                "parameters": {
                    "clientAuthentication": "body",
                    "grantType": "clientCredentials",
                    "tokenURL": "#####"
                },
                "secrets": {
                    "clientSecret": {
                        "expiresOn": null,
                        "parameters": {},
                        "value": {
                            "text": "##### (Client Secret)"
                        }
                    }
                }
            }
        },
        "oauthTokens": {
            "object": {
                "name": "Tokens Credential Name",
                "schemaName": "generic-configurable-oauth-tokens",
                "userName": null,
                "parameters": {
                    "scope": "#####"
                },
                "secrets": {}
            }
        }
    }
}'

Delete Connection

To delete a Connection, use the DELETE {baseURL}/v3/dcm/connections/{id} endpoint. The data source and credentials will be deleted as well unless they are used in any other connection.

Properties

id (string): Required. Enter the DCM Connection ID you want to delete.

curl --location --request DELETE 'https://localhost/webapi/v3/dcm/connections/d8cc5fca-86cc-4e7e-93a3-d500cca9a3f3' `
  --header 'Authorization: Bearer BearerTokenGoesHere'

DCM Endpoints for Admins

Endpoints that can be used by Curators with API access:

Note

  • All admin API endpoints return all data available on the Server across all users, regardless of ownership.

  • All examples are in PowerShell.

Get Connection

To get a Connection record, use the GET {baseURL}/v3/dcm/admin/connections/{objectId} endpoint.

Properties

objectId (string): Required. Enter the DCM Connection ID you want to get information about.

curl --location --request GET 'https://localhost/webapi/v3/dcm/admin/connections/d8cc5fca-86cc-4e7e-93a3-d500cca9a3f3' `
  --header 'Authorization: Bearer BearerTokenGoesHere'

List Connections

To get a list of all Connection records present on the Server, use the GET {baseURL}/v3/dcm/admin/connections endpoint.

Properties

Both parameters are filters that can be combined. Using connectionId and visibleBy together will return the connection with the ConnectionID specified, visible by the specified user.

  • connectionId (string): Optional. Filters connections by its connectionID, as referenced from a workflow. Multiple connections can be returned for a single connectionID, if the connection is shared for collaboration.

  • visibleBy (string): Optional. Enter user ID. If present, it filters the results to the same result as for all connections available to the specified user.

curl --location --request GET 'https://localhost/webapi/v3/dcm/admin/connections?connectionId=d8cc5fca-86cc-4e7e-93a3-d500cca9a3f3&visibleBy=bc7cb7b47c33' `
  --header 'Authorization: Bearer BearerTokenGoesHere'

Create or Update Connection on Behalf of User

To create or update a Connection record on behalf of a user, use the POST {baseURL}/v3/dcm/admin/connections endpoint.

Properties

Use the same properties as described in the Create or Update Connection section. The only additional property required for this endpoint is ownerId.

ownerId (string): Required.

  • When creating a Connection, enter the ID of the user on behalf of which the connection shall be created.

  • When updating a Connection, you must also enter the ownerId even if you don't want to change it. For more information how to get an ownerID, go to Get Connection or List Connections.

curl --location --request POST 'https://localhost/webapi/v3/dcm/connections' `
  --header 'Authorization: Bearer BearerTokenGoesHere' `
  --header 'Content-Type: application/json' `
  --data '{
    "upsertConnectionContract": {
      "name": "MSSQL DEV Admin",
      "ownerId": "1b4bc56d489d9543a",
      "schemaName": "database-odbc-dsn-mssql",
      "parameters": {},
      "dataSource": {
        "object": {
          "name": "SQL Server DEV",
          "schemaName": "database-odbc-dsn-mssql",
          "parameters": {
            "dsn": "sql server"
          }
        }
      },
      "credentials": {
        "main": {
          "object": {
            "name": "SQL Server Admin Credentials",
            "schemaName": "username_password",
            "parameters": {},
            "userName": "admin",
            "secrets": {
              "password": {
                "value": {
                  "text": "password"
                },
                "parameters": {}
              }
            }
          }
        }
      }
    }
  }'

Unshare Connection Shared for Execution

To unshare Connection whose type of sharing has been defined as Shared for Execution, use the DELETE {baseURL}/v3/dcm/admin/connections/{objectId}/sharing/execution endpoint.

Properties

objectId (string): Required. Enter the DCM Connection ID to be unshared for execution.

curl --location --request DELETE 'https://localhost/webapi/v3/dcm/admin/connections/d8cc5fca-86cc-4e7e-93a3-d500cca9a3f3/sharing/execution' `
  --header 'Authorization: Bearer BearerTokenGoesHere'

Unshare Connection Shared for Collaboration

To unshare a Connection whose type of sharing has been defined as Shared for Collaboration, use the DELETE {baseURL}/v3/dcm/admin/connections/{objectId}/sharing/collaboration endpoint.

Properties

objectId (string): Required. Enter the DCM Connection ID to be unshared for collaboration.

curl --location --request DELETE 'https://localhost/webapi/v3/dcm/admin/connections/d8cc5fca-86cc-4e7e-93a3-d500cca9a3f3/sharing/collaboration' `
  --header 'Authorization: Bearer BearerTokenGoesHere'

Delete Connection

To delete a Connection record, use the DELETE {baseURL}/v3/dcm/admin/connections/{objectId} endpoint. The data source and credentials will be deleted as well unless they are used in any other connection.

Properties

objectId (string): Required. Enter the DCM Connection ID you want to delete.

curl --location --request DELETE 'https://localhost/webapi/v3/dcm/admin/connections/d8cc5fca-86cc-4e7e-93a3-d500cca9a3f3' `
  --header 'Authorization: Bearer BearerTokenGoesHere'

Get All Connection Handling Rules

To get all Connection handling rules, use the GET {baseURL}/v3/dcm/admin/connectionhandlingrules endpoint.

Go to DCM Connection Handling for more information.

Properties

No properties.

curl --location --request GET 'https://localhost/webapi/v3/dcm/admin/connectionhandlingrules' `
  --header 'Authorization: Bearer BearerTokenGoesHere'

Get Connection Handling Rule

To get a specific DCM Connection handling rule, use the GET {baseURL}/v3/dcm/admin/connectionhandlingrules/{id} endpoint.

Properties

id (string): Required. Specify the ID of the DCM connection handling rule to return.

curl --location --request GET 'https://localhost/webapi/v3/dcm/admin/connectionhandlingrules/{id}' `
  --header 'Authorization: Bearer BearerTokenGoesHere'

Add or Update Connection Handling Rule

To add a new Connection handling rule or update an existing one, use the POST {baseURL}/v3/dcm/admin/connectionhandlingrules endpoint.

Properties

Enter the following properties to create or update a DCM connection handling rule:

  • rule (body): Required. The DCM ConnectionHandlingRule to create or update.

    • id (string): Optional. The DCM connection handling rule ID. Enter a DCM connection handling rule ID if you wish to update an existing connection handling rule. Skip if you wish to create a new connection handling rule.

    • sourceConnectionId (string): Enter a sourceConnectionId, referencing a ConnectionId to be replaced at workflow execution. The Connection doesn’t have to exist on the Server (workflows referencing it can still be executed). It can’t be used in another existing rule, be it as a source connection or target connection.

    • sourceConnectionTitle (string): Enter a custom name or description of the source connection.

    • targetConnectionId (string): Enter a targetConnectionId. Must be referencing a DCM connection present on the Server.

    • targetConnectionTitle (string): Optional. Enter a custom name or description of the target connection. It autocompletes to the title of the selected connection.

curl --location 'https://localhost.com/webapi/v3/dcm/admin/connectionhandlingrules' `
--header 'Content-Type: application/json' `
--header 'Authorization: Bearer BearerTokenGoesHere' `
--data '{
    "sourceConnectionTitle": "MSSQL DEV",
    "sourceConnectionId": "c.cid.d8cc5fca-86cc-4e7e-93a3-d500cca9a3f3",
    "targetConnectionId": "c.cid.cbf55382-f90b-4304-a1cd-37c5cff697e0"
}'

Delete Connection Handling Rule

To delete an existing Connection handling rule, use the DELETE {baseURL}/v3/dcm/admin/connectionhandlingrules/{id} endpoint.

Properties

id (string): Required. Specify the DCM connection handling rule ID you want to delete.

curl --location --request DELETE 'https://localhost/webapi/v3/dcm/admin/connectionhandlingrules/{id}' `
  --header 'Authorization: Bearer BearerTokenGoesHere'

Objects Relations

If you are creating a Connection, you can use created objects as follows:

Object created:

  • "id" (for example, "id": "c128cc5fca-86cc-4e7e-93a3-d500cca9a3f3")

  • connectionId” (for example, "id": "c0332423423-86cc-4e7e-93a3-d500cca9a3f3")

You can use it as:

Admin: