Import Entries
Table of Contents
Overview
This job enables you to import entries into Codex. This removes the need for manual data entry, ensuring consistent adherence to our defined schema.
JSON Schema
Before using the entries import job, understanding the JSON schema that defines the structure of entries in Codex is crucial. This schema serves as a blueprint for creating valid JSON entries. Here's a glimpse of the expected schema:
{
"id": "string",
"system": {
"status": 1,
"firstPublishedAt": "2023-08-22T14:19:35.811Z",
"publishedAt": "2023-08-22T14:19:35.811Z",
"unpublishedAt": "2023-08-22T14:19:35.811Z",
"createdAt": "2023-08-22T14:19:35.811Z",
"updatedAt": "2023-08-22T14:19:35.811Z",
"versionId": "string",
"labels": [
{
"id": "string"
}
],
"metrics": {
"wordCount": 0,
"characterCount": 0,
"sentenceCount": 0,
"imageCount": 0,
"readingTime": 0
},
"slug": "string"
},
"content": {
"text_field_alias": "string_value",
"number_field_alias": 123,
"boolean_field_alias": true,
"url_field_alias": "/url/",
"section_field_alias": [
{
"id": "sectionId1",
"isMain": true
},
{
"id": "sectionId2",
"isMain": false
}
],
"media_field_alias":{
"id": "string",
"url": "asset",
"type": 1
},
"rich_content_field_alias":[
{
"type": "string",
"contentHTML": "",
"content": [
{
"type": "text",
"text": "string",
"marks": [],
"attrs": {}
}
],
"text": null,
"marks": [],
"attrs": {
"align": "left",
"blockId": "string",
"dropCap": false
}
}
]
},
"attrs": {
"additionalProp1": "string",
"additionalProp2": "string",
"additionalProp3": "string"
}
}
JSON Schema Explanation
The JSON schema outlines the structure of entries to be imported using "codex.content.import." Let's explore the schema's fields:
Json Schema Requirements
Initially, the process involves retrieving the JSON file's structure to determine if it encompasses all the essential properties that define an Entry object. Subsequently, based on the content of the file, the deserialization is tailored to either yield a single Entry object or a List of Entry objects. Entries that do not meet the specified criteria are gathered into a list for further processing and reporting.
The Entry object has some fields that are always required, regardless of the Model it is based on. These fields form the basic structure of an entry, which looks like this:
[
{
"id": "string", // a unique identifier for the entry
"system": {
"modelAlias":"string", // the alias of the Model that defines the entry's structure and validation rules
"siteId":"string" // the site to which the entry belongs; the site ID must be valid according to codex standards
},
"content": {}, // a list of key/value pairs that assign values to the fields of the Model
"attrs": {}, // a list of key/value pairs that store additional attributes for the entry.
"references":[] // a list of other entries or entities in codex that are linked to this entry
}
]
The id property is the same as the externalId of an existing Entry, which is a unique identifier that you can use to access or update the entry later. The modelAlias property tells you which Model the entry is based on, so it should match the alias of one of the existing and published Models.
When you create a new entry, the status property is automatically set to Draft, which means the entry is not published yet and only visible to you and other authorized users.
id (string)
An external unique identifier for the entry. This distinguishes each entry and is crucial for referencing and retrieval. It serves as the System.ExternalId and can be a UUID, string, or other formats you prefer. This field is mandatory for all entries.
system (object)
This object holds metadata and system-related information about the entry.
status(enum): Represents the entry's status (published, deleted, draft, unpublished, archived, scheduled, or edited). If the status isn't defined, it defaults to "draft."firstPublishedAt(datetime): DateTime for the first publication of the entry.publishedAt(datetime): DateTime for the last publication or scheduled publication of the entry.unpublishedAt(datetime): DateTime for unpublishing or scheduled unpublishing of the entry.createdBy(string): The User ID or API Key ID as it is in Codex. If not provided, a default value is assigned.createdAt(datetime): Creation DateTime. If not provided, it's set to the current UTC time.updatedBy(string): User ID or API Key ID of the last updater as it is in Codex. If not provided, a default value is assigned.updatedAt(datetime): DateTime of the last update. If not provided, it's set to the current UTC time.labels(array of objects): Label objects associated with the entry.id(string): Unique Codex identifier for each label.
metrics(object): Metrics related to the entry.wordCount(integer): Number of words in the content.characterCount(integer): Number of characters in the content.sentenceCount(integer): Number of sentences in the content.imageCount(integer): Number of images in the content.readingTime(integer): Estimated reading time in minutes.
slug(string): Human-readable URL-friendly identifier for the entry. If not provided:- If the model uses
titlefor slug generation,titleis used. Otherwise, - It's resolved from the
contentfield configured in the model.
- If the model uses
content (object)
Actual content of the entry. Keys and values vary based on model configuration. The key is the alias of the field in the Model, and the value is a value or object that matches the type of the field.
For example, suppose you have a Model with these fields:
{
...
"Fields": [
{
"_t": "TextField",
"Type": 1,
"Alias": "title",
"Description": "",
"ValueType": 1,
"HelpText": "",
"Validation": {...
},
},
{
"_t": "IntegerField",
"Type": 2,
"Alias": "number",
"Description": "",
"ValueType": 1,
"HelpMessage": null,
"Validation": {...
}
},
{
"_t": "DateTimeField",
"Type": 4,
"Alias": "time",
"Description": "",
"ValueType": 1,
"HelpText": "",
"Validation": {...
},
},
{
"_t": "MediaField",
"Type": 8,
"Alias": "featuremedia",
"Description": "",
"ValueType": 1,
"Validation": {...
},
"CalculateMetrics": false
},
{
"_t": "RichTextField",
"Type": 10,
"Alias": "texteditor",
"Description": "",
"ValueType": 1,
"FormattingOption": {...
},
"Hyperlinks": {
"Url": true,
"Article": false,
"Images": true,
"Files": true
},
"Embeded": null,
"Validation": {...
},
},
{
"_t": "JsonField",
"Type": 6,
"Name": "json",
"Alias": "json",
"Description": "",
"ValueType": 1,
"Validation": {...
}
},
{
"_t": "BooleanField",
"Type": 5,
"Alias": "gender",
"Description": "",
"ValueType": 1,
"Validation": {...
}
},
{
"_t": "LocationField",
"Type": 9,
"Alias": "location",
"Description": "",
"ValueType": 1,
"Validation": {...
}
},
{
"_t": "ReferenceField",
"Type": 7,
"Alias": "references",
"Description": "",
"ValueType": 1,
"Validation": {...
}
},
{
"_t": "RichContentField",
"Type": 11,
"Alias": "textcontainer",
"Description": "",
"ValueType": 2,
"CalculateMetrics": false,
"Validation": {...
}
},
{
"_t": "AuthorField",
"Type": 12,
"Alias": "authors",
"Description": "",
"ValueType": 1,
"Validation": {...
}
},
{
"_t": "TagField",
"Type": 13,
"Alias": "tags",
"Description": "",
"ValueType": 2,
"Validation": {...
},
"Types": []
},
{
"_t": "SectionField",
"Type": 14,
"Alias": "sections",
"Description": "",
"ValueType": 1,
"Validation": {...
}
},
{
"_t": "UrlField",
"Type": 15,
"Alias": "url",
"Description": "",
"ValueType": 1,
"Validation": {...
},
"Pattern": "/{system.modelAlias}/{id}",
}
],
}
Setting values for them in Entry would look like this:
{
...
"Content": {
"title": "string",
"number": 0,
"time": "2023-12-25T00:00:00Z",
"featuremedia": {
"id": "string",
"type": 1,
"caption": "sfsdfsd",
"focalPoints": {
"default": {
"x": 0.5,
"y": 0.5
}
}
},
"texteditor": "<p>string</p>",
"json": {},
"gender": true,
"location": {
"address": null,
"latitude": "42.588841300287434",
"longitude": "21.12399644778058"
},
"references": null,
"textcontainer": [
{
"type": "paragraph",
"text": null,
"marks": [],
"content": [
{
"type": "text",
"text": "string",
"marks": [],
"content": null,
"attrs": {},
"contentHTML": null
}
],
"attrs": {
"align": "left",
"blockId": "bl7c61626bf1844249919a",
"dropCap": false
},
"contentHTML": "string"
}
],
"authors": {
"id": "string"
},
"tags": [
{
"id": null,
"tag": "string",
"alias": "string",
"externalId": null,
"source": 0
}
],
"sections": {
"id": "string",
"isMain": true
},
"url": "/{modelAlias}/{id}"
},
attrs (object)
Additional attributes for the entry. Similar to content, keys and values can vary based on use case.
Customize field names and descriptions based on your system's schema. Replace placeholder field names with actual ones from your import.
All DateTime fields must have a UTC time zone.
Usage
JSON file can contain a list of entries for creation or update.
Inserting an Entry
When creating an entry, structure JSON with a unique ID not created/imported in codex.
Example:
{
"id": "unique-entry-externalID-to-be-created",
"system": {
"status": 3, // Draft status
// ... other fields
},
"content": {
"title": "Getting Started with Codex",
"content": "This guide explains how to get started with our Codex platform.",
// ... other content-related fields
},
"attrs": {
// ... additional attributes
}
}
Updating an Entry
For updating, provide valid "id" (entry external ID) corresponding to existing entry. Changes apply to existing entry.
Example:
{
"id": "unique-entry-externalID-to-be-updated",
"system": {
"status": 3, // Draft status
// ... other fields to update
},
"content": {
"title": "Updated Codex Guide",
"content": "This guide has been updated with new information.",
// ... other updated content-related fields
},
"attrs": {
// ... updated additional attributes
}
}
Valid "id" and updated information modify existing entry.
Customize provided examples for your entry/update needs.
Referencing an Entry
Link to other entries via unique identifiers in the Reference field. Useful for relationships within codex.
Reference an entry in the Reference (content) field in two ways:
EntryIdequals the JSON file "id" field.EntryIdequals Codex ID of existing entry.
Reference schema for Reference field:
{
"Model": "string",
"EntryId": "string"
}
Validation
When the JSON file contains entries with the status of published or scheduled, they undergo validation similar to how entries are processed by the web app.
Validation in published & scheduled statuses
The following validations apply only to entries with the status of published or scheduled:
System level Validations
- All model fields should exist within the Entry.Content property, ensuring their values conform to the specified field types.
- Slug must match a string that consists of only allowed characters, which can be either a lowercase letter from a to z or a digit from 0 to 9. The string must also be between 1 and 500 characters long and must be unique among all entries.
- The VersionId property must be a valid Codex version ID.
- The title property must not be null or empty.
- Metrics properties must all be non-negative integers.
- Every reference within an entry to another entity (such as Author, Section, Url, Media, Entry, Label, Tag) must be accessible and existing(e.g., the MediaField must match an existing media object).
Field specific validations
Validation occurs based on the settings configured for each field. Even if the "Required" validation isn't initially set to true, certain fields may become Required depending on other field's conditions.
Url Field
- Requires a unique URL, which must point to a relative or absolute URL and cannot contain spaces, certain characters (e.g., '&', backslashes), or any characters outside a predefined set.
- May include pattern matching, be marked as required, or be set as read-only.
Text Field
- Can be set as required, read-only, unique, or limited in character count.
- May involve pattern matching or prohibiting specific patterns.
- with special considerations if it's the title field.
Tag Field
- May be required, read-only, and limited in the number of tags allowed.
- Tags must be unique within their field if field type is list.
Section Field
- Can be required, read-only, and may have restrictions on parent/child selection.
- The number of sections may be limited.
Rich Content Field
- Specifies allowed types (e.g., Toolbar, Textual, Embeds, Newsroom, Others & Content) and may be set as read-only or required.
- Requires valid references matching allowed types in content or media.
Rich Text
- May be Limited by character count, and may be required or read-only.
Reference Field
- Prohibits self-referencing and may be required, read-only, or restricted by allowed entry types or number of references.
Number Field
- Can be required, read-only, unique, and limited by allowed values or a range of numbers.
Media Field
- May be required and read-only, with required metadata and dimensional ranges for image types.
- Specifying labels of assets enables the validation to check for medias with selected labels
- May restrict the number or type of assets allowed.
Json Field
- Can be required and read-only, with limitations on the number of properties allowed.
DateTime Field
- Can be required and read-only, with validation based on a specified date range.
Author Field
- May be required, read-only, and limited in the number of authors allowed.
These validation rules ensure the integrity and consistency of data within entries, with each field type subject to specific constraints and requirements.
Logging
Import process yields logging messages including:
| Message | Description |
|---|---|
Downloading entries | Entry download initiation. |
#N entries downloaded | Number of entries from JSON. |
X% of entries preprocessed | Percentage preprocessed every 10% of total entries. |
X% of entry references preprocessed | Preprocessed entry references for each 10%. |
Validating entries | Validation start for published/scheduled entries. |
Imported {noOfTotalEntries} entries from file {request.FileId} for organization {request.Organization} with task id {request.JobTaskId} | Imported entry summary. |
Valid entries: {noOfValidEntries}, Invalid entries: {noOfInvalidEntries} | Valid and invalid entry counts. |
Created: {noOfEntriesCreated}, Updated: {noOfEntriesUpdated} | New and updated entry counts. |
Entries with status {status}: {count} | Entry counts for each status. |
Task completed | Process completion. |
Model with alias {modelAlias} not found | Invalid entry with missing entry.System.ModelAlias. |
Entry {ID} is invalid: {validationErrorMessage} | Validation errors for entry with provided ID. |
These messages offer insights into successful entry import.