# Migrate to Structured Data Files v8

*Last update: 2024-11-12*

This guide leads you through the process of migrating from using Structured Data
Files v7.1 to v8 and explains the changes between the two versions that may
impact your integration.

See the [release notes](https://developers.google.com/display-video/api/structured-data-file/rel-notes#version_8_beta) for an exhaustive list of differences
between v7.1 and v8.

## Migrate your Structured Data Files version

To migrate to Structured Data Files (SDFs) v8 from a previous version:

1. Update your resources and SDF generation actions to use v8.
2. Update Ad resource logic to identify a type upon creation.
3. Add new logic for reading, creating, and updating Demand Gen resources.

### Update Structured Data Files version

To use a new Structured Data Files version, update the assigned version in your
parent Partner and Advertiser resources and use the new version when creating
individual download tasks in the [Display \& Video 360 API](https://developers.google.com/display-video/api).

#### Update parent resource settings

A default Structured Data Files version is set at the partner and advertiser
resource level. This version is used as the default when downloading Structured
Data Files through the interface or API.

##### Set in the interface

**At the partner level**

1. Navigate to the intended partner.
2. Expand the **Partner settings** menu in the left-hand navigation and navigate to the **Basic details** page.
3. Update the **SDF version** configuration in the **Structured Data Files** section to **v8**.

**At the advertiser level**

1. Navigate to the intended advertiser.
2. Expand the **Advertiser settings** menu in the left-hand navigation and navigate to the **Basic details** page.
3. Update the **SDF version** configuration in the **Structured Data Files** section to **v8**. If the default version is set at the Partner level, this setting may not be editable.

##### Set in the API

At the partner level
:   You cannot set the default SDF version at the Partner level in the API.

At the advertiser level
:   Make an [`advertisers.patch`](https://developers.google.com/display-video/api/reference/rest/current/advertisers/patch) request to update the
    [`dataAccessConfig.sdfConfig.sdfConfig.version`](https://developers.google.com/display-video/api/reference/rest/current/SdfConfig#FIELDS.version) to
    `SDF_VERSION_8` and, if needed,
    [`dataAccessConfig.sdfConfig.overridePartnerSdfConfig`](https://developers.google.com/display-video/api/reference/rest/current/advertisers#AdvertiserSdfConfig.FIELDS.override_partner_sdf_config)
    to `True`.

#### Update `sdfdownloadtasks.create` requests in the API

When making a [`sdfdownloadtasks.create`](https://developers.google.com/display-video/api/reference/rest/current/sdfdownloadtasks/create) request using the
Display \& Video 360 API, set the [`version`](https://developers.google.com/display-video/api/reference/rest/current/sdfdownloadtasks/create#body.request_body.FIELDS.version) field of the
request body to `SDF_VERSION_8`.

### Specify type in Ad resources

v8 adds an `Ad Type` column to [Ad](https://developers.google.com/display-video/api/structured-data-file/v8/AdGroupAd) files, which surfaces the type of
Ad represented by each row. This new column is required and will be populated
for existing resources when downloading v8 Ad files.

When updating existing Ads, the value of this column shouldn't be changed.

When creating new Ads, you must populate this column with one of the values
listed in the column description.

### Update logic for Demand Gen resources

v8 supports the creation, retrieval, and updating of Demand Gen campaigns using
[Line Item](https://developers.google.com/display-video/api/structured-data-file/v8/LineItem), [Ad Group](https://developers.google.com/display-video/api/structured-data-file/v8/AdGroup), and [Ad](https://developers.google.com/display-video/api/structured-data-file/v8/AdGroupAd) files. Demand
Gen resources use different logic for timestamp verification, require the
population of additional columns, and are limited by new restrictions across the
three file types.

#### Timestamp verification

For all non-Demand-Gen line items, the `Timestamp` column of a [Line
Item](https://developers.google.com/display-video/api/structured-data-file/v8/LineItem) file is populated at download with the last time a line item
was modified. This value is used when updating a line item using SDF to verify
that a line item has not been updated since the original file was downloaded. If
so, the update fails.

For Demand Gen line items, the `Timestamp` column and the accompanying
verification works differently. For Demand Gen line item entries, the column is
populated with the current time at download. On upload, Display \& Video 360
checks if it has been more than 24 hours since the given timestamp. If it has
been more than 24 hours, the original file entry is considered stale and the
update fails. If this happens, download the file again and make your updates
based on the more recent version. *This new verification method does not prevent
you from overwriting changes made in the last 24 hours. To avoid accidental
overwrites, only include Demand Gen line items that you want to update in files
that you upload.*

#### Required columns

The following file types have columns that are now required for certain Demand
Gen resources, in addition to the columns that are required for all entities of
that file type.

> [!NOTE]
> **Note:** Other columns not listed here may be required when *updating* Demand Gen resources. See the v8 reference documentation for [Line Item](https://developers.google.com/display-video/api/structured-data-file/v8/LineItem), [Ad
> Group](https://developers.google.com/display-video/api/structured-data-file/v8/AdGroup), and [Ad](https://developers.google.com/display-video/api/structured-data-file/v8/AdGroupAd) file types for an exhaustive list of requirements for each column.

##### Line Item

| Required columns for the following [Line Item](https://developers.google.com/display-video/api/structured-data-file/v8/LineItem) `Type` column values ||
|---|---|
| Demand Gen | |---| | `Pacing Amount` | | `TrueView Bid Strategy Type` | | `TrueView Bid Strategy Value` | |

##### Ad

| Required columns for the following [Ad](https://developers.google.com/display-video/api/structured-data-file/v8/AdGroupAd) `Ad Type` column values ||
|---|---|
| Demand Gen Carousel | |---| | `Business Name` | | `Call to Action` | | `Demand Gen Cards` | | `Description 1` | | `Headline` | | `In-feed Video Headline` | | `Landing Page URL` | | `Logo Asset IDs` | |
| Demand Gen Image | |---| | `Business Name` | | `Call to Action` | | `Description 1` | | `Headline` | | `In-feed Video Headline` | | `Landing Page URL` | | `Logo Asset IDs` | | `Marketing Image Asset Id` | |
| Demand Gen Product | |---| | `Business Name` | | `Description 1` | | `Headline` | | `In-feed Video Headline` | | `Landing Page URL` | | `Logo Asset IDs` | |
| Demand Gen Video | |---| | `Business Name` | | `Call to Action` | | `Description 1` | | `Headline` | | `In-feed Video Headline` | | `Landing Page URL` | | `Logo Asset IDs` | | `Video Id` | |

#### Updated restrictions

In addition to the new required columns for certain Demand Gen Line Items and
Ads, multiple columns across [Line Item](https://developers.google.com/display-video/api/structured-data-file/v8/LineItem), [Ad Group](https://developers.google.com/display-video/api/structured-data-file/v8/AdGroup), and
[Ad](https://developers.google.com/display-video/api/structured-data-file/v8/AdGroupAd) file types have new use restrictions that apply to Demand Gen
resources.

These restrictions are numerous and specific to the columns in question, so this
guide doesn't provide an exhaustive list of restrictions. We recommend that you
closely read the v8 reference documentation for [Line Item](https://developers.google.com/display-video/api/structured-data-file/v8/LineItem), [Ad
Group](https://developers.google.com/display-video/api/structured-data-file/v8/AdGroup), and [Ad](https://developers.google.com/display-video/api/structured-data-file/v8/AdGroupAd) file types before creating or updating
Demand Gen resources using SDF upload.