Skip to main content
Sign in

Search

Publisher Support

Bulk Uploading, Editing and Deleting Cohorts

  • Updated

In this article

Instructions on how to bulk upload or bulk edit cohorts to the Permutive platform

How to Bulk Upload Cohorts

Bulk uploading cohorts is a way to automatically upload 50 or more cohorts into the platform without having to build them manually.

To do so, open this Google sheet and go to 'File' > 'Make a copy' and name it with your publication.

Warning: Do not change columns, headers or file structure (ie. no columns are added, deleted or moved).  These must be exact.

Screenshot_2022-10-12_at_17.35.13.png

Example Format

Fill in the Google sheet, following the examples you can find under the 'Example Cohorts' tab.

Screenshot_2022-10-12_at_17.32.00.png

Cohorts Conditions and Modifiers

Column A
Cohort name. This needs to be a unique name and must be exactly how you want it to appear in the dashboard
Column B
Tags. You can tag your cohort with keywords to help with organising your cohorts. Please ensure multiple tags are separated by a comma.
Column C
For the first clause of the cohort, use this column to add a description to help other platform users understand the audience that you are building. For additional clauses, use this column to denote whether they should be separated by AND or OR.
Column D
This column should be used for the Event or cohort functionality (engagement or cohort transition). The Event's spelling has to be exactly as it appears in the Events tab in the dashboard, including case sensitivity.
Column E
  • If column D is an Event name (e.g. Pageview), use column E to denote the operation associated with the 'frequency': exactly, not, at least, at most, between.
  • If column D is 'engaged time', use column E to express any of the following operations associated with the number of engaged seconds: is, is not, less than, more than, less or equal to, more or equal to.
  • If column D is 'engaged completion', use column E to express any of the following operations associated with the % of completion: is, is not, less than, more than, less or equal to, more or equal to.
  • If column D is 'engaged with pageviews', use column E to denote the operation associated with the frequency: exactly, not, at least, at most.
  • If column D is 'cohort transition', use column E to choose entered or left.

Note: "Current Page" is not an accepted value for Bulk Upload at this time.

Column F
  • If column D is an Event name (e.g. Pageview), use column F to choose the Event 'frequency'.
  • If column D is 'engaged time', use column F to specify the number of seconds e.g 60.
  • If column D is 'engaged completion', use column F to specify the % of completion e.g 50.
  • If column D is 'engaged with pageviews', use column F to specify the pageview frequency.
  • If column D is 'cohort transition', use column F to specify the cohort using the cohort code.
Column G
  • If column D is an Event name (e.g. Pageview), column G should be left blank.
  • If column D is 'engaged time', column G should be left blank.
  • If column D is 'engaged completion', column G should be left blank.
  • If column D is 'engaged with pageviews', use column G to specify 'engaged time' or 'completion'.
  • If column D is 'cohort transition', column G should be left blank.
Column H
  • If column D is an Event name (e.g. Pageview), column H should be left blank.
  • If column D is 'engaged time', column H should be left blank.
  • If column D is 'engaged completion', column H should be left blank.
  • If column D is 'engaged with pageviews', use column G to choose the operation associated with time %: is, is not, less than, more than, less or equal to, more or equal to.
  • If column D is 'cohort transition', column H should be left blank.
Column I
  • If column D is an Event name (e.g. Pageview), column I should be left blank.
  • If column D is 'engaged time', column I should be left blank.
  • If column D is 'engaged completion', column I should be left blank.
  • If column D is 'engaged with pageviews', use column I to specify the number of seconds or completion % e.g 50.
  • If column D is 'cohort transition', column I should be left blank.
Column J
Time. Specify the recency of the Event or cohort functionality by the number of days.
Column K
all/any. If you're adding multiple properties, decide if you want them separated by an 'and' (all) or by an 'or' (any). 
Column L
Property 1. The property must be entered into the spreadsheet exactly as it is ingested into Permutive, eg. 'client.referrer'. You can find the correct property name in the Events Tab, by clicking on 'Quick View' of the corresponding Event and looking in the second column.

This can be any of the following property types: String, List of Strings, Integer, and Boolean. Please note that we cannot support properties where the parent property is a List of Objects.

Column M
Property operation. Decide whether the property is, is empty, contains (and their negations) specific values. It has to have exactly one value from the list.
Column N
Property value 1. Enter the values or keywords you want the property to be or contain. If entering more than one value, separate them with a comma eg. sport, football, basketball. These will be separated by 'or' in the platform.
Columns O onwards
Use these columns to add multiple properties following the same format described in columns L-N.

Bulk Edit Cohorts

To bulk edit existing cohorts, you will need to provide Technical Support with a separate CSV file that contains all of your cohort edits (see examples and CSV template at the bottom of the article). There are a couple requirements for the cohorts you want to bulk edit and the CSV that you provide.

Cohort Requirements

All the cohorts you want to bulk edit must:

1. Be Custom Cohorts (e.g. no Lookalike Cohorts).

2. Not have a Lookalike Model using it.

3. Have been created within the same workspace — please specify the workspace ID where these changes will occur your request. If you are editing cohorts across different workspaces, please provide a separate CSV for each workspace.

CSV File Requirements

The CSV file has a strict file structure, containing the following columns:

‼️ Note that the "id" column is required for all changes.

id: this should correspond to how the cohort code appears in the Permutive dashboard.

name: The new name of the cohort (please trim white space on either side). If this field is left empty, the current name will stay the same. 

description: The new cohort description. Please escape any commas by surrounding the text in quotes. If you export from a google sheet, this escaping will be done for you. If this field is empty, the current description will stay the same. 

tags: The new tags for the cohort. If uploading multiple tags, please separate the text with a "|" (pipe) symbol. If this field is empty, the current tags will stay the same.

state: The new cohort state. This field only expects two case sensitive values. Please enter either "Enabled" or "Disabled". If this field is empty, the current state will stay the same.

segment_type: The new cohort type. This field only expects two case sensitive values. Please enter either "real_time" or "offline". If this field is empty, the current cohort type will stay the same.

delete: To delete cohort, this field must equal "DELETE_ME". This is case sensitive and an exact match. If this field is empty, the cohort will not be deleted.

Flags

(+=) Append tags to current tag list: Add "+=" to the front of your tag list to append the new tags to the current list of tags. 

Examples

Updating name, description, tags, and state

id,name,description,tags,state,segment_type,delete
1234,new name,new description,newtag1|newtag2|newtag3,Enabled,,

Updating tags only

id,name,description,tags,state,segment_type,delete
123,,,newtag1|newtag2,,,
1234,,,newtagA,,,
3210,,,+=addTag,,,

Updating state only. Please note, you only have 2 options here and the capitalization is important. You can only have "Enabled" or "Disabled".


id,name,description,tags,state,segment_type,delete
123,,,,Disabled,,
1234,,,,Enabled,,

Deleting a cohort and updating another cohort's description.

id,name,description,tags,state,segment_type,delete
123,,,,,,DELETE_ME
1234,,"new description with , comma",,,,

Tip: As a best practice, please send a sample upload of ~10 cohorts to technical-services@permutive.com for alignment confirmation.

Once alignment has been confirmed, please complete the final upload and send the document to technical-services@permutive.com to be actioned.

Note: We usually expect the upload to be complete within two weeks. Please see the bottom of this article for a sample CSV file with the above columns.

If you have any questions, please contact customer support by emailing technical-services@permutive.com or chat to the Customer Operations Team via the LiveChat icon in the bottom right corner of your screen.

 

Comments

0 comments

Article is closed for comments.