API Reference > Define settings for data collections > Delivery targets
  

Delivery targets

A delivery target is a delivery option that you as a stakeholder of a data collection can use to deliver data to a Data User. Stakeholders use delivery templates to create new delivery targets for their data collections. To ensure that you can fulfill an order, ensure that you configure a delivery target for your data collection.

Create delivery targets

Use a REST API to create delivery targets in Data Marketplace.

Endpoint and method

The following table describes the connection properties for the API:
Property
Description
Endpoint
/api/v1/integration/provisioning/deliveryTargets
Method
POST

Request

The following table describes the parameters that you enter in the body of the API payload:
Parameter
Description
Additional Information
refId
Optional. Enter a reference identifier for the delivery target.
If you don't specify a reference identifier, Data Marketplace automatically assigns a unique value to the object. 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.
name
Required. Enter a name for the delivery target.
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 delivery target as "Excel over ipfs" while a delivery target called "Excel over IPFS" already exists, the API call fails.
description
Required. Enter a description for the delivery target.
-
status
Required. Specify a status for the delivery target. The status determines whether the delivery target is available for use to the Data Users that order the data collection.
Enter one of the following values:
  • - To make the delivery targets available, enter ACTIVE.
  • - To make the delivery targets unavailable, enter INACTIVE.
targetSystemReference
Optional. Enter the target system or resource reference from where the data is obtained.
-
physicalLocation
Optional. Enter the URL of the delivery location.
If the Managed Access option is enabled for the deliver template that you specified in the deliveryTemplateId parameter, the data won't be delivered to the location that you specify in the physicalLocation parameter. Instead, the data will be delivered to a location that is generated at the time of order fulfillment. The generated location is unique to each order that is fulfilled using this target.
For more information, see the Manage access to data with Data Access Management topic in the Set Up Data Marketplace help.
deliveryTemplateId
Required. Enter the system generated unique identifier of the delivery template that you want to use to create the delivery target.
For more information about how you can use an API to get the system generated unique identifier of a delivery template, see Retrieve delivery templates.
deliveryMethodId
Required. Enter the system generated unique identifier of the delivery method that constitutes the delivery target.
For more information about how you can use an API to get the system generated unique identifier of a delivery method, see Retrieve delivery methods.
deliveryFormatId
Required. Enter the system generated unique identifier of the delivery format that constitutes the delivery target.
For more information about how you can use an API to get the system generated unique identifier of a delivery format, see Retrieve delivery formats.
dataCollectionId
Required. Enter the system generated unique identifier of the data collection in which you want to create the delivery target.
For more information about how you can use an API to get the system generated unique identifier of a data collection, see Retrieve data collections.
To get the system generated unique identifier of a data collection, open the data collection. The data collection page's URL contains the system generated unique identifier.
For example, in the URL https://{{CDMP_URL}}/datacollection/25158afc-3dfb-44ef-8f3e-cec1e171d0f1?dtn=&tab=summary, the system generated unique identifier is 25158afc-3dfb-44ef-8f3e-cec1e171d0f1.
Note: If the Managed Access option is enabled for the deliver template that you specified in the deliveryTemplateId parameter, ensure that the data collection that you specify in the dataCollectionId parameter is comprised only of data assets that belong to the same data source. For more information about how you can add data assets to a data collection, see Add or remove data assets from data collections.

Example request

The following example shows how you can use an API to create a delivery target:
{
"items": [
{
"refId": "Target561",
"name": "Customer DB",
"description": "Customer DB Delivery",
"status": "ACTIVE",
"targetSystemReference": "AXON",
"physicalLocation": "Oracle db",
"deliveryTemplateId": "94df4d34-22f3-3f3e-9409-2b0354c87365",
"deliveryMethodId": "c35181e7-7832-3b5c-b0d3-fc2360a82f05",
"deliveryFormatId": "fe4e89ab-80e9-3e0d-8aba-71b79deab4b8",
"dataCollectionId": "d2aef733-4886-38df-8eb3-6db8be9d0fb9"
}
]
}

Response

When you pass the API payload in the REST client, the client displays a response for the parameter values that you have entered.
The following example shows the response of an API call to create a delivery target:
{
"processingTime": 4769,
"objects": [
{
"index": 1,
"id": "13c937c3-e6d8-3006-a530-f3cd6ecf2a8f",
"refId": "Target561",
"name": "Customer DB"
}
]
}
The following table describes the parameters of each delivery target that is created:
Parameter
Description
index
The position of the delivery target in the objects JSON array. This value does not impact how the delivery target is used by a Data Marketplace user.
id
System generated unique identifier of the delivery target.
refId
Reference identifier of the delivery target.
name
Name of the delivery target.

Retrieve delivery targets

Use a REST API to retrieve the details of a delivery target in Data Marketplace.

Endpoint and method

The following table describes the connection properties for the API:
Property
Description
Endpoint
/api/v1/integration/provisioning/deliveryTargets
Method
GET
Note: Before you call this API, consider the following:
For more information, see How to call a Data Marketplace API.

Request

The following table describes the parameters that you enter in the request query:
Parameter
Description
Additional Information
search
Optional. Enter the search term that you want to use to find a delivery target.
Ensure that the search term that you enter don't contain an asterisk (*).
fields
Optional. Enter the fields on which the search term applies. The terms that you entered in the search field parameter are used to search the fields that you specify here.
Enter the following values:
  • - NAME
  • - DESCRIPTION
ids
Optional. Enter the system generated unique identifier of a delivery target.
To enter more than one value, use the following format:
ids=<value1>&ids=<value2>
dataCollectionIds
Optional. Enter the system generated unique identifier of the data collection that is associated with the delivery target.
For more information about how you can use an API to get the system generated unique identifier of a data collection, see Retrieve data collections.
To get the system generated unique identifier of a data collection, open the data collection. The data collection page's URL contains the system generated unique identifier.
For example, in the URL https://{{CDMP_URL}}/datacollection/25158afc-3dfb-44ef-8f3e-cec1e171d0f1?dtn=&tab=summary, the system generated unique identifier is 25158afc-3dfb-44ef-8f3e-cec1e171d0f1.
deliveryTemplateIds
Optional. Enter the system generated unique identifier of a delivery template.
For more information about how you can use an API to get the system generated unique identifier of a delivery template, see Retrieve delivery templates.
status
Optional. Specify the status of the delivery target. The status indicates whether the delivery target is available for use to the Data Users that order the data collection.
Enter one of the following values:
  • - To find the delivery targets that are available, enter ACTIVE.
  • - To find the delivery targets that aren't available, enter INACTIVE.
isDefault
Optional. Specify whether to retrieve the default delivery target of a data collection.
Enter one of the following values:
  • - To find a delivery target that is configured as the default delivery option for a data collection, enter true.
  • - To find a delivery target that isn't configured as the default delivery option for a data collection, enter false.
deliveryMethodIds
Optional. Enter the system generated unique identifier of a delivery method.
For more information about how you can use an API to get the system generated unique identifier of a delivery method, see Retrieve delivery methods.
deliveryFormatIds
Optional. Enter the system generated unique identifier of a delivery format.
For more information about how you can use an API to get the system generated unique identifier of a delivery format, see Retrieve delivery formats.
createdDateFrom
Optional. To find delivery targets that were created between a date range, enter the initial date when the delivery targets were created.
To specify a date, use the YYYY-MM-DD format. The value that you specify is automatically converted and stored in the Coordinated Universal Time (UTC) time standard.
If you have specified a value for the createdDateFrom parameter, ensure that you also enter a value for the createdDateTo parameter.
createdDateTo
Optional. To find delivery targets that were created between a date range, enter the latest date when the delivery targets were created.
To specify a date, use the YYYY-MM-DD format. The value that you specify is automatically converted and stored in the Coordinated Universal Time (UTC) time standard.
If you have specified a value for the createdDateTo parameter, ensure that you also enter a value for the createdDateFrom parameter.
modifiedDateFrom
Optional. To find delivery targets that were modified between a date range, enter the initial date when the delivery targets were modified.
To specify a date, use the YYYY-MM-DD format. The value that you specify is automatically converted and stored in the Coordinated Universal Time (UTC) time standard.
If you have specified a value for the modifiedDateFrom parameter, ensure that you also enter a value for the modifiedDateTo parameter.
modifiedDateTo
Optional. To find delivery targets that were modified between a date range, enter the latest date when the delivery targets were modified.
To specify a date, use the YYYY-MM-DD format. The value that you specify is automatically converted and stored in the Coordinated Universal Time (UTC) time standard.
If you have specified a value for the modifiedDateTo parameter, ensure that you also enter a value for the modifiedDateFrom parameter.
sortByField
Optional. Specify the parameters to sort the search results.
To sort the search results, enter one of the following values:
  • - ID
  • - NAME
  • - TARGET_SYSTEM_REFERENCE
  • - STATUS
  • - CREATED_BY
  • - CREATED_ON
  • - MODIFIED_BY
  • - MODIFIED_ON
Default value is MODIFIED_ON.
sort
Optional. Set the sorting order of the search results.
Enter one of the following values:
  • - To sort the search results by ascending order, enter ASC.
  • - To sort the search results by descending order, enter DESC.
Default value is DESC.
offset
Optional. Enter the starting index for the paginated results.
Default value is 0.
limit
Optional. Enter the maximum number of results.
Default value is 50.
Maximum value is 100.
Note: The API has no payload.

Example request

The following example shows how you can use an API to retrieve the details of a delivery target:
https://{{CDMP_URL}}/api/v1/integration/provisioning/deliveryTargets?search=AWS&status=ACTIVE&sortByField=MODIFIED_BY&sort=ASC

Response

When you pass the API query parameters in the REST client, the client displays a response for the parameter values that you have entered.
The following example shows the response of an API call to retrieve the details of a delivery target:
{
"processingTime": 4190,
"offset": 0,
"limit": 50,
"totalCount": 1,
"objects": [
{
"id": "16e32a13-6fba-4f1a-a337-e0aeecf9fab4",
"refId": "Target345",
"name": "AWS-1",
"description": "Data to be made available in a CSV file hosted on AWS, this is to be sent via FTP.",
"isDefault": true,
"status": "ACTIVE",
"physicalLocation": "AWS",
"targetSystemReference": "Axon",
"deliveryTemplate": {
"id": "7f280b8a-35fb-4325-ada0-2bf5654b4891",
"refId": "Template345",
"name": "AWS",
"description": "Send an excel file via FTP",
"isDefault": true,
"status": "ACTIVE",
"managedAccess": "DISABLED",
"deliveryType": "MANUAL",
"templateOwners": [
{
"displayName": "John Doe",
"id": "9f280b8a-35fb-4325-ada0-2bf5654b4892",
"name": "username1",
"email": "abc@xyz.com",
"phone": "2020202023",
"status": "ACTIVE",
"userInfo": {
"initials": "string",
"avatarColor": "string",
"description": "string",
"title": "string",
"timeZoneId": "string"
}
}
],
"targetSystemReference": "Axon",
"defaultPhysicalLocation": "AWS",
"deliveryMethods": [
{
"id": "5wd2a13-9fha-4f1a-b317-e0vvtcf9efe4",
"refId": "Method345",
"name": "FTP",
"status": "ACTIVE",
"createdBy": "User2",
"createdOn": "2022-04-20T10:50:39.251Z",
"modifiedBy": "User1",
"modifiedOn": "2022-04-20T10:50:39.251Z"
}
],
"deliveryFormats": [
{
"id": "3h32a13-9cdf-4f1a-b317-e0ttecf9def4",
"refId": "Format345",
"name": "XSLX",
"status": "ACTIVE",
"createdBy": "User2",
"createdOn": "2022-04-20T10:50:39.251Z",
"modifiedBy": "User1",
"modifiedOn": "2022-04-20T10:50:39.251Z"
}
],
"createdBy": "User2",
"createdOn": "2022-04-20T10:50:39.251Z",
"modifiedBy": "User1",
"modifiedOn": "2022-04-20T10:50:39.251Z"
},
"deliveryMethod": {
"id": "5wd2a13-9fha-4f1a-b317-e0vvtcf9efe4",
"refId": "Method345",
"name": "FTP",
"status": "ACTIVE",
"createdBy": "User2",
"createdOn": "2022-04-20T10:50:39.251Z",
"modifiedBy": "User1",
"modifiedOn": "2022-04-20T10:50:39.251Z"
},
"deliveryFormat": {
"id": "3h32a13-9cdf-4f1a-b317-e0ttecf9def4",
"refId": "Format345",
"name": "XSLX",
"status": "ACTIVE",
"createdBy": "User2",
"createdOn": "2022-04-20T10:50:39.251Z",
"modifiedBy": "User1",
"modifiedOn": "2022-04-20T10:50:39.251Z"
},
"createdBy": "User2",
"createdOn": "2022-04-20T10:50:39.251Z",
"modifiedBy": "User1",
"modifiedOn": "2022-04-20T10:50:39.251Z"
}
]
}
The following table describes the parameters of each delivery target that is retrieved:
Parameter
Description
processingTime
Time taken (in milliseconds) to complete the API call.
offset
Starting index for the paginated results.
limit
Maximum number of results.
totalCount
Number of delivery targets retrieved.
objects
Details of the retrieved delivery target.
objects > id
System generated unique identifier of the delivery target.
objects > refId
Reference identifier of the delivery target.
objects > name
Name of the delivery target.
objects > description
Description of the delivery target.
objects > isDefault
This parameter indicates whether the delivery target is the default delivery option for a data collection. This parameter can have one of the following values:
  • - true. The delivery target is the default delivery option for a data collection.
  • - false. The delivery target isn't the default delivery option for a data collection.
objects > status
The status indicates whether the delivery target is available for use to the Data Users that order the data collection. A delivery target can have one of the following statuses:
  • - ACTIVE. The delivery target is available.
  • - INACTIVE. The delivery target is unavailable.
objects > physicalLocation
The location where the data is delivered.
Note: If the value of the managedAccess parameter is ENABLED, the data won't be delivered to the location that is specified in the physicalLocation parameter. Instead, the data will be delivered to a location that is generated at the time of order fulfillment. The generated location is unique to each order that is fulfilled using this target.
For more information, see the Manage access to data with Data Access Management topic in the Set Up Data Marketplace help.
objects > targetSystemReference
System where the data was delivered.
objects > deliveryTemplate > id
System generated unique identifier of the delivery template that was used to create the delivery target.
objects > deliveryTemplate > refId
Reference identifier of the delivery template.
objects > deliveryTemplate > name
Name of the delivery template.
objects > deliveryTemplate > description
Description of the delivery template.
objects > deliveryTemplate > isDefault
This parameter indicates whether or not the delivery template is set as the default delivery option for your Data Marketplace instance. The parameter can have one of the following values:
  • - true. The delivery template is the default delivery option.
  • - false. The delivery target isn't the default delivery option.
objects > deliveryTemplate > status
The status indicates whether the delivery template is available to be used to create a delivery target of a data collection. A delivery template can have one of the following statuses:
  • - ACTIVE. The delivery template is available.
  • - INACTIVE. The delivery template is unavailable.
objects > deliveryTemplate > managedAccess
This parameter determines whether a unique data location is created for each order that is fulfilled using a target that is based on this template. This parameter can have one of the following values:
  • - ENABLED. A unique data location is created for each order that is fulfilled using a target that is based on this template. Furthermore, an access management application such as Data Access Management might customize the delivered data based on the characteristics of the data, the Data User and the usage context that they specified in the order.
  • - DISABLED. The same data is made available in a data location that is common to all Data Users.
For more information, see the Manage access to data with Data Access Management topic in the Set Up Data Marketplace help.
objects > deliveryTemplate > deliveryType
The type of delivery. A delivery template can have one of the following types:
  • - AUTOMATIC. The order approval and fulfillment is automated.
  • - MANUAL, a stakeholder of the data collection must approve and fulfill the order manually.
objects > deliveryTemplate > templateOwners
Details of the Delivery Owner that is responsible for the delivery template.
objects > deliveryTemplate > targetSystemReference
Target system or resource reference from where the data is obtained.
objects > deliveryTemplate > defaultPhysicalLocation
The default delivery location.
objects > deliveryTemplate > deliveryMethods
Details of the delivery method of the delivery template.
objects > deliveryTemplate > deliveryFormats
Details of the delivery format of the delivery template.
objects > deliveryTemplate > createdBy
System generated unique identifier of the user account that created the delivery template.
objects > deliveryTemplate > createdOn
Date when the delivery template was created.
objects > deliveryTemplate > modifiedBy
System generated unique identifier of the latest user account that modified the delivery template.
objects > deliveryTemplate > modifiedOn
Latest date when the delivery template was modified.
objects > deliveryMethod > id
System generated unique identifier of the delivery method.
objects > deliveryMethod > refId
Reference identifier of the delivery method.
objects > deliveryMethod > name
Name of the delivery method.
objects > deliveryMethod > status
The status indicates whether a delivery method is available to be added to delivery templates. A delivery method can have one of the following statuses:
  • - ACTIVE. The delivery method is available.
  • - INACTIVE. The delivery method is not available.
objects > deliveryMethod > createdBy
System generated unique identifier of the user account that created the delivery method.
objects > deliveryMethod > createdOn
Date when the delivery method was created.
objects > deliveryMethod > modifiedBy
System generated unique identifier of the latest user account that modified the delivery method.
objects > deliveryMethod > modifiedOn
Latest date when the delivery method was modified.
objects > deliveryFormat > id
System generated unique identifier of the delivery format.
objects > deliveryFormat > refId
Reference identifier of the delivery format.
objects > deliveryFormat > name
Name of the delivery format.
objects > deliveryFormat > status
The status indicates whether a delivery format is available to be added to delivery templates. A delivery format can have one of the following statuses:
  • - ACTIVE. The delivery format is available.
  • - INACTIVE. The delivery format is not available.
objects > deliveryFormat > createdBy
System generated unique identifier of the user account that created the delivery format.
objects > deliveryFormat > createdOn
Date when the delivery format was created.
objects > deliveryFormat > modifiedBy
System generated unique identifier of the latest user account that modified the delivery format.
objects > deliveryFormat > modifiedOn
Latest date when the delivery format was modified.
objects > createdBy
System generated unique identifier of the user account that created the delivery target.
objects > createdOn
Date when the delivery target was created.
objects > modifiedBy
System generated unique identifier of the latest user account that modified the delivery target.
objects > modifiedOn
Latest date when the delivery target was modified.

Modify delivery targets

Use a REST API to modify delivery targets inData Marketplace.

Endpoint and method

The following table describes the connection properties for the API:
Property
Description
Endpoint
/api/v1/integration/provisioning/deliveryTargets
Method
PUT

Request

The following table describes the parameters that you enter in the body of the API payload:
Parameter
Description
Additional Information
id
Required. Enter the system generated unique identifier of the delivery target that you want to modify.
For more information about how you can use an API to get the system generated unique identifier of a delivery target, see Retrieve delivery targets.
refId
Optional. Enter a reference identifier for the delivery target.
If you don't specify a reference identifier, Data Marketplace automatically assigns a unique value to the object. 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.
name
Required. Enter a name for the delivery target.
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 delivery target as "Excel over ipfs" while a delivery target called "Excel over IPFS" already exists, the API call fails.
description
Required. Enter a description for the delivery target.
-
status
Required. Specify a status for the delivery target. The status determines whether the delivery target is available for use to the Data Users that order the data collection.
Enter one of the following values:
  • - To make the delivery targets available, enter ACTIVE.
  • - To make the delivery targets unavailable, enter INACTIVE.
targetSystemReference
Optional. Enter the target system or resource reference from where the data is obtained..
-
physicalLocation
Optional. Enter the location where the data is delivered to a Data User.
-
deliveryMethodId
Required. Enter the system generated unique identifier of the delivery method.
For more information about how you can use an API to get the unique identifier of a delivery method, see Retrieve delivery methods.
deliveryFormatId
Required. Enter the system generated unique identifier of the delivery format.
For more information about how you can use an API to get the system generated unique identifier of a delivery format, see Retrieve delivery formats.

Example request

The following example shows how you can use an API to modify a delivery target:
{
"items": [
{
"id": "13c937c3-e6d8-3006-a530-f3cd6ecf2a8f",
"refId": "Target561",
"name": "Customer DB",
"description": "Customer DB Delivery updated",
"status": "ACTIVE",
"targetSystemReference": "AXON",
"physicalLocation": "Oracle db ",
"deliveryMethodId": "c35181e7-7832-3b5c-b0d3-fc2360a82f05",
"deliveryFormatId": "fe4e89ab-80e9-3e0d-8aba-71b79deab4b8"
}
]
}

Response

When you pass the API payload in the REST client, the client displays a response for the parameter values that you have entered.
The following example shows the response of an API call to modify a delivery target:
{
"processingTime": 4483,
"objects": [
{
"index": 1,
"id": "13c937c3-e6d8-3006-a530-f3cd6ecf2a8f",
"refId": "Target561",
"name": "Customer DB"
}
]
}
The following table describes the parameters of each delivery target that is modified:
Parameter
Description
index
The position of the delivery target in the objects JSON array. This value does not impact how the delivery target is used by a Data Marketplace user.
id
System generated unique identifier of the delivery target.
refId
Reference identifier of the delivery target.
name
Name of the delivery target.