Task Upload Delimited File Format

Version 3.00.02

Format Requirements

The delimited file contains UTF8 encoded text representation of rows and columns where each column is delimited by a character delimiter and each row is delimited by a new line character. It can be generated from spreadsheet applications usually in the form of .CSV (comma separated) and .TSV (tab separated) files and we support them both.

In order for such files to be valid, they must satisfy the row & column content conditions specified in this document.

First Row

First row is the signature row, and the first three columns need to contain specific information. Other cells in this row are ignored and can be used for note keeping purposes.

First cell needs to be empty

That is how we detect the delimiter in the file. It is especially important for .CSV files since some spreadsheets export with commas (‘,’) and others with semi-columns (‘;’). We support both flavors. The advantage of .TSV files might be that you can use comma or semi-column in task data like keywords.

Signature

Second cell is our signature cell. It must start with the word ‘WordApp’. This way we can detect accidental files early in the file upload.

Version Info

This cell must start with the following text ‘v3.00’. This way we can support delimited files prepared in earlier versions, or for different purposes. This version introduces domains to be uploaded along with tasks. Therefore, version 0.00 files also valid for upload. Empty rows are ignored from this point on.

Header Row

The first non-empty row defines the task data that this file contains. Each non-empty column in this row identifies the type of task data the for the same column in the following rows.

 Headers related to domain data

  • Domain Url
  • Domain Description
  • Sample Url
  • Persona
  • USP
  • Topics

Headers related to task data

  • keyword (focus)
  • keyword(x)
  • substitute (main)
  • substitute(x)
  • source url
  • target url
  • external Id
  • template name
  • template id
  • project id
  • substitute
  • price amount
  • price currency

Headers used for uploading content text along with task

  • description
  • title
  • image url(x) where x is the order of image
  • image text(x) where x is the order of image
  • video url(x) where x is the order of video
  • video text(x) where x is the order of video
  • h1(x) where x is the order of h1
  • h2(x) where x is the order of h2
  • h3(x) where x is the order of h3
  • h4(x) where x is the order of h4
  • h5(x) where x is the order of h5
  • h6(x) where x is the order of h6
  • text(x) where x is the order of text
  • list(x.y) where x is the order of list and y is the order of list item in xth list

Headers and columns rules:

  • All headers are case-insensitive.
  • Headers have to be suitable with the words above.
  • Empty headers are allowed, and ignored.
  • Empty columns are allowed, and ignored.
  • The number of columns and number of headers must be equal.
  • h7, h8,… or more are not allowed.
  • Repeated headers are not allowed.
  • x>99 will not be allowed in any of headers.
  • “template id” and “template name” cannot be filled at the same time.
  • Project ID cannot be empty, and all Project IDs must be identical within the order sheet. A user must have permission to access the project that they wish to upload an order sheet into.
  • “domain id” is mandatory, if any other domain related column is filled.
  • if substitute(x) column is filled, keyword(x) is mandatory.
  • Orders of headers are not important anymore.

Headers related to WordPress Plugin

  • WP Type
  • WP Status
  • WP Author
  • WP Template
  • WP Schedule
  • WP Category
  • WP Tags
  • WP Thumbnail MID
  • WP Thumbnail TIN
  • WP Thumbnail URL
  • WP Slug *

* feature is under development

Task Related Headers

Keyword (focus)

Keyword (focus) will represent the focus keyword.

Keyword (x)

There can be more than one sub-keyword headers, other than “keyword (focus)”. They can be indexed 1, 2, … up to 99 in parenthesis like “(x)”, respectively.

Substitute (focus)

Substitute (focus) will represent the substitute for “keyword (focus)”, subsequent keyword headers will represent the substitute of sub-keywords indexed 1, 2, … up to 99 in parenthesis like “(x)”, respectively.

Substitute (x)

There can be more than one keyword header, other than “keyword (focus)”. They can be indexed 1, 2, … up to 99, respectively.

Source Url

The source URL is associated with the source content for translation or rewrite tasks, if any.

Target Url

The target URL is associated with the content destination URL where the content goes after approval, if any. (Also known as the former keyword_url, content_url headers)

External Id

The id associated by a second party for this task if any. The external id will also be displayed in generated deliveries, which can make it possible for the clients, publishers, automated tools to process them. The word ‘external_id’ is also recognized as a valid header.

Template Name

You can specify the name of the library template to be used for this task. You can have different templates for different tasks within the same project, if the name is not given for a task, the project template will be used by default. The word ‘template_name’ is also recognized as a valid header. template_name header and template_id header cannot coexist in the same file.

Template ID

You can specify the id of the library template to be used for this task. You can have different templates for different tasks within the same project, if the id is not given for a task, the project template will be used by default. The word ‘template_id’ is also recognized as a valid header. template_id header and template_name header cannot coexist in the same file.

Project ID

You can specify the ID of the project to be used for this task. There cannot be different projects specified for different tasks within an order sheet. The system will not allow an empty Project ID for any task. Both “project id” and “project_id” are accepted as valid headers. The user wishing to upload a tsv to a project must have access permission for that project.

Substitute

There can be more than one substitute header. Each substitute header represents the substitution text that will replace the keyword header immediately preceding it. It is not necessary for any keyword header to be followed by a substitute header, only the keywords that have substitution text needs it.

Attn: Substitution within substitute text?

Each version also supports substitution within substitute text. The only supported attribute, for now, is the keyword that will be replaced. It is expected to have more supported attributes in the feature.

There is a special notation to denote attributes within substitute text. They must start with ‘#’ and must be enclosed in curly braces within the text. i.e. #{keyword} will represent the keyword attribute. For example, you can have ‘https://example.com/#{keyword}.img‘ as the substitute and if the associated keyword is ‘blue’ in the task, the text in the generated output will be replaced by ‘https://example.com/blue.img‘ wherever ‘blue’ occurs in the text.

Price Amount

This is content order price in cents. In order to process price amount, price currency should be given.

Price Currency

This is the currency code of price amount. Without this field or price amount, there is nothing to do about content order price.

Domain Related Headers

Domain Url

Domain URL identifies the domain of the task. If there exists a domain in the database with the same URL, the task will be associated with that domain and any other domain data in this row will be ignored. If however, no such domain exists, a domain will be created using the domain data on the row along with the domain URL. The task will then be associated with the newly created domain.

Domain Description

Short description of the domain. The data in this column is only used when a new domain is created, otherwise, it is ignored.

Sample Url

The sample URL of the domain. The data in this column is only used when a new domain is created, otherwise, it is ignored.

Persona

The persona of the domain. The data in this column is only used when a new domain is created, otherwise, it is ignored.

USP

Unique Selling Proposition persona of the domain. The data in this column is only used when a new domain is created, otherwise, it is ignored.

Topics

The topics associated with the domain, separated by commas. The data in this column is only used when a new domain is created, otherwise, it is ignored.

Content Upload Related Headers

Headers under this category will be used for uploading initial content along with the task. The data in the column designated by the header will be used to upload text for the corresponding template item with the same type of the header. e.g. the data in h2(1) column will be used to upload text to the first h2 template item, h2(2) column’s data will be used to upload text to the second h2 template item and so on. You do not need to specify a column for the parts of the task’s template that you will not be uploading. e.g. if you do not need to upload text for h1 parts of the template, you do not need to specify any h1 columns. Similarly, you can leave some rows of the column empty, these rows will not be used for uploading. i.e. corresponding template part will be left with default text in it, rather than empty text upload.

Text(x), H1(x), H2(x), H3(x), H4(x), H5(x), H6(x)

The data in these columns will be used to upload text for the corresponding template part with the same item type in the given number order in parenthesis.

Title, description

The data in these columns will be used to upload text for meta title and meta description parts of the template respectively.

Mandatory Headers

Generally, headers are not mandatory. This gives you the ability to upload tasks without keywords. The two exceptions are:

  • “domain id” header is mandatory if any other domain related column is filled.
  • If substitute(x) column is filled, keyword(x) is header and data are mandatory.

WordPress Plugin Related Headers

WP Type

post, page (+all registered types)

WP Status

draft, publish (+all registered types)

WP Author

username (WordPress login name)

WP Template

Template name from WordPress theme

WP Schedule

Schedule blog posts to automatically publish themselves at any time in the future.

Header value is a formatted text in server time as Year-Month-Day Hour:Minute, example: 2017-06-07 09:00

This option overrides the WP Status header with pre-defined future status.

WP Category

Category name from WordPress

WP Tags

Comma-separated tag items

WP Thumbnail URL

External Url to use as a featured image

WP Thumbnail TIN

Number, a template item sequence number from Wordapp Template to use as a featured image.

When featured image marked by WP Thumbnail TIN option, the corresponding template item will not be included in the content transfer.

Has precedence over WP Thumbnail URL header.

WP Thumbnail MID

Number, media item ID from WordPress Media Library to use a featured image.

Has precedence over WP Thumbnail URL and WP Thumbnail TIN headers.

WP Slug *

The URL friendly name of a post

* feature is under development

Data Rows

All the rows following header row contains data in the related header columns for one task per row.

Mandatory Data

  • “domain id” data is mandatory if any other domain related column is filled.
  • If substitute(x) column is filled, keyword(x) is header and data are mandatory.

Upload Behavior

For now, all the uploaded data will be appended to the task list even if the keyword or the external id exist in the project tasks. In the future we expect this behavior to be controlled with options like; erase data before upload, ignore existing keywords or external ids, overwrite existing keywords or external ids, etc.