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 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.
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.
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.
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.
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.
* feature is under development
Keyword (focus) will represent the focus keyword.
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) 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.
There can be more than one keyword header, other than “keyword (focus)”. They can be indexed 1, 2, … up to 99, respectively.
The source URL is associated with the source content for translation or rewrite tasks, if any.
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)
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.
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.
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.
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.
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.
This is content order price in cents. In order to process price amount, price currency should be given.
This is the currency code of price amount. Without this field or price amount, there is nothing to do about content order price.
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.
Short description of the domain. The data in this column is only used when a new domain is created, otherwise, it is ignored.
The sample URL of the domain. The data in this column is only used when a new domain is created, otherwise, it is ignored.
The persona of the domain. The data in this column is only used when a new domain is created, otherwise, it is ignored.
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.
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.
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.
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.
The data in these columns will be used to upload text for meta title and meta description parts of the template respectively.
Generally, headers are not mandatory. This gives you the ability to upload tasks without keywords. The two exceptions are:
post, page (+all registered types)
draft, publish (+all registered types)
username (WordPress login name)
Template name from WordPress theme
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.
Category name from WordPress
Comma-separated tag items
External Url to use as a featured image
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.
Number, media item ID from WordPress Media Library to use a featured image.
Has precedence over WP Thumbnail URL and WP Thumbnail TIN headers.
The URL friendly name of a post
* feature is under development
All the rows following header row contains data in the related header columns for one task per row.
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.
