Skip to content

Add diagram describing the mapping between Form and FormDocument objects #234

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
chao-xian wants to merge 1 commit into from
Closed

Add diagram describing the mapping between Form and FormDocument objects #234

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
74 changes: 74 additions & 0 deletions diagrams/mapping-forms-formdocuments.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,74 @@
# Form and FormDocument object mappings

## What gets turned into what?

```mermaid
graph LR
Form -- transformed into --> FormDocument
Page -- transformed into --> Step
Condition -- transformed into --> RoutingCondition
```

Forms are transformed into Pages, and Pages are transformed into Steps.

Form has a method to transform into a FormDocument called [as_form_document](https://github.com/alphagov/forms-admin/blob/main/app/models/form.rb#L147-L155).

The Page to Step transformation by [this method in the Page](https://github.com/alphagov/forms-admin/blob/main/app/models/page.rb#L94) class.

It basically puts the positional attributes such at the position and ID at the top-level of the step and the other attributes within the "data" field. We add a "type" which for now is always "question_page", but could be "question_set" in the future. This maps mainly onto Option 1 in [this RFC](https://github.com/alphagov/forms/discussions/174) from a while ago.

## How they relate

### Forms
```mermaid
graph TD
A[Form] -- has many --> B[Page]
B <-- has many and belongs to --> C[Condition]
D[Routing Condition] -- is a --> C
E[Check Condition] -- is a --> C
F[Goto Condition] -- is a --> C
G[Routing Page] -- is a --> B
H[Check Page] -- is a --> B
I[Goto Page] -- is a --> B
D -- points to --> G
E -- points to --> H
G -- points to --> I
```
Copy link
Copy Markdown
Contributor

@stephencdaly stephencdaly Oct 13, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't think this diagram makes a whole lot of sense. There isn't such a thing as a "check condition" or a "goto condition" really. We just have those associations on the page model to get all conditions where the check_page_id or goto_page_id point to the current page as it's sometimes useful to get these. If we want to explain how conditions relate to pages, I think the following is a better way to comprehend it:

The below diagram shows a primary condition (not sure whether we have a better name for these), which skips to Page 3 after Page 1 if the answer given to the selection question on Page 1 matches the answer_value of the condition. For primary conditions, the routing_page_id is always equal to the check_page_id.

flowchart TD
    Form[Form]
    Page1[Page 1]
    Page2[Page 2]
    Page3[Page 3]
    Condition[Condition]

    Page1 --> Form
    Page2 --> Form
    Page3 --> Form
    Condition -->|routing_page_id|Page1
    Condition -->|check_page_id|Page1
    Condition -->|goto_page_id|Page3
Loading

We can also have secondary skip conditions. These cause page(s) to be skipped later on in the form if any answer other than the answer_value was given to the question on the page that the check_page_id references. In this example if any answer other than the answer_value on the primary condition was answered, the user will proceed to Page 2. After answering the question on Page 2, Page 3 will be skipped and they will proceed to Page 4.

flowchart TD
    Form[Form]
    Page1[Page 1]
    Page2[Page 2]
    Page3[Page 3]
    Page4[Page 4]
    Condition[Secondary skip condition]

    Page1 --> Form
    Page2 --> Form
    Page3 --> Form
    Page4 --> Form
    Condition -->|check_page_id|Page1
    Condition -->|routing_page_id|Page2
    Condition -->|go_to_page_id|Page4
Loading

Copy link
Copy Markdown
Contributor Author

@chao-xian chao-xian Oct 13, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

TYSM @stephencdaly I'll update with these


### FormDocuments
```mermaid
graph TD
A[FormDocument] -- has many --> B[Steps]
B <-- has many and belongs to --> C[Routing Conditions]
C -- check_step_id --> B
C -- routing_step_id --> B
C -- goto_step_id --> B
```

A FormDocument would include the following:

```json
{
"step": {
id: 18
/* ..other steps attributes... */
"routing_conditions": [
{
"id": 3,
"check_step_id": 18,
"routing_step_id": 18,
"goto_step_id": null,
"answer_value": "Yes",
"created_at": "2024-08-02T08:54:07.479Z",
"updated_at": "2024-08-02T08:54:07.479Z",
"skip_to_end": true,
"validation_errors": []
}
]
}
}
```

The `step.id`, is the id of the step (which is a `Page` in active record but stored as `step` in the `FormDocument`).

`step.routing_conditions` contains an array of `Conditions` linked to the `step` through `routing_step_id`. `check_step_id` and `goto_step_id` are references to other `steps` in the form. These are just references, not extra conditions. All Conditions have a `routing_step_id` which links them to a `Step`.