openfn/project

A package to track, parse and serialize OpenFn project definitions.

A PROJECT is defined as a set of connected workflows with a single billing account, like a project in the app.

A single Project can be Checked Out to disk at a time, meaning its source workflows and expressions will be expanded nicely onto the file system.

A Workspace is a set of related Projects , including a Project and its associated Sandboxes, or a Project deployed to apps in multiple web domains

Structure and Artifects

openfn.yaml

project file

sort of a mix of project.yaml, state.json and config.json

This is strictly a representation of a server-side project, it's like the last-sync-state. CLI-only or offline projects do not have one.

It's also a portable representation of the project

Serializing and Parsing

The main idea of Projects is that a Project represents a set of OpenFn workflows defined in any format and present a standard JS-friendly interface to manipulate and reason about them.

The from/to serializers are designed to support the following formats:

• Projects expanded to the file system (through CLI or hand-written)
• v1 JSON state files generated by openfn pull
• v2 Project files (basically v1 state with some extra props)

Serializers and parsers also support JSON and YAML formats interchangeably.

Project & Workflow Generation

project exports utility functions to generate Projects and Workflows from a simple syntax. This is useful for testing.

Really it's a Workflow generator, but you can have it wrapped in a Project if you like.

Use it like this:

import { generateProject, generateWorkflow } from '@openfn/project'
import type { Project, Workflow } from '@openfn/project'

const proj: Project = generateProject('my-project', ['a-b b-c'])
const wfL Workflow = generateWorkflow('a-b b-c')

Project generation uses a simple string language to represent a workflow structure:

Define nodes in pairs seperated by a dash (no whitespace)

a-b # parent-child

For multiple children, define multiple pairs:

a-b
a-c

You can set properties on the workflow itself - probably the id, with @attributes

@id my-cool-workflow

You can also set properties on a node by putting comma seperated key-value pairs in brackets

a(adaptor=http)

You can use quotes to include spaces and brackets in a property value - great for expressions:

a(expression="fn(s => s)")

You can comment inside the string with #, which is a basic single-line comment

Reference:

# Comments behind hashes
@attribute-name attribute-value
parent(propName=propValue,x=y)-child
a-b # can comment here to

Use special names webhook and cron to create trigger nodes (when converting into app state, the difference between a step and a trigger becomes important).