# Editorial Concepts This page explains the editorial domain concepts behind the Kordiam API. Understanding these concepts helps you map API resources to real Kordiam editorial workflows. Use this page for domain context. The [Resource Model](/docs/getting-started/data-model) page covers the technical resource model, and the [API reference](/api) is the source of truth for exact contracts. ## Stories and Events In Kordiam, an **Element** is the top-level editorial planning item. Depending on its contents, it can represent: - A **story**: an editorial piece planned for one or more publication channels - An **event**: a real-world happening (press conference, sports match, election day) - Both at the same time: a story that covers a specific event - A group-based planning entry or task-only assignment Story-like elements carry a description (slug), a title, notes, and optional event data such as date, time, and location. The API resource `Element` maps to this top-level concept. ## Tasks A **Task** is a work assignment within a story. Each task represents a deliverable that someone needs to produce: an article, a photo, a video, an audio piece, or another organization-specific deliverable. ### Task Formats Every task has a **format** (also called task type) that determines its nature and available options. The public API exposes built-in format type codes for text, picture, video, audio, and other. Organizations can still name and configure their task formats to match local workflows. Format metadata exposes the **task statuses** configured for that format. Public REST task writes validate `statusId` against the statuses active for the organization. For the exact resource and reference-data mapping, see [Resource Model](/docs/getting-started/data-model#statuses). ### Task Lifecycle Tasks follow a status-driven workflow. A typical progression: ``` Requested → Offered → Received → Edited → Approved ``` Task format metadata may expose different workflow stages for different formats, such as text and video. Administrators configure these per organization. Tasks expose a **done** state. Public REST writes change it through the dedicated done-state operation; root task create, replace, and patch payloads do not infer done-state changes from other task fields. ### Task Confirmation Tasks support a **confirmation workflow** where the assignee can confirm or reject the assignment. In API payloads, this is represented through `confirmationStatusCode`: | Code | Meaning | |------|---------| | `-2` | Confirmation not requested | | `-1` | Rejected by assignee | | `0` | Confirmation requested, awaiting response | | `1` | Confirmed by assignee | Task create and replace payloads must send `confirmationStatusCode` where the schema requires it. Do not rely on user type to provide an implicit public API default. ### Task Cost Tracking Tasks can carry cost data for tracking editorial assignment expenses. In the API, the `cost` object on task payloads includes `amount` and `currency`. Omitting `cost`, or sending it as `null`, creates a task without cost unless the endpoint schema says otherwise. ### Text Length Text-type tasks can specify a **text length requirement**: a predefined option that indicates the expected word count or length category. Text length options are defined per task format and referenced by `optionId` in the API. ## Publications A **Publication** represents a scheduled or published output of a story on a specific platform. A single story can have multiple publications across different channels. Each publication belongs to exactly one **Platform** and can optionally have a **Category** and a **Type** (both defined within that platform). ### Task-Publication Links Tasks and publications can be linked to each other within the same story. - A task may contribute to one publication or to several publications. - A publication may depend on one task or on several tasks. - The link answers a practical planning question: which assignments contribute to which output. In the API, this link is always explicit rather than inferred automatically. For the exact payload shapes and `localId` rules, see [Task-Publication Linking](/docs/guides/editorial-workflows/task-publication-linking). ### Publication Scheduling Publications can be: - **Undated**: no schedule assigned yet - **Single-dated**: scheduled for one specific date, optionally with a time or time slot - **Recurring**: repeating on a daily (weekday-based) or manual (issue-based) schedule For details on the scheduling API, see [Publication Scheduling](/docs/guides/editorial-workflows/publication-scheduling). ### Time Slots Platforms can define **time slots**: named time ranges for scheduling publications. For example, a digital platform might have "Morning" (6:00-9:00), "Noon" (11:00-13:00), and "Evening" (18:00-21:00) slots. Platform responses expose each slot with `id`, `name`, `start`, and `end`. Publication schedules reference an existing slot by `timeSlotId` in the schedule `timing` object. For v1-to-v2 platform schedule and time-slot migration notes, see [Platform Schedule Configuration Migration](/docs/migration-from-v1/platform-schedule-configuration). ### Publication CMS Data When a publication is connected to a content management system, the `cms` object on the publication carries integration data: - `cms.articleId`: the publication's identifier in the CMS - `cms.publishedLink`: a link object for the public-facing published content - `cms.editLink`: a link object for opening the content in the CMS editorial UI This data model supports CMS integrations where Kordiam and an external CMS exchange article references. ## Statuses Kordiam uses **three independent status systems** that operate at different levels of the editorial model. Available statuses are configured per organization and, for tasks and publications, further scoped by format or platform. This section explains what each status system means in the Kordiam editorial workflow. For the exact reference endpoints and field names, see [Resource Model](/docs/getting-started/data-model#statuses). ### Element Status Applies to the entire story or event, regardless of how many tasks or publications it has. Commonly used for: - **Editorial decision-making**: moving stories through a pitch-to-publish pipeline (e.g., Proposed → Accepted → In Progress → Ready) - **Priority flagging**: marking important stories for filtering ### Publication Status Applies per publication. One story with three publications can have three different statuses. Used for: - **Platform-specific decisions**: which channels will run the story - **Production tracking**: from proposal through editing to publication Each platform can define which publication statuses are relevant to it, including a default that product workflows may preselect. Public REST write defaults are defined by the endpoint schemas. ### Task Status Tracks the workflow stage of individual tasks (e.g., Requested → Received → Approved). Task-format metadata can expose different status lists for different formats, while public task writes validate `statusId` against the organization's active task statuses. ## Custom Fields Custom fields extend the data model with organization-specific attributes on stories, tasks, and publications. They are split into **definitions** (what fields exist) and **values** (what data a specific story, task, or publication carries). The public write model supports text, single selection, multiple selection, date, and number values. Some internal definition types are intentionally hidden from public definition reads and are not writable through the public API. ### Scoping Custom fields can be scoped to: - **Elements**: story- or event-level metadata - **Tasks**: assignment-specific metadata, optionally limited to selected task formats - **Publications**: output-specific metadata, optionally limited to selected platforms For the exact resource split between field definitions, field options, and stored values, see [Resource Model](/docs/getting-started/data-model#custom-fields). ## Platforms and Categories ### Platforms A **Platform** represents a publication channel such as a website, print newspaper, mobile app, newsletter, or social media account. Each platform can define its own: - **Categories**: content sections (Politics, Sports, Culture) - **Subcategories**: nested sections within categories - **Types**: content formats (Article, Interview, Opinion, Review) - **Time slots**: named scheduling windows - **Publication statuses**: which statuses are relevant for this channel ### Categories Categories organize content within a platform and support **one level of nesting**: a category can have subcategories, but subcategories cannot have their own children. ## Groups **Groups** are organizational units such as editorial desks, departments, or teams. They help express: - Which users belong to which organizational unit - Which stories are relevant to which department - Platform and category access relationships Groups can reference a parent group. User responses can include the groups a user works for. In practice, groups help express editorial ownership, desk responsibility, and access boundaries. ## Users Users in Kordiam fall into two categories: | User type | Description | |-----------|-------------| | **Internal** | Staff members with full or scoped access | | **External** | Freelancers and contractors | Users can also carry additional identifiers for system integration: - `supplierId` - `externalId` Both identifiers are optional and depend on the organization's integration setup; the public schema does not assign them different meanings by user type. ## Shifts and Absences **Shifts** define recurring work schedules (e.g., "Early Morning Shift", "Night Desk"). Each shift has a weekly schedule, start/end times, time zone, and an availability code indicating whether assigned users are available for additional work. **Absences** are user availability exceptions such as vacation, business trips, days off, and short-work periods. ## Related Pages - [Resource Model](/docs/getting-started/data-model): technical resource model and ERD diagrams - [Write Semantics](/docs/guides/api-conventions/write-semantics): how `POST`, `PUT`, `PATCH`, and `DELETE` behave - [Task-Publication Linking](/docs/guides/editorial-workflows/task-publication-linking): linking rules and `localId` usage - [Publication Scheduling](/docs/guides/editorial-workflows/publication-scheduling): schedule subresource API - [Publishing Publications](/docs/guides/editorial-workflows/publishing-publications): publish lifecycle operation