DocumentationExperience PlatformDestinations Guide

Update destination dataflows using the Flow Service API

Last update: Fri Jan 19 2024 00:00:00 GMT+0000 (Coordinated Universal Time)

CREATED FOR:

  • Developer
  • User
  • Admin
  • Leader

This tutorial covers the steps for updating a destination dataflow. Learn how to enable or disable the dataflow, update its basic information, or add and remove audiences and attributes using the Flow Service API. For information on editing destination dataflows using the Experience Platform UI, read Edit activation flows.

Getting started get-started

This tutorial requires you to have a valid flow ID. If you do not have a valid flow ID, select your destination of choice from the destinations catalog and follow the steps outlined to connect to the destination and activate data before attempting this tutorial.

NOTE
The terms flow and dataflow are used interchangeably in this tutorial. In the context of this tutorial, the have the same meaning.

This tutorial also requires you to have a working understanding of the following components of Adobe Experience Platform:

  • Destinations: Destinations are pre-built integrations with destination platforms that allow for the seamless activation of data from Adobe Experience Platform. You can use destinations to activate your known and unknown data for cross-channel marketing campaigns, email campaigns, targeted advertising, and many other use cases.
  • Sandboxes: Experience Platform provides virtual sandboxes which partition a single Platform instance into separate virtual environments to help develop and evolve digital experience applications.

The following sections provide additional information that you will need to know in order to successfully update your dataflow using the Flow Service API.

Reading sample API calls reading-sample-api-calls

This tutorial provides example API calls to demonstrate how to format your requests. These include paths, required headers, and properly formatted request payloads. Sample JSON returned in API responses is also provided. For information on the conventions used in documentation for sample API calls, see the section on how to read example API calls in the Experience Platform troubleshooting guide.

Gather values for required headers gather-values-for-required-headers

In order to make calls to Platform APIs, you must first complete the authentication tutorial. Completing the authentication tutorial provides the values for each of the required headers in all Experience Platform API calls, as shown below:

  • Authorization: Bearer {ACCESS_TOKEN}
  • x-api-key: {API_KEY}
  • x-gw-ims-org-id: {ORG_ID}

All resources in Experience Platform, including those belonging to Flow Service, are isolated to specific virtual sandboxes. All requests to Platform APIs require a header that specifies the name of the sandbox the operation will take place in:

  • x-sandbox-name: {SANDBOX_NAME}
NOTE
If the x-sandbox-name header is not specified, requests are resolved under the prod sandbox.

All requests that contain a payload (POST, PUT, PATCH) require an additional media type header:

  • Content-Type: application/json

Look up dataflow details look-up-dataflow-details

The first step in updating your destination dataflow is to retrieve dataflow details using your flow ID. You can view the current details of an existing dataflow by making a GET request to the /flows endpoint.

API format

GET /flows/{FLOW_ID}
Parameter
Description
{FLOW_ID}
The unique id value for the destination dataflow you want to retrieve.

Request

The following request retrieves information regarding your flow ID.

curl -X GET \
    'https://platform.adobe.io/data/foundation/flowservice/flows/226fb2e1-db69-4760-b67e-9e671e05abfc' \
    -H 'Authorization: Bearer {ACCESS_TOKEN}' \
    -H 'x-api-key: {API_KEY}' \
    -H 'x-gw-ims-org-id: {ORG_ID}' \
    -H 'x-sandbox-name: {SANDBOX_NAME}'

Response

A successful response returns the current details of your dataflow including its version, unique identifier (id), and other relevant information.

{
   "items":[
      {
         "id":"226fb2e1-db69-4760-b67e-9e671e05abfc",
         "createdAt":"{CREATED_AT}",
         "updatedAt":"{UPDATED_BY}",
         "createdBy":"{CREATED_BY}",
         "updatedBy":"{UPDATED_BY}",
         "createdClient":"{CREATED_CLIENT}",
         "updatedClient":"{UPDATED_CLIENT}",
         "sandboxId":"{SANDBOX_ID}",
         "sandboxName":"prod",
         "imsOrgId":"{ORG_ID}",
         "name":"2021 winter campaign",
         "description":"ACME company holiday campaign for high fidelity customers",
         "flowSpec":{
            "id":"71471eba-b620-49e4-90fd-23f1fa0174d8",
            "version":"1.0"
         },
         "state":"enabled",
         "version":"\"8b0351ca-0000-0200-0000-61c4d6700000\"",
         "etag":"\"8b0351ca-0000-0200-0000-61c4d6700000\"",
         "sourceConnectionIds":[
            "5e45582a-5336-4ea1-9ec9-d0004a9f344a"
         ],
         "targetConnectionIds":[
            "8ce3dc63-3766-4220-9f61-51d2f8f14618"
         ],
         "inheritedAttributes":{
            "sourceConnections":[
               {
                  "id":"5e45582a-5336-4ea1-9ec9-d0004a9f344a",
                  "connectionSpec":{
                     "id":"8a9c3494-9708-43d7-ae3f-cda01e5030e1",
                     "version":"1.0"
                  },
                  "baseConnection":{
                     "id":"0a82f29f-b457-47f7-bb30-33856e2ae5aa",
                     "connectionSpec":{
                        "id":"8a9c3494-9708-43d7-ae3f-cda01e5030e1",
                        "version":"1.0"
                     }
                  },
                  "typeInfo":{
                     "type":"ProfileFragments",
                     "id":"ups"
                  }
               }
            ],
            "targetConnections":[
               {
                  "id":"8ce3dc63-3766-4220-9f61-51d2f8f14618",
                  "connectionSpec":{
                     "id":"0b23e41a-cb4a-4321-a78f-3b654f5d7d97",
                     "version":"1.0"
                  },
                  "baseConnection":{
                     "id":"7fbf542b-83ed-498f-8838-8fde0c4d4d69",
                     "connectionSpec":{
                        "id":"0b23e41a-cb4a-4321-a78f-3b654f5d7d97",
                        "version":"1.0"
                     }
                  }
               }
            ]
         },
         "transformations":[
            {
               "name":"GeneralTransform",
               "params":{
                  "profileSelectors":{
                     "selectors":[
                        {
                           "type":"JSON_PATH",
                           "value":{
                              "path":"Email",
                              "operator":"EXISTS",
                              "identity":{
                                 "namespace":"Email"
                              },
                              "mapping":{
                                 "sourceType":"text/x.schema-path",
                                 "source":"Email",
                                 "destination":"Email",
                                 "identity":false,
                                 "primaryIdentity":false,
                                 "functionVersion":0,
                                 "copyModeMapping":false,
                                 "sourceAttribute":"Email",
                                 "destinationXdmPath":"Email"
                              }
                           }
                        },
                        {
                           "type":"JSON_PATH",
                           "value":{
                              "path":"person.name.firstName",
                              "operator":"EXISTS",
                              "mapping":{
                                 "sourceType":"text/x.schema-path",
                                 "source":"person.name.firstName",
                                 "destination":"person.name.firstName",
                                 "identity":false,
                                 "primaryIdentity":false,
                                 "functionVersion":0,
                                 "copyModeMapping":false,
                                 "sourceAttribute":"person.name.firstName",
                                 "destinationXdmPath":"person.name.firstName"
                              }
                           }
                        },
                        {
                           "type":"JSON_PATH",
                           "value":{
                              "path":"person.name.lastName",
                              "operator":"EXISTS",
                              "mapping":{
                                 "sourceType":"text/x.schema-path",
                                 "source":"person.name.lastName",
                                 "destination":"person.name.lastName",
                                 "identity":false,
                                 "primaryIdentity":false,
                                 "functionVersion":0,
                                 "copyModeMapping":false,
                                 "sourceAttribute":"person.name.lastName",
                                 "destinationXdmPath":"person.name.lastName"
                              }
                           }
                        },
                        {
                           "type":"JSON_PATH",
                           "value":{
                              "path":"personalEmail.address",
                              "operator":"EXISTS",
                              "mapping":{
                                 "sourceType":"text/x.schema-path",
                                 "source":"personalEmail.address",
                                 "destination":"personalEmail.address",
                                 "identity":false,
                                 "primaryIdentity":false,
                                 "functionVersion":0,
                                 "copyModeMapping":false,
                                 "sourceAttribute":"personalEmail.address",
                                 "destinationXdmPath":"personalEmail.address"
                              }
                           }
                        },
                        {
                           "type":"JSON_PATH",
                           "value":{
                              "path":"segmentMembership.status",
                              "operator":"EXISTS",
                              "mapping":{
                                 "sourceType":"text/x.schema-path",
                                 "source":"segmentMembership.status",
                                 "destination":"segmentMembership.status",
                                 "identity":false,
                                 "primaryIdentity":false,
                                 "functionVersion":0,
                                 "copyModeMapping":false,
                                 "sourceAttribute":"segmentMembership.status",
                                 "destinationXdmPath":"segmentMembership.status"
                              }
                           }
                        }
                     ],
                     "mandatoryFields":[
                        "Email",
                        "person.name.firstName",
                        "person.name.lastName"
                     ],
                     "primaryFields":[
                        {
                           "identityNamespace":"Email",
                           "fieldType":"IDENTITY"
                        }
                     ]
                  },
                  "segmentSelectors":{
                     "selectors":[
                        {
                           "type":"PLATFORM_SEGMENT",
                           "value":{
                              "id":"9f7d37fd-7039-4454-94ef-2b0cd6c3206a",
                              "name":"Interested in Mountain Biking",
                              "filenameTemplate":"%DESTINATION_NAME%_%SEGMENT_ID%_%DATETIME(YYYYMMdd_HHmmss)%",
                              "exportMode":"DAILY_FULL_EXPORT",
                              "schedule":{
                                 "frequency":"ONCE",
                                 "startDate":"2021-12-25",
                                 "startTime":"20:00"
                              },
                              "createTime":"1640289901",
                              "updateTime":"1640289901"
                           }
                        },
                        {
                           "type":"PLATFORM_SEGMENT",
                           "value":{
                              "id":"f52a3785-2e7c-40a7-8137-9be99af7794e",
                              "name":"Birth year 1970",
                              "filenameTemplate":"%DESTINATION_NAME%_%SEGMENT_ID%_%DATETIME(YYYYMMdd_HHmmss)%",
                              "exportMode":"DAILY_FULL_EXPORT",
                              "schedule":{
                                 "frequency":"DAILY",
                                 "startDate":"2021-12-23",
                                 "endDate":"2021-12-31",
                                 "startTime":"20:00"
                              },
                              "createTime":"1640289901",
                              "updateTime":"1640289901"
                           }
                        },
                        {
                           "type":"PLATFORM_SEGMENT",
                           "value":{
                              "id":"6caa79b9-39e0-4c37-892b-5061cdca2377",
                              "name":"Account Leads",
                              "filenameTemplate":"%DESTINATION_NAME%_%SEGMENT_ID%_%DATETIME(YYYYMMdd_HHmmss)%",
                              "exportMode":"FIRST_FULL_THEN_INCREMENTAL",
                              "schedule":{
                                 "frequency":"DAILY",
                                 "startDate":"2021-12-23",
                                 "endDate":"2021-12-31",
                                 "startTime":"20:00"
                              },
                              "createTime":"1640289901",
                              "updateTime":"1640289901"
                           }
                        },
                        {
                           "type":"PLATFORM_SEGMENT",
                           "value":{
                              "id":"4c41c318-9e8c-4a4f-b880-877cdd629fc7",
                              "name":"Batch export for autumn campaign",
                              "filenameTemplate":"%DESTINATION_NAME%_%SEGMENT_ID%_%DATETIME(YYYYMMdd_HHmmss)%",
                              "exportMode":"FIRST_FULL_THEN_INCREMENTAL",
                              "schedule":{
                                 "frequency":"EVERY_6_HOURS",
                                 "startDate":"2022-01-05",
                                 "endDate":"2022-12-30",
                                 "startTime":"20:00"
                              },
                              "createTime":"1640289901",
                              "updateTime":"1640289901"
                           }
                        }
                     ]
                  }
               }
            }
         ]
      }
   ]

Update dataflow name and description update-dataflow

To update your dataflow’s name and description, perform a PATCH request to the Flow Service API while providing your flow ID, version, and the new values you want to use.

IMPORTANT
The If-Match header is required when making a PATCH request. The value for this header is the unique version of the dataflow you want to update. The etag value updates with every successful update of a dataflow.

API format

PATCH /flows/{FLOW_ID}

Request

The following request updates your dataflow’s name and description.

curl -X PATCH \
    'https://platform.adobe.io/data/foundation/flowservice/flows/226fb2e1-db69-4760-b67e-9e671e05abfc' \
    -H 'Authorization: Bearer {ACCESS_TOKEN}' \
    -H 'x-api-key: {API_KEY}' \
    -H 'x-gw-ims-org-id: {ORG_ID}' \
    -H 'x-sandbox-name: {SANDBOX_NAME}'
    -H 'If-Match: "1a0037e4-0000-0200-0000-602e06f60000"' \
    -d '[
            {
                "op": "replace",
                "path": "/name",
                "value": "2021/2022 winter campaign"
            },
            {
                "op": "replace",
                "path": "/description",
                "value": "ACME company holiday campaign for high fidelity customers and prospects"
            }
        ]'
Property
Description
op
The operation call used to define the action needed to update the dataflow. Operations include: add, replace, and remove.
path
Defines the part of the flow that is to be updated.
value
The new value you want to update your parameter with.

Response

A successful response returns your flow ID and an updated etag. You can verify the update by making a GET request to the Flow Service API, while providing your flow ID.

{
    "id": "2edc08ac-4df5-4fe6-936f-81a19ce92f5c",
    "etag": "\"50014cc8-0000-0200-0000-6036eb720000\""
}

Enable or disable dataflow enable-disable-dataflow

When enabled, a dataflow exports profiles to the destination. Dataflows are enabled by default, but can be disabled to pause the profile exports.

You can enable or disable an existing destination dataflow by making a POST request to the Flow Service API and providing state that you want to update the flow to.

API format

POST /flows/{FLOW_ID}/action?op=enable or disable

Request

The following request updates your dataflow’s state to enabled.

curl -X POST \
    'https://platform.adobe.io/data/foundation/flowservice/flows/226fb2e1-db69-4760-b67e-9e671e05abfc/action?op=enable' \
    -H 'Authorization: Bearer {ACCESS_TOKEN}' \
    -H 'x-api-key: {API_KEY}' \
    -H 'x-gw-ims-org-id: {ORG_ID}' \
    -H 'x-sandbox-name: {SANDBOX_NAME}'

The following request updates your dataflow’s state to disabled.

curl -X POST \
    'https://platform.adobe.io/data/foundation/flowservice/flows/226fb2e1-db69-4760-b67e-9e671e05abfc/action?op=disable' \
    -H 'Authorization: Bearer {ACCESS_TOKEN}' \
    -H 'x-api-key: {API_KEY}' \
    -H 'x-gw-ims-org-id: {ORG_ID}' \
    -H 'x-sandbox-name: {SANDBOX_NAME}'

Response

A successful response returns your flow ID and an updated etag. You can verify the update by making a GET request to the Flow Service API, while providing your flow ID.

{
    "id": "2edc08ac-4df5-4fe6-936f-81a19ce92f5c",
    "etag": "\"50014cc8-0000-0200-0000-6036eb720000\""
}

Add an audience to a dataflow add-segment

To add an audience to the destination dataflow, perform a PATCH request to the Flow Service API while providing your flow ID, version, and the audience you want to add.

API format

PATCH /flows/{FLOW_ID}

Request

The following request adds a new audience to an existing destination dataflow.

curl -X PATCH \
    'https://platform.adobe.io/data/foundation/flowservice/flows/226fb2e1-db69-4760-b67e-9e671e05abfc' \
    -H 'Authorization: Bearer {ACCESS_TOKEN}' \
    -H 'x-api-key: {API_KEY}' \
    -H 'x-gw-ims-org-id: {ORG_ID}' \
    -H 'x-sandbox-name: {SANDBOX_NAME}'
    -H 'If-Match: "1a0037e4-0000-0200-0000-602e06f60000"' \
    -d '[
   {
      "op":"add",
      "path":"/transformations/0/params/segmentSelectors/selectors/-",
      "value":{
         "type":"PLATFORM_SEGMENT",
         "value":{
            "id":"2d79d0d8-724f-49fc-a09d-d1dec338c93c",
            "name":"Winter 2021/2022 campaign",
            "filenameTemplate":"%DESTINATION_NAME%_%SEGMENT_ID%_%SEGMENT_NAME%_%DATETIME(YYYYMMdd_HHmmss)%_custom-text",
            "exportMode":"DAILY_FULL_EXPORT",
            "schedule":{
               "startDate":"2022-01-05",
               "frequency":"DAILY",
               "triggerType": "AFTER_SEGMENT_EVAL",
               "endDate":"2022-03-10"
            }
         }
      }
   }
]'
Property
Description
op
The operation call used to define the action needed to update the dataflow. Operations include: add, replace, and remove. To add an audience to a dataflow, use the add operation.
path
Defines the part of the flow that is to be updated. When adding an audience to a dataflow, use the path specified in the example.
value
The new value you want to update your parameter with.
id
Specify the ID of the audience you are adding to the destination dataflow.
name
(Optional). Specify the name of the audience you are adding to the destination dataflow. Note that this field is not mandatory and you can successfully add an audience to the destination dataflow without providing its name.
filenameTemplate

For batch destinations only. This field is required only when adding an audience to a dataflow in batch file export destinations like Amazon S3, SFTP, or Azure Blob.
This field determines the file name format of the files that are exported to your destination.
The following options are available:

  • %DESTINATION_NAME%: Mandatory. The exported files contain the destination name.
  • %SEGMENT_ID%: Mandatory. The exported files contain the ID of the exported audience.
  • %SEGMENT_NAME%: (Optional). The exported files contain the name of the exported audience.
  • DATETIME(YYYYMMdd_HHmmss) or %TIMESTAMP%: (Optional). Select one of these two options for your files to include the time when they are generated by Experience Platform.
  • custom-text: (Optional). Replace this placeholder with any custom text that you would like to append at the end of your file names.

For more information about configuring file names, refer to the configure file names section in the batch destinations activation tutorial.

exportMode
For batch destinations only. This field is required only when adding an audience to a dataflow in batch file export destinations like Amazon S3, SFTP, or Azure Blob.
Mandatory. Select "DAILY_FULL_EXPORT" or "FIRST_FULL_THEN_INCREMENTAL". For more information about the two options, refer to export full files and export incremental files in the batch destinations activation tutorial.
startDate
Select the date when the audience should start exporting profiles to your destination.
frequency

For batch destinations only. This field is required only when adding an audience to a dataflow in batch file export destinations like Amazon S3, SFTP, or Azure Blob.
Mandatory.

  • For the "DAILY_FULL_EXPORT" export mode, you can select ONCE or DAILY.
  • For the "FIRST_FULL_THEN_INCREMENTAL" export mode, you can select "DAILY", "EVERY_3_HOURS", "EVERY_6_HOURS", "EVERY_8_HOURS", "EVERY_12_HOURS".
triggerType

For batch destinations only. This field is required only when selecting the "DAILY_FULL_EXPORT" mode in the frequency selector.
Mandatory.

  • Select "AFTER_SEGMENT_EVAL" to have the activation job run immediately after the daily Platform batch segmentation job completes. This ensures that when the activation job runs, the most up-to-date profiles are exported to your destination.
  • Select "SCHEDULED" to have the activation job run at a fixed time. This ensures that Experience Platform profile data is exported at the same time each day, but the profiles you export may not be the most up-to-date, depending on whether the batch segmentation job has completed before the activation job starts. When selecting this option, you must also add a startTime to indicate at which time in UTC the daily exports should occur.
endDate
For batch destinations only. This field is required only when adding an audience to a dataflow in batch file export destinations like Amazon S3, SFTP, or Azure Blob.
Not applicable when selecting "exportMode":"DAILY_FULL_EXPORT" and "frequency":"ONCE".
Sets the date when audience members stop being exported to the destination.
startTime
For batch destinations only. This field is required only when adding an audience to a dataflow in batch file export destinations like Amazon S3, SFTP, or Azure Blob.
Mandatory. Select the time when files containing members of the audience should be generated and exported to your destination.

Response

A successful response returns your flow ID and an updated etag. You can verify the update by making a GET request to the Flow Service API, while providing your flow ID.

{
    "id": "2edc08ac-4df5-4fe6-936f-81a19ce92f5c",
    "etag": "\"50014cc8-0000-0200-0000-6036eb720000\""
}

Remove an audience from a dataflow remove-segment

To remove an audience from an existing destination dataflow, perform a PATCH request to the Flow Service API while providing your flow ID, version, and the index selector of the audience you want to remove. Indexing starts at 0. For example, the sample request further below removes the first and second audiences from the dataflow.

API format

PATCH /flows/{FLOW_ID}

Request

The following request removes two audiences from an existing destination dataflow.

curl -X PATCH \
    'https://platform.adobe.io/data/foundation/flowservice/flows/226fb2e1-db69-4760-b67e-9e671e05abfc' \
    -H 'Authorization: Bearer {ACCESS_TOKEN}' \
    -H 'x-api-key: {API_KEY}' \
    -H 'x-gw-ims-org-id: {ORG_ID}' \
    -H 'x-sandbox-name: {SANDBOX_NAME}'
    -H 'If-Match: "1a0037e4-0000-0200-0000-602e06f60000"' \
    -d '[
{
   "op":"remove",
   "path":"/transformations/0/params/segmentSelectors/selectors/0",
   "value":{
      "type":"PLATFORM_SEGMENT",
      "value":{
      }
   }
},
{
   "op":"remove",
   "path":"/transformations/0/params/segmentSelectors/selectors/1",
   "value":{
      "type":"PLATFORM_SEGMENT",
      "value":{
      }
   }
}
]'
Property
Description
op
The operation call used to define the action needed to update the dataflow. Operations include: add, replace, and remove. To remove an audience from a dataflow, use the remove operation.
path
Specifies which existing audience should be removed from the destination dataflow, based on the index of the audience selector. To retrieve the order of audiences in a dataflow, perform a GET call to the /flows endpoint and inspect the transformations.segmentSelectors property. To delete the first audience in the dataflow, use "path":"/transformations/0/params/segmentSelectors/selectors/0".

Response

A successful response returns your flow ID and an updated etag. You can verify the update by making a GET request to the Flow Service API, while providing your flow ID.

{
    "id": "2edc08ac-4df5-4fe6-936f-81a19ce92f5c",
    "etag": "\"50014cc8-0000-0200-0000-6036eb720000\""
}

Update components of an audience in a dataflow update-segment

You can update components of an audience in an existing destination dataflow. For example, you can change the export frequency or you can edit the file name template. To do this, perform a PATCH request to the Flow Service API while providing your flow ID, version, and the index selector of the audience you want to update. Indexing starts at 0. For example, the request below updates the ninth audience in a dataflow.

API format

PATCH /flows/{FLOW_ID}

Request

When updating an audience in an existing destination dataflow, you should first perform a GET operation to retrieve the details of the audience you want to update. Then, provide all the audience information in the payload, not just the fields that you want to update. In the example below, custom text is added at the end of the file name template and the export schedule frequency is updated from 6 hours to 12 hours.

curl -X PATCH \
    'https://platform.adobe.io/data/foundation/flowservice/flows/226fb2e1-db69-4760-b67e-9e671e05abfc' \
    -H 'Authorization: Bearer {ACCESS_TOKEN}' \
    -H 'x-api-key: {API_KEY}' \
    -H 'x-gw-ims-org-id: {ORG_ID}' \
    -H 'x-sandbox-name: {SANDBOX_NAME}'
    -H 'If-Match: "1a0037e4-0000-0200-0000-602e06f60000"' \
    -d '[
   {
      "op":"replace",
      "path":"/transformations/0/params/segmentSelectors/selectors/8",
      "value":{
         "type":"PLATFORM_SEGMENT",
         "value":{
            "id":"4c41c318-9e8c-4a4f-b880-877cdd629fc7",
            "name":"Batch export for autumn campaign",
            "filenameTemplate":"%DESTINATION_NAME%_%SEGMENT_ID%_%DATETIME(YYYYMMdd_HHmmss)%_custom-text",
            "exportMode":"FIRST_FULL_THEN_INCREMENTAL",
            "schedule":{
               "frequency":"EVERY_12_HOURS",
               "startDate":"2022-01-05",
               "endDate":"2022-01-30",
               "startTime":"20:00"
            },
            "createTime":"1640289901",
            "updateTime":"1640289901"
         }
      }
   }
]'

For descriptions of the properties in the payload, refer to the section Add an audience to a dataflow.

Response

A successful response returns your flow ID and an updated etag. You can verify the update by making a GET request to the Flow Service API, while providing your flow ID.

{
    "id": "2edc08ac-4df5-4fe6-936f-81a19ce92f5c",
    "etag": "\"50014cc8-0000-0200-0000-6036eb720000\""
}

See the examples below for more examples of audience components that you can update in a dataflow.

Update the export mode of an audience from scheduled to after audience evaluation update-export-mode

Click to see an example where an audience export is updated from being activated every day at a specified time to being activated every day after the Platform batch segmentation job completes.

The audience is exported every day at 16:00 UTC.

code language-json 

{
  "type": "PLATFORM_SEGMENT",
  "value": {
    "id": "b1e50e8e-a6e2-420d-99e8-a80deda2082f",
    "name": "12JAN22-AEP-NA-NTC-90D-MW",
    "filenameTemplate": "%DESTINATION_NAME%_%SEGMENT_ID%_%DATETIME(YYYYMMdd_HHmmss)%",
    "exportMode": "DAILY_FULL_EXPORT"
    "schedule": {
      "frequency": "DAILY",
      "triggerType": "SCHEDULED",
      "startDate": "2022-01-13",
      "endDate": "2023-01-13",
      "startTime":"16:00"
    },
    "createTime": "1642041770",
    "updateTime": "1642615573"
  }
}

The audience is exported every day after the daily batch segmentation job completes.

code language-json 

{
  "type": "PLATFORM_SEGMENT",
  "value": {
    "id": "b1e50e8e-a6e2-420d-99e8-a80deda2082f",
    "name": "12JAN22-AEP-NA-NTC-90D-MW",
    "filenameTemplate": "%DESTINATION_NAME%_%SEGMENT_ID%_%DATETIME(YYYYMMdd_HHmmss)%",
    "exportMode": "DAILY_FULL_EXPORT"
    "schedule": {
      "frequency": "DAILY",
      "triggerType": "AFTER_SEGMENT_EVAL",
      "startDate": "2022-01-13",
      "endDate": "2023-01-13"
    },
    "createTime": "1642041770",
    "updateTime": "1642615573"
  }
}

Update the file name template to include additional fields in the file name update-filename-template

Click to see an example where the file name template is updated to include additional fields in the file name

The exported files contain the destination name and Experience Platform audience ID

code language-json 

{
  "type": "PLATFORM_SEGMENT",
  "value": {
    "id": "b1e50e8e-a6e2-420d-99e8-a80deda2082f",
    "name": "12JAN22-AEP-NA-NTC-90D-MW",
    "filenameTemplate": "%DESTINATION_NAME%_%SEGMENT_ID%",
    "exportMode": "DAILY_FULL_EXPORT"
    "schedule": {
      "frequency": "DAILY",
      "triggerType": "SCHEDULED",
      "startDate": "2022-01-13",
      "endDate": "2023-01-13",
      "startTime":"16:00"
    },
    "createTime": "1642041770",
    "updateTime": "1642615573"
  }
}

The exported files contain the destination name, Experience Platform audience ID, the date and time when the file was generated by Experience Platform, and custom text appended at the end of the files.

code language-json 

{
  "type": "PLATFORM_SEGMENT",
  "value": {
    "id": "b1e50e8e-a6e2-420d-99e8-a80deda2082f",
    "name": "12JAN22-AEP-NA-NTC-90D-MW",
    "filenameTemplate": "%DESTINATION_NAME%_%SEGMENT_ID%_%DATETIME(YYYYMMdd_HHmmss)%_%this is custom text%",
    "exportMode": "DAILY_FULL_EXPORT"
    "schedule": {
      "frequency": "DAILY",
      "triggerType": "SCHEDULED",
      "startDate": "2022-01-13",
      "endDate": "2023-01-13",
      "startTime":"16:00"
    },
    "createTime": "1642041770",
    "updateTime": "1642615573"
  }
}

Add a profile attribute to a dataflow add-profile-attribute

To add a profile attribute to the destination dataflow, perform a PATCH request to the Flow Service API while providing your flow ID, version, and the profile attribute you want to add.

API format

PATCH /flows/{FLOW_ID}

Request

The following request adds a new profile attribute to an existing destination dataflow.

curl -X PATCH \
    'https://platform.adobe.io/data/foundation/flowservice/flows/226fb2e1-db69-4760-b67e-9e671e05abfc' \
    -H 'Authorization: Bearer {ACCESS_TOKEN}' \
    -H 'x-api-key: {API_KEY}' \
    -H 'x-gw-ims-org-id: {ORG_ID}' \
    -H 'x-sandbox-name: {SANDBOX_NAME}'
    -H 'If-Match: "1a0037e4-0000-0200-0000-602e06f60000"' \
    -d '[
    {
    "op":"add",
    "path":"/transformations/0/params/profileSelectors/selectors/-",
    "value":{
        "type":"JSON_PATH",
        "value":{
            "path":"mobilePhone.status"
        }
    }
    }
]'
Property
Description
op
The operation call used to define the action needed to update the dataflow. Operations include: add, replace, and remove. To add a profile attribute to a dataflow, use the add operation.
path
Defines the part of the flow that is to be updated. When adding a profile attribute to a dataflow, use the path specified in the example.
value.path
The value of the profile attribute that you are adding to the dataflow.

Response

A successful response returns your flow ID and an updated etag. You can verify the update by making a GET request to the Flow Service API, while providing your flow ID.

{
    "id": "2edc08ac-4df5-4fe6-936f-81a19ce92f5c",
    "etag": "\"50014cc8-0000-0200-0000-6036eb720000\""
}

Remove a profile attribute from a dataflow remove-profile-attribute

To remove a profile attribute from an existing destination dataflow, perform a PATCH request to the Flow Service API while providing your flow ID, version, and the index selector of the profile attribute you want to remove. Indexing starts at 0. For example, the sample request further below removes the fifth profile attribute from the dataflow.

API format

PATCH /flows/{FLOW_ID}

Request

The following request removes a profile attribute from an existing destination dataflow.

curl -X PATCH \
    'https://platform.adobe.io/data/foundation/flowservice/flows/226fb2e1-db69-4760-b67e-9e671e05abfc' \
    -H 'Authorization: Bearer {ACCESS_TOKEN}' \
    -H 'x-api-key: {API_KEY}' \
    -H 'x-gw-ims-org-id: {ORG_ID}' \
    -H 'x-sandbox-name: {SANDBOX_NAME}'
    -H 'If-Match: "1a0037e4-0000-0200-0000-602e06f60000"' \
    -d '[
    {
    "op":"remove",
    "path":"/transformations/0/params/profileSelectors/selectors/4",
    "value":{
        "type":"JSON_PATH",
        "value":{
            "path":"mobilePhone.status"
        }
    }
    }
]'
Property
Description
op
The operation call used to define the action needed to update the dataflow. Operations include: add, replace, and remove. To remove an audience from a dataflow, use the remove operation.
path
Specifies which existing profile attribute should be removed from the destination dataflow, based on the index of the audience selector. To retrieve the order of profile attributes in a dataflow, perform a GET call to the /flows endpoint and inspect the transformations.profileSelectors property. To delete the first audience in the dataflow, use "path":"transformations/0/params/segmentSelectors/selectors/0/".

Response

A successful response returns your flow ID and an updated etag. You can verify the update by making a GET request to the Flow Service API, while providing your flow ID.

{
    "id": "2edc08ac-4df5-4fe6-936f-81a19ce92f5c",
    "etag": "\"50014cc8-0000-0200-0000-6036eb720000\""
}

API error handling api-error-handling

The API endpoints in this tutorial follow the general Experience Platform API error message principles. Refer to API status codes and request header errors in the Platform troubleshooting guide for more information on interpreting error responses.

Next steps next-steps

By following this tutorial, you have learned how to update various components of a destination dataflow, like adding or removing audiences or profile attributes using Flow Service API. For more information on destinations, see the destinations overview.

recommendation-more-help
7f4d1967-bf93-4dba-9789-bb6b505339d6