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.
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'
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
parametersobjects 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
schemaNamedefined in that part of the connection. They are independent and can (and often do) contain different fields.The
parametersproperty 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:
Create a DCM Connection in the Alteryx Server UI for your target technology.
Query the Connection via API:
GET /v3/dcm/connections/{id}Review the structure and fields returned for each
parametersobject in the response.
This is the most reliable way to discover the required and available fields for your specific data source or credential.
Because
parametersfields 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.schemaNameproperty.parameters (object): Required. Parameters for the
DataSourcepart of the connection. SeeConnection.parametersproperty 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. Theobjecthas 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
oauthApplicationandoauthTokens <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
Credentialparts of the connection. SeeConnection.parametersproperty 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.
Note
You can’t transfer ownership of a DCM Connection. You can only create or update a Connection for a specific 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
ownerIdeven if you don't want to change it. For more information how to get anownerId, 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": {}
}
}
}
}
}
}
}'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:
id if you want to get a Connection.
connectionId if you want to get a Connection as referenced in workflows.
id if you want to share a Connection with specified users and groups.
id if you want to update a Connection.
id if you want to delete a Connection.
id if you want to unshare a Connection.
Admin:
id if you want to get a Connection.
ownerId (userId) if you want to create a Connection on behalf of a user.
id if you want to update a Connection on behalf of a user.
id if you want to unshare a Connection shared for execution.
id if you want to unshare a Connection shared for collaboration.
id if you want to delete a Connection.