Workflow Frontend

Workflow is the Guardian's content tracking system, part of the Digital CMS. It allows editorial staff to track content through the production pipeline, from commission to publication.

This repository contains the frontend app and its Scala API layer, whilst the backend apps are in a separate repository: workflow.

Contents

• Introduction
• Getting Started
• How It Works
• Useful Links
• Terminology

1. Introduction

Workflow is used by Guardian editorial staff to manage content in production. Content is represented as "stubs" which are typically analogous to content in Composer and are often linked together. However, stubs can also represent other forms of content such as media atoms.

This repository contains the frontend app as well as its own backend (Scala API layer) which interacts with the workflow backend app: Datastore.

Frontend features:

• Dashboard — a filterable, real-time view of all content in production, with status tracking, assignees, priorities, and due dates.
• Content/stub management — create and update content stubs, including metadata such as section, legal status, commissioned length, production office, and planned publication details (newspaper book, page, and digital publication date).
• Admin interface — manage editorial desks, sections, and section-to-desk mappings (restricted via the Permissions service).
• Editorial support teams — manage and view the status of editorial support staff.
• Presence indicators — see who else is viewing the same content in real time.

2. Getting Started

Prerequisites

• Java 11
• Node
• sbt
• AWS credentials: workflow and capi (API Gateway invocation) profiles from Janus

Workflow Frontend needs to talk to Workflow Datastore and Preferences. It can use either a local backend or the CODE environment.

Setup

1. Run the setup script:

   ./scripts/setup.sh

2. Download the DEV config:

   ./scripts/fetch-config.sh

If you encounter a Module build failed error due to Node Sass during setup, run npm rebuild node-sass.

Setup for local development container

You may choose to work on the code within an isolated containerised environment, which requires an IDE that supports development container. We added support for it using devenv. Note that mise is used for tool version management in the development container built by devenv.

VScode

1. Open the project with VSCode. You may reference this doc if you encounter any errors.

2. Switch to development container when prompted. You can also use the command "Dev Containers: Reopen in container" in VSCode.

3. Launch into the user configuration for a fully personalized development environment, or the shared configuration for a standard project setup.

4. Open a terminal within the IDE so that we can run command line in the container.

5. Load the AWS credentials.

6. Download the local container config:

   ./scripts/fetch-config.sh

IntelliJ

1. Follow the "clone-outside-container section of this doc to open the project in IntelliJ using development container. It requires a more recent version of IntelliJ (for example, 2026). If it returned an error that Docker wasn't running, you may change the settings in IntelliJ to look for the right socket location.

2. Open a terminal within the IDE so that we can run command line in the container.

3. Run mise reshim to update the paths to run tools managed by mise.

4. Load the AWS credentials.

5. Download the local container config:

   ./scripts/fetch-config.sh

Connecting to Datastore

CODE

Create an SSH tunnel to a workflow-frontend CODE instance. You will need ssm-scala installed.

./scripts/setup-ssh-tunnel.sh

Local backend

Alternatively, set up the workflow backend locally and verify it is running:

curl -is http://localhost:9095/management/healthcheck

Running

./scripts/start.sh

Certain features require running other services locally, e.g. run atom-workshop locally to test creating Chart atoms through Workflow.

Note: when running Workflow Frontend locally, some functionality will currently not work.

• Connect to CAPI
• Presence
• 'Assign to me'

Deploying

This project uses continuous deployment on the main branch. Merging to main triggers a build and deploy via RiffRaff. If you suspect your change hasn't deployed, look for the Editorial Tools::Workflow::Workflow Frontend project in RiffRaff.

Admin Permissions

The /admin path allows management of desks and sections. Access is controlled by the Permissions service — not all Workflow users have admin access.

3. How It Works

This project holds the user interface for Workflow, consisting of an AngularJS based client and a Scala Play backend.

AngularJS client

The AngularJS client is located in the public directory, more detail can be found in the README.

Scala Play backend

The Scala Play backend is responsible for serving the client assets. It also provides a REST API for interacting with Workflow data. This includes the CRUD capabilities for stubs, along with various admin functions.

The backend proxies client requests to the Datastore app. Requests are authenticated using Panda auth which are then directed to backend services using machine-to-machine authentication. For more detail on the backend apps see the Workflow repository.

Configuration for workflow-frontend is stored in S3. For the location of the configuration files, see the editorial-tools-platform repository.

Presence

The client uses a WebSocket connection with Presence to display user interactions with content in real-time. The client provides a list of subscriptions for content it is interested in receiving updates for. When users open the content in a browser or interact with certain parts of the UI, updates are sent across the WebSocket connection, then used to update the dashboard UI.

4. Useful Links

Related projects

• Workflow backend — The data layer and core business logic for Workflow.
• Presence — A real-time service showing which users are currently viewing or editing content.
• Preferences - A service to store and retrieve user preferences across editorial tools. Workflow frontend uses it to store a user's chosen filter options.
• Composer – The main content authoring tool, content is expected to be tracked in Workflow
• Atom Workshop – The tool used for authoring certain kinds of atoms, which may be tracked via Workflow
• Media Atom Maker – The tool for authoring media atoms, which may be tracked via Workflow
• CAPI – The main API for Guardian digital content. CAPI is called when displaying content detail in the UI
• Flexible Octopus Converter – Writes events to the Octopus Thrift stream, which Prole consumes
• Pan-Domain Authentication — The authentication library used across Guardian tools
• editorial-tools-platform – Infrastructure and CloudFormation templates
• editorial-tools-support – Runbooks and support documentation

5. Terminology

• Stub — a content item being tracked in Workflow. A stub represents a story in production and carries metadata such as status, assignee, section, priority, and due date. A stub may or may not have a corresponding piece of content in Composer.
• Desk — an editorial team or department (e.g. "News", "Sport"). Desks own sections and are used to filter the dashboard.
• Section — an editorial section within a desk (e.g. "UK News", "Football"). Content is assigned to a section.
• Production Office — the geographical office responsible for a piece of content (e.g. UK, US, AU).