Table of Contents:
- Exporting CSV Templates
- Modifying the Template for Import
- Importing the Modified Template
- Bulk AIP CSV Definitions
- Formatting Total Seconds & Timestamps
The Bulk AIP Update feature allows series profile users with Owner access to export, add, remove, or change Ad Insertion Point (AIP) markers across all episodes in one go. This feature is especially useful for series profiles that use dynamic ad insertion and want to either a) migrate their AIPs from a previous hosting provider, or b) edit current markers without having to manually adjusting each marker in each episode.
The Bulk AIP Update card can be found on the Series Details page of your series profile as well as on the feed pages for alternate feeds. You can either use the Series Details page card to update your Primary Feed (and any shared episodes in alternate feeds) or go to the individual alternate feed page to import feed-specific markers.
As we will illustrate in more detail in the next sections, you can use this feature to remove, add, or make the following changes to any episode AIP*:
- Position type
- Timestamp (Start position)
- Max number of ad positions
- Max duration
*This tool can only modify the AIP marker settings listed above. You cannot add or modify AIP priorities. If you modify any markers that have a custom priority, the priority will revert to All Live Reads & Spots.
*This tool also cannot be used to alter episode title or publishing status, nor delete/add any of the episodes themselves.
Exporting the Template
Exporting your template from the Bulk AIP Update feature allows you to have a current and correctly formatted CSV of all episodes and AIPs. We highly recommend you save a version of the downloaded template for all feeds in a series profile before you make bulk AIP changes, this way if you make any changes in bulk that you want to revert, you can re-upload your original template to recover your AIPs. You can also use this template to migrate AIPs into another host platform.
Primary Feed Template
Get started by navigating to your Series Details page and scrolling down to the Bulk AIP Update card. Click on the blue + button:
Next, you will select the Download a template link in the modal:
Alternate Feed Template(s)
Primary Feed episodes are linked to any alternate feed versions of the episodes by default, meaning that alternate feed episodes will also inherit the import when linked. This is another reason why downloading your alternate feed templates can be useful. We will discuss this in more detail in the Modifying the Template for Import section.
To export a template for an alternate feed, go to the Feeds section in the left-side menu of the series profile and click into the feed page you would like to export from. Scroll down to the Bulk AIP Update card and follow the same process as outline above for the Primary Feed.
Modifying the Template for Import
Now that you know where to access the Bulk AIP Import feature and how to download your CSV template, we will show you how to manage your import template for applying AIP marker changes to your episodes.
Primary Feed Imports
The CSV template export includes 10 columns (there may be more columns depending on the number of marker priorities per AIP), 5 of which are editable for the import:
- episode_id: Not Editable
- episode_guid: Not Editable
- unique_content_id: Not Editable
- episode_title: Not Editable
- release_date: Not Editable
- position_type: Editable - Accepted values for position_type are preroll, midroll, and postroll. You can have up to 7 prerolls, 7 midrolls, and 7 postrolls per episode.
- start_position: Editable - Acceptable formats are total seconds (SSSSS.00) or timestamp (HH:MM:SS.00) for specifying start position. For postrolls, you can use "end" to place the start position of the marker at the end of the episode. The downloadable template uses total seconds by default. For help formatting the start positions please see: Formatting Total Seconds & Timestamps
- max_ads: Editable - You can choose to have 1-5 maximum ads at each marker point. Please use whole numbers.
- max_duration: Editable - You can choose to have 1-900 seconds of maximum duration for each marker point. Please use whole numbers.
-
priority_1: Editable - This field allows you to configure one or many marker priorities which allow you to target specific campaigns, brands, ads, live reads, spots, or any combination. In the Bulk AIP template, there can be a priortity 1,2,3, n*. which is dependent on the number of priorities being used to target your ad content. For more information on using “priority_n” in the template reference the “Using Priorities to Target Ad Content”.
*Note: priority_n denotes any variable number of priorities used to target ad content
Please note that if you clear the marker settings cells for an episode's AIP in the sheet, it will remove the marker during import. This is described in the Removing AIPs in Bulk section below, and should be done intentionally. If you want any existing markers to remain unchanged, please leave them as they are in the export sheet.
Similarly, if you delete some marker rows for an episode and leave others in the template, then the marker rows that are deleted from the template will be deleted from the episode. However, removing all marker rows for an episode will not make any changes to the markers in the episode.
For example, if you only want to modify a midroll and the episode also has a preroll and a postroll, if you delete the preroll and postroll rows in the template and modify the midroll, the preroll and postroll markers will be deleted from the episode and the midroll will be updated. If you only want to modify the midroll and leave the preroll and postroll as they are, just leave the preroll and postroll in the template and modify the midroll.
Alternate Feed Imports
The CSV template export from an alternate feed page includes one additional editable column: inherit_from_primary. If the episode is linked to the Primary Feed this column will display a “Y” for “Yes” in the inherit_from_primary column and will inherit any changes made to the Primary Feed. If not, the field will be blank. If you want to make bulk AIP updates to episodes that are inheriting from primary, delete the Y in the inherit_from_primary field and add the marker information for position_type, start_position, max_ads, and max_duration fields. If you want to relink the alternate feed to the Primary Feed, delete the marker information for position_type, start_position, max_ads, and max_duration, and add a Y to the inherit_from_primary column.
Note: If your feed has dynamic ads disabled, no ads will be allowed to insert into the feed whether AIPs exist or not.
Adding Multiple AIPs to One Episode
Each AIP needs to be on its own row. To add an additional new AIP to an episode, simply copy and paste the episode row and add your desired AIP settings. Type is not numbered in the sheet, so even if you have more than one mid-roll in one episode, for example, each row should display midroll in the position_type column. They will be numbered according to order in the episode Warpfeed. You can add up to to 7 prerolls, 7 midrolls, and 7 postrolls per episode.
Removing AIPs in Bulk
You can also use the Bulk AIP Update feature to remove AIPs in bulk. To do this, first download the CSV template and remove all the data in the cells in the columns: position_type, start_position, max_ads, max_duration, and inherit_from_primary (for alternate feeds). Once the cells in these columns are empty, upload the CSV to remove the AIPs in bulk. Do not empty the cells for episode_id, episode_guid, unique_content_id, episode_title, and release_date.
See example below:
This is an example of what you might see when you download your AIP template. In this case there are three episodes and each episode has three AIPs:
To remove AIPs from the three episodes, empty the cells for position_type, start_position, max_ads, and max_duration, then upload the CSV.
Note: Removing an episode row from the CSV will not delete the episode itself. Only the markers can be edited.
Using Priorities to Target Ad Content
In order to target a specific campaign from the Bulk AIP Update template, you must add columns to the CSV file. If the columns are omitted, then the Bulk AIP Update tool will allow any available campaign to target the AIP.
The new columns in the template are as follows:
Note: You can add any number of priority columns as needed. ‘Priority_n’ denotes any additional priorities needed beyond 3 in this example, please note “priority_n” is not a valid field name for the Bulk AIP template.
To target specific campaigns within your template, update your priority(ies) columns with the following rules:
| Rule | Cell Value | Example |
| Any Available Campaign (Default) | campaigns/any | campaigns/any |
| Specific Campaign | campaigns/id-of-campaign | campaigns/4783d8ca-1ce0-40eb-9476-cbc2c8226aff |
| Specific Brand | brands/id-of-brand | brands/da209008-ea11-44a6-bfd7-5428f1355cd6 |
| Specific Ad | advertisements/id-of-ad | advertisements/f2d00260-244a-4bd1-91cd-43f781d48e7f |
| Live Reads Only | Live Reads | Live Reads |
| Traditional Ads Only (Spots) | Traditional Ads | Traditional Ads |
Important Note: You must specify "campaigns/any" in the next priority column if you want any available campaign to run after it has tried your specific targeting rule.
For an example of what your template might look like Targeting Specific Campaigns - see screenshot below:
Based on the Template Inputs in this Example the following Campaign Priority Results would be applied:
- In row 1, the AIP will use the default setting of All Live Reads & Spots (any available campaign)
- In row 2, the AIP will use the specific campaign, then fallback to any available campaign
- In row 3, the AIP will use the specific campaign only
- In row 4, will use the default settings which are any available campaign
Importing the Modified Template
When you have finished making changes to the template, save the file, then either select or drag and drop your updated CSV for import into the modal. The modal will then validate the upload.
In the case of any errors, the modal will identify this and not allow you to continue with the import. If this occurs, click the Download the error report to see what went wrong and what to needs to be fixed:
You can directly use the error report to fix invalid row(s) and re-upload the error report. The error field can remain during re-upload as it will not affect Bulk AIP processing. Once you have corrected the errors in the CSV, you can try the import again.
After your upload is validated, the modal will display how many episodes will be updated by this action. If all looks right, click the Confirm button:
You will then see the processing progress in the Bulk AIP Update card. Depending on how many episode you are updating, it may take several minutes, but you can navigate away from the page without interrupting the process:
You will also see when the import is complete:
Bulk AIP CSV Definitions
In the list below you will find the definitions for the columns included in your Bulk AIP Update template. The only cells you need to populate when updating your AIPs in bulk are the AIP Start Position, Max Ads, and Max Duration.
- Episode ID - This is an ART19 identifier for your episode.
- Episode GUID - The Globally Unique Identifier (GUID) is an alphanumeric identifier published to your RSS feed that never changes, even if you change hosting services.
- Unique Content ID - This is an ART19 identifier that is updated when changes are made to episode media files. It is used for ART19 to verify versions of an episode to ensure that marker placements are compatible.
- Episode Title - This is the title of your episode.
- Release Date - This is the published or scheduled date and time for the episode in UTC.
- Position Type - This is the position type for an ad insertion point. There are three position types: pre-roll, mid-roll, and post-roll.
- Inherit From Primary - AIPs in your alternate feeds that are inherited from your Primary Feed will be marked as “Y” for “Yes.” If the cells are empty, the AIP is not being inherited from your Primary Feed. Changes made on alternate feed AIPs will not be reflected back to the Primary Feed. You will only see this column when you download AIP templates from alternate feeds.
- AIP Start Position - This is the position (in seconds) where the AIP will be placed for the specified position type.
- Max Ads - This is the maximum number of ads that can run per ad insertion point.
- Max Duration - This is the maximum total seconds of ads that can play in this ad insertion marker. If there is extra time there won’t be any silence when your ad creative ends - it will always automatically return to your episode content. Ads will also not insert if the entire ad cannot fit within the maximum duration time.
- Priority_1 - This allows you to configure marker priorities within your AIP. There can be 1, 2, 3, n columns depending on the number of priorities in the AIP.
Formatting Total Seconds & Timestamps
The Bulk AIP Import tool accepts both total seconds (SSSSS.00) and timestamp (HH:MM:SS.00) format in the start_position column when importing. By default, the export CSV template uses total seconds. Here are some tips for formatting the start_position column in your CSV template:
- Formatting the timestamp into HH:MM:SS.00 in Google Drive:
- Highlight/select the cell(s) with the timestamp you want to correct
- Go to Format in the menu, go to Number, scroll down to "Custom date and time"
- In the top formatting field, select the following format:
Hour (01):Minute (01):Second (01).Millisecond (01)
- Formatting the timestamp into HH:MM:SS.00 in Excel:
- Highlight/select the cell(s) with the timestamp you want to correct
- Right click and select “Format Cells” or go to Format in the top menu and select “Cells...”
- Select “Custom” from the Category list
- Type
hh.mm.ss.00into the open Type field and select OK
- Converting from total seconds into HH:MM:SS.00:
- Highlight/select the cell(s) with total seconds you want to change
- Divide the cell by 86400
- If needed, format the cell to HH:MM:SS.00 (as shown above)
- Converting from HH:MM:SS.00 to total seconds:
- Highlight/select the cell(s) with the timestamp you want to change
- Multiply the cell by 86400
- Convert to total seconds in Google Drive:
- Go to Format in the menu, go to Number, and again select Number - Convert to total seconds in Excel:
- Right click and select “Format Cells” or go to Format in the top menu and select “Cells...”
- Select General from the category list