API Reference > Part II: Authenticate using JWT > Manage data collections > Modify data collections

Modify data collections

Use a REST API to modify a data collection in Data Marketplace.

Endpoint and method

The following table describes the connection properties for the API:

Property

Description

Endpoint

/api/v2/data-collections/<dataCollectionId>

<dataCollectionId>: Required. Enter the system-generated unique identifier of the data collection that you want to modify.

For more information about how you can use an API to get the system-generated unique identifier of a data collection, see Retrieve all data collections.

To get the system-generated unique identifier of a data collection from the Data Marketplace user interface, open the data collection. The data collection page's URL contains the unique identifier.

For example, in the URL https://{{CDMP_URL}}/datacollection/25158afc-3dfb-44ef-8f3e-cec1e171d0f1?dtn=&tab=summary, the unique identifier is 25158afc-3dfb-44ef-8f3e-cec1e171d0f1.

Method

PATCH

For more information about how you can call an API, see Authenticate using JWT.

Request

The following table describes the parameters that you enter in the body of the API payload:

Parameter	Description	Additional Information
operation	Required. Specify the type of change you want to make to the data collection. Enter one of the following values: - To add a value to a parameter, enter add. - To replace an existing value of a parameter, enter replace. - To remove a value from a parameter, enter remove.	-
segment	Required. Specify the type of details that you want the API request to modify. Enter one of the following values: - To modify the value specified in the categoryId parameter, enter category. - To modify the value specified in the customAttributes parameter, enter customAttributes. - To modify the values specified in the name, description, externalId and status parameters, enter summary. - To modify the values specified in the stakeholderId and roleID parameters, enter stakeholdership. - To modify the value specified in the termsOfUse parameter, enter termsOfUse. - To modify the value specified in the usageContexts parameter, enter usageContexts.	-
name	Optional. Enter a name for the data collection.	Ensure that you enter a unique value. Data Marketplace doesn't consider the letter case when it verifies the uniqueness of the name parameter's value. For example, if you try to name a category as "Retail Department" while a category called "Retail department" already exists, the API call fails.
description	Optional. Enter a description for the data collection.	-
externalId	Optional. Enter a reference identifier for the data collection.	If you don't specify a reference identifier, Data Marketplace automatically assigns a unique value to the item. The reference identifier that Data Marketplace automatically generates contains a prefix. The administrator can specify the prefix of the automatically generated reference identifier in Metadata Command Center. If you want to specify a reference identifier, ensure that you enter a unique value. Ensure that you don't use the prefix value that is configured in Metadata Command Center.
status	Optional. Specify a status for the data collection. The status determines whether the data collection is discoverable to Data Users. Enter one of the following values: - To make the data collection discoverable to Data Users, enter PUBLISHED. - To make the data collection undiscoverable to Data Users, enter UNPUBLISHED.
customAttributes	Specify the custom attribute values for the data collection or modify the values that are already specified for the custom attribute.	Whether you must enter a value in a custom attribute or not is determined by how the custom attribute was defined by your administrator in Metadata Command Center. Custom attributes are additional properties for Data Marketplace items that are defined by your administrator in Metadata Command Center. For more information about custom attributes, see the Create custom attributes for items topic in the Set Up Data Marketplace help.
customAttributes > value	Enter the updated value for the custom attribute.	-
customAttributes > id	Enter the system-generated unique identifier of the custom attribute that you want to modify.	For more information about how you can retrieve the system-generated unique identifier of a custom attribute, see Retrieve custom attributes.
stakeholdership > stakeholderId	Optional. Enter the system-generated unique identifier of the user account or user group that you want to assign as a stakeholder for the data collection.	- To get the system-generated unique identifier of a user account, navigate to My Services > Administrator > Users. On the Users page, click a user account. The user account page's URL contains the unique identifier. For example, in the URL /cloudUI/products/administer/main/usersAsset/0LH3xBJC9A6haZ26htGZyT, the unique identifier is 0LH3xBJC9A6haZ26htGZyT. - To get the system-generated unique identifier of a user group, navigate to My Services > Administrator > User Groups. On the User Groups page, click a user group. The user group page's URL contains the unique identifier. For example, in the URL /cloudUI/products/administer/main/userGroupsAsset/90uizkSWg0ycuu7hSNXSW4, the unique identifier is 90uizkSWg0ycuu7hSNXSW4.
stakeholdership > roleId	Optional. Enter the system-generated unique identifier of the user role that is assigned to the stakeholder that you specified in the stakeholderId parameter.	If you specify a value for the stakeholderId parameter, ensure that you also specify a value for the roleId parameter. To get the system-generated unique identifier of a user role, navigate to My Services > Administrator > User Roles. On the User Roles page, click a user role. The user role page's URL contains the unique identifier. For example, in the URL /cloudUI/products/administer/main/userRolesAsset/90uizkSWg0ycuu7hSNXSW4, the unique identifier is 90uizkSWg0ycuu7hSNXSW4.
usageContexts	Optional. Enter the system-generated unique identifier of the usage type that you want to use to specify the context in which you intend to use the data after you receive access to the collection.	For more information about how you can use an API to get the system-generated unique identifier of a usage type, see Retrieve usage type.
termsOfUse	Optional. Enter the system-generated unique identifier of the terms of use that you want to associate with the data collection.	For more information about how you can use an API to get the system-generated unique identifier of a terms of use, see Retrieve terms of use.
categoryId	Optional. The system-generated unique identifier of the category to which you want to move the data collection.	For more information about how you can use an API to get the system-generated unique identifier of a category, see Retrieve all categories. To get the system-generated unique identifier of a category from the Data Marketplace user interface, open the category. The category page's URL contains the system-generated unique identifier. For example, in the URL https://{{CDMP_URL}}/category/view?ac=67417f72-e5ab-44f0-add9-a1e412c1ce13&dtn=_AfterEBF%20may20, the system-generated unique identifier is 67417f72-e5ab-44f0-add9-a1e412c1ce13.

Example request

The following example shows how you can use an API to modify a data collection:

{
"operation": "replace",
"segment": "summary",
"value": {
"name": "Aggregated Sales Data",
"description": "Sales data from all sources (physical online subscription) in one place for easy analysis.",
"externalId": "DCL-1",
"status": "PUBLISHED"
}
}

Response

When you invoke the API using a REST client, the client displays a response for the parameter values that you have entered.

If you see the following response code, it means that the data collection is successfully modified:

204 OK code

If you modify the category or stakeholder of a data collection, the REST client displays the following response code to indicate that a job was created in Metadata Command Center to apply your changes:

202 Accepted code

The following example shows the response of an API call to modify a category for which a job was created in Metadata Command Center to apply the changes:

{
"trackerJobId": "b93c4539-a93e-440d-a4b4-95d69b8911e6",
"propagationJobId": "b93c4539-a93e-440d-a4b4-95d69b8911e6"
}

The following table describes the parameters of each job that is created in Metadata Command Center:

Parameter	Description
trackerJobId	System-generated identifier of the job that enables you to track the progress of the job in Metadata Command Center. For more information about jobs in Metadata Command Center, see the Administration help in Metadata Command Center.
propagationJobId	System-generated identifier of the internal job that applies your changes to Data Marketplace .