Skip to main content

DCME Endpoints

DCME Endpoints and Parameters

The DCME endpoints are divided into two groups: DCME endpoints for users and DCME endpoints for admins. All DCME 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

DCME Endpoints for Users

These endpoints can be used by users with API access:

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

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

Parameters

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

Request Example: cURL

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

To retrieve a DCM Connection record as it is referenced in workflows, use the GET {baseURL}/v3/dcm/connections/lookup endpoint. The endpoint returns all information about the DCM 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.

Parameters

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

Request Example: cURL

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

To share a DCM 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.

Parameters

  • 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).

Request Example: cURL

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"]}'

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

Parameters

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

Request Example: cURL

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

To create or update a DCM 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.

Parameters

  • upsertConnectionContract (string): Required. DCM Connection is a combination of a data source (describing the target instance host) and credentials (for example, username and password) by defining the possible schema combination.

    • 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.

    • schemaName (string): Required. Enter a connection schema name you’d like to use. The schema defines the required parameters of the connection as well as the data source and credentials schemas allowed to be used for that connection.

    • allowInSdks (boolean): Optional.

    • parameters (object): Required. Various parameters might be required based on the schemaName selected.

    • 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.

        • additional schema-specific parameters: depending on the schema used, you’ll be required to provide additional data source parameters.

    • credentials (string): Optional, depending on the selected schemaName in the upsertConnectionContract. Some connections may not require any credentials, while others may have multiple nested objects (slots).

      • main (object): Optional (see above). This main is just one (most common) credential slot name. It can however be named differently or there might be multiple credential slots for the connection depending on what is defined in the connection schema.

        • 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.

        • additional schema-specific parameters: depending on the schema used, you’ll be required to provide additional data source parameters.

Request Example: cURL

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":{}}}}}}}'

To delete a DCM 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.

Parameters

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

Request Example: cURL

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

DCME Endpoints for Admins

Endpoints that can be used by Curators with API access:

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

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

Parameters

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

Request Example: cURL

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

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

Parameters

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.

Request Example: cURL

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

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

Parameters

  • upsertConnectionContract (string): Required.

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

    • ownerId (string): Required.

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

    • schemaName (string): Required. Enter a connection schema name you’d like to use. The schema defines the required parameters of the connection as well as the data source and credentials schemas allowed to be used for that connection.

    • allowInSdks (boolean): Optional.

    • parameters (object): Required. Various parameters might be required based on the schemaName selected.

    • dataSource (object): Required. The data source used for the connection

      • object (object): Required.

        • id (string): Enter a data source ID if you're updating 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.

        • additional schema-specific parameters: depending on the schema used, you’ll be required to provide additional data source parameters.

    • credentials (string): Optional, depending on the selected schemaName in the upsertConnectionContract. Some connections may not require any credential, while others may have multiple.

      • main (object): Optional (see above).

        • id (string): Enter a credential ID if you’re updating 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.

        • additional schema-specific parameters: depending on the schema used, you’ll be required to provide additional credential parameters.

Request Example: cURL

curl --location --request POST 'https://localhost/webapi/v3/dcm/connections' \ --header 'Authorization: Bearer BearerTokenGoesHere' \ --header "Content-Type: application/json" \ --data '{"Name":"MSSQL DEV Admin","onwerId":"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":{}}}}}}}'

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

Parameters

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

Request Example: cURL

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

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

Parameters

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

Request Example: cURL

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

To delete a DCM 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.

Parameters

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

Request Example: cURL

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

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

Go to DCM Connection Handling for more information.

Parameters

No parameters.

Request Example: cURL

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

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

Parameters

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

Request Example: cURL

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

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

Paramaters

Enter the following parameters 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): Enter a custom name or description of the target connection.

Request Example: cURL

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

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

Parameters

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

Request Example: cURL

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

Objects Relations

If you are creating a DCM 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: