> For the complete documentation index, see [llms.txt](https://docs.rubica.au/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.rubica.au/households/forms/building-a-form.md).

# Building a Form

Build your own client forms: sections and questions, rules that show or hide questions, answers that fill fields on the client's record, your colours, and a preview of exactly what the client sees.

The **Form Builder** is where you create and edit the forms you send to clients. Everything you build here is what the client sees on their form page, and what lands back in rubica when they submit it.

Open it from the **Form Builder** tab. You'll see a list of your forms. Click a form to edit it, or **+ New form** to start one.

<figure><img src="https://3555949013-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FqzoPnlIGiL5ejRdJEq5X%2Fuploads%2Fgit-blob-34c170ba30147c5cbfa86d76f7885f694347a4ba%2Fform-builder-question.png?alt=media" alt="The Form Builder with a question open"><figcaption><p>The Form Builder. Sections and questions on the left, the open question on the right. All names shown are examples.</p></figcaption></figure>

## How a form is laid out

* **Sections** group questions, such as *About you*, *Income* and *Goals*. Use **+ Add section** at the bottom of the list.
* **Questions** sit inside a section. Use **+ Question** under a section, or **AI** to draft a few questions from a short description.
* Click any question in the list to edit it. **Previous** and **Next** step through them in order.

The small markers next to each question tell you about it at a glance:

| Marker | Meaning                                                                      |
| ------ | ---------------------------------------------------------------------------- |
| **\*** | Required                                                                     |
| **If** | Only shown when a rule matches (see [Rules](#rules-show-or-hide-a-question)) |
| **⇔**  | Fills a field on the client's record (see [Fills a field](#fills-a-field))   |
| **S**  | Sensitive: never shown in full to your team, never sent outside rubica       |

## Editing a question

| Setting                | What it does                                                                                                                                                                                                                                    |
| ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Question text**      | What the client reads.                                                                                                                                                                                                                          |
| **Type**               | The kind of answer: Single Choice, Multi Choice, Yes/No, Rating, Checklist, Matrix, Text, Long Text, Number, Currency, Percent, Date, Email, Phone, Address, File Upload, Repeating Group, Ranking, Slider, or Statement (text with no answer). |
| **Required**           | The client can't move on without answering.                                                                                                                                                                                                     |
| **Sender can skip**    | Whoever sends the form can leave this question out for that client.                                                                                                                                                                             |
| **Sensitive**          | For things like a Tax File Number. The answer is masked for your team and redacted from anything sent outside rubica.                                                                                                                           |
| **Help text**          | A line under the question to guide the answer.                                                                                                                                                                                                  |
| **Image or video URL** | Shown with the question. Paste a link or use **Upload image**.                                                                                                                                                                                  |
| **Answer rules**       | Depends on the type, for example past dates only, or a minimum and maximum length.                                                                                                                                                              |

## Rules: show or hide a question

Rules make a form fit each client. A partner question only appears when the client says they have a partner, for example.

1. Open the question and click **Edit rules** (or **+ Add a rule** if it has none).
2. Choose **Show when** or **Hide when**.
3. Choose **Any of these** or **All of these**.
4. Add a condition: pick the earlier question, how to compare (equals, does not equal, greater than, less than) and the answer.
5. Click **Done**.

<figure><img src="https://3555949013-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FqzoPnlIGiL5ejRdJEq5X%2Fuploads%2Fgit-blob-a9c4520ab6a54600c9f9bc56ca76effc5e1b7a63%2Fform-builder-rules.png?alt=media" alt="The Rules window"><figcaption><p>"Your partner's full name" only shows when the client answers Yes to "Do you have a partner?"</p></figcaption></figure>

**Required only when…** in the same window makes a question required for some clients and optional for others. When a rule is set there, it decides instead of the plain Required tick.

{% hint style="info" %}
If a client answers a question and then changes an earlier answer so that question hides again, their hidden answer is ignored. It won't keep other questions showing, and it isn't treated as part of their submission. Switching back brings their answer back.
{% endhint %}

You can apply the same rules to a whole **section**: open the section and use its rules.

## Fills a field

A question can write its answer onto the client's record when the form comes back. For example, *How are you employed?* can fill the member's **Employment Status**.

1. Open the question and click **Fills a field**.
2. Under **Whose record**, choose:
   * **The member**: the person the form is for, chosen when you send it. All of their own details are listed together, such as date of birth, marital status and employment.
   * **The household**: the record the request is sent from, for household-level details only.
3. Pick the **Field**. Only fields that suit the question's type are listed. Formula and system fields are shown greyed out so you can see why they can't be used.
4. Choose what should happen:
   * **Pre-fill this question from the record when the form is sent** puts the current value in for the client to confirm. Pre-filled forms are protected by SMS verification.
   * **Review the answer against the record when the form comes back** shows you the old and new values side by side if they differ. Nothing is written until you accept it.

{% hint style="info" %}
If the member is set up under a business account rather than as a person in their own right, fields from their own account can't be filled. Rubica skips those and notes it on the form request.
{% endhint %}

<figure><img src="https://3555949013-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FqzoPnlIGiL5ejRdJEq5X%2Fuploads%2Fgit-blob-bb1bd15943875a92fee1a49d8621f6c5734c032c%2Fform-builder-fills.png?alt=media" alt="Fills a field on an employment question"><figcaption></figcaption></figure>

**When it comes back** (bottom of the list) also shows every question that fills a field, in one table.

## Form settings

Click **Form settings** at the top of the list to set the form's details:

| Setting                | What it does                                                                                                                                                                                         |
| ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Label**              | The name your team sees.                                                                                                                                                                             |
| **Title**              | The name the client sees at the top of the form.                                                                                                                                                     |
| **Status**             | Draft, Published or Archived. Only published forms can be sent.                                                                                                                                      |
| **Layout**             | **Single page** (every section on one scrolling page), **Cards** (one section at a time) or **Sidebar** (numbered sections down the side, one at a time). **Firm default** uses your firm's setting. |
| **Link expiry (days)** | How long the client's link works. Leave it blank for links that don't expire.                                                                                                                        |
| **Consent method**     | Ask the client to tick a box or sign before submitting.                                                                                                                                              |

### Colours on the client's page

Each form can use its own colours instead of your firm's.

* **Main colour** is used for buttons, links, the progress bar and the outline of a chosen answer.
* **Highlight shade** fills the answers a client picks. Keep it very light: a darker colour is ignored and a pale shade of the main colour is used instead.

Pick a colour with the swatch or type a hex code such as `#0F6E56`. The sample on the right shows how it will look to the client. **Use the firm's colours** clears both.

<figure><img src="https://3555949013-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FqzoPnlIGiL5ejRdJEq5X%2Fuploads%2Fgit-blob-21fd7c9b25f402d270383b9ae6eed78900e7a825%2Fform-builder-colours.png?alt=media" alt="Colours on the client&#x27;s page"><figcaption></figcaption></figure>

## Preview

Click **Preview** at the top of the builder to open the form exactly as a client will see it: your firm's own web address, your branding and the colours you've set, even if you haven't saved them yet.

<figure><img src="https://3555949013-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FqzoPnlIGiL5ejRdJEq5X%2Fuploads%2Fgit-blob-8966f0d31854fdc9055577eb840169199bb42c32%2Fclient-form-rule-shown.png?alt=media" alt="A form in preview"><figcaption><p>A preview. Choosing Yes shows the partner question, just as it will for a client.</p></figcaption></figure>

In a preview:

* Nothing you type is saved and the form can't be submitted.
* You can move to any section, even if required questions are empty.
* The link stops working after an hour.

Preview shows your questions as they were last saved. Save first if you want to check a change to a question.

## Saving

Click **Save** to save the form. If an action under **When it comes back** isn't finished (for example a webhook with no address), you'll be told which one before anything is saved.

## Next

* [When a Form Comes Back](/households/forms/when-a-form-comes-back.md): tasks, notifications, records, documents and webhooks that run when a client submits.
* [Creating a Form Request](/households/forms/creating-a-form-request.md): sending a form to a client.