genroc

    docs / Guides / Process definition

    Basics

    How a process is defined.

    Genroc uses *.genroc.yaml files to describe processes.

    Each process has a unique name and a version. Definitions are never deleted: when you apply a new definition different from the previous ones, it gets a new version automatically. Once a process is started, it is pinned to its current definition version, so a new version doesn't influence already running processes, unless you upgrade them.

    A process can optionally also have input, described with a subset of JSON Schema (the supported keywords are in the reference).

    The input is validated when the process starts, and properties the schema doesn't declare are dropped. Without input_schema, the input isn't checked and the process can't read it.

    Then there is a required list of tasks, which represent the executable body.

    So the skeleton looks something like this:

    name: process-name
    input_schema:
      type: object
      properties:
        user_name:
          type: string
      required: [user_name]
    
    tasks:
      - id: task1
        ...
      - id: task2
        ...

    This process would require input of an object with field user_name. Input is something that can be used inside the process.

    The tasks

    Tasks represent a unit of work that needs to be done. A process always starts with the first task in the array. Each task then needs to specify what should be the following task with a switch statement.

    The syntax allows you to use keywords next or end to go to next task or end the process. Or you can reference task by id with $ prefix.

    ...
    tasks:
      - id: task1          # this is a first task
        switch: $task2     # next task referenced by id
    
      - id: task2
        switch: next        # same as `$task3` in this case
    
      - id: task3
        switch: end         # end of the process

    The switch field is required in every task; there is no default value.

    Branching

    The switch statement can also be conditional.

    ...
    tasks:
      - id: task1
        switch:
            # condition to check the name
          - case: "input.user_name == 'Brenda'"
            goto: $only_brenda
            # the default case
          - goto: $others
    
      - id: only_brenda
        switch: end
    
      - id: others
        switch: end

    Cases are evaluated top to bottom and the first one that evaluates to true wins. The last one always needs to be a "catch-all" - without the case expression (we'll explain expressions in the next chapter).

    Your own data: x- keys

    A key starting with x- is yours. Genroc accepts it anywhere in the definition's structure, schemas included, and never reads it, so a tool that generates definitions can keep its data in them, a layout for example:

    name: process-name
    x-builder: { zoom: 2 }
    tasks:
      - id: task1
        x-position: { x: 120, y: 40 }
        switch: end

    A definition is stored as you applied it, so GET /api/definitions/{name} returns these keys too. Inside a value, such as an output or headers, an x- key is ordinary data.