Lightning.Collaboration.WorkflowSerializer (Lightning v2.15.0-pre5)

View Source

Serializes Lightning Workflow structs to/from Y.Doc CRDT documents.

This module handles bidirectional conversion:

These functions maintain consistent field mappings between the two formats.

Y.Doc Structure

The Y.Doc contains six top-level collections:

  • workflow (Map): Core workflow metadata (id, name, lock_version, deleted_at, concurrency, enable_job_logs)
  • jobs (Array): Array of job objects with Y.Text body field
  • edges (Array): Array of edge objects connecting jobs/triggers
  • triggers (Array): Array of trigger objects (webhook, cron, kafka)
  • positions (Map): Canvas positions for visual editor (node_id → {x, y})
  • errors (Map): Field-level validation errors (field_path → error_message)

Field Mappings

Special Type Conversions

  • Job body: Stored as Y.Text (for collaborative editing)
  • Atoms (condition_type, trigger type): Converted to/from strings
  • Nil values: Coalesced to empty strings or defaults where appropriate

Summary

Functions

deserialize_from_ydoc(doc, workflow_id)

Extracts workflow data from a Y.Doc.

serialize_to_ydoc(doc, workflow)

Writes a workflow's data into a Y.Doc.

Functions

deserialize_from_ydoc(doc, workflow_id)

@spec deserialize_from_ydoc(Yex.Doc.t(), String.t()) :: map()

Extracts workflow data from a Y.Doc.

This reads the Y.Doc structure and converts it to a map suitable for passing to Lightning.Workflows.save_workflow/2.

Parameters

  • doc: The Y.Doc to read from
  • workflow_id: The workflow ID (needed for the returned map)

Returns

  • A map with workflow data in the format expected by Workflows.save_workflow/2

serialize_to_ydoc(doc, workflow)

@spec serialize_to_ydoc(Yex.Doc.t(), Lightning.Workflows.Workflow.t()) :: Yex.Doc.t()

Writes a workflow's data into a Y.Doc.

This initializes the Y.Doc structure with:

  • workflow map: Core workflow metadata (id, name, lock_version, deleted_at, concurrency, enable_job_logs)
  • jobs array: Array of job objects
  • edges array: Array of edge objects
  • triggers array: Array of trigger objects
  • positions map: Canvas positions for visual editor

This function is a refactored version of Session.initialize_workflow_data/2 with no behavioral changes.

Parameters

  • doc: The Y.Doc to write into
  • workflow: The workflow struct to serialize

Returns

  • The doc (for chaining convenience)