# FormSG (Multi-Respondent Form) integration

{% hint style="info" %}
**Advanced Feature**

This guide covers Plumber's integration with FormSG Multi-Respondent Forms. Before proceeding, you should:

* Be comfortable using Plumber to create basic pipes
* Understand how Multi-Respondent Forms work in FormSG
* Have already set up and tested an MRF workflow in FormSG

If you're new to MRF, we recommend reading [FormSG's guide on Multi-Respondent Forms](https://guide.form.gov.sg/user-guides/multi-respondent-form-guide) first to understand workflow steps, approval fields, and respondent routing.
{% endhint %}

## What is Multi-Respondent Forms?

Multi-Respondent Forms (MRF) is a FormSG feature that allows multiple people to fill out different parts of the same form in sequence. For example, an employee submits a leave request, then their manager reviews and approves it, then HR processes it, all within a single form submission.

## MRF Integration with Plumber

When you connect an MRF form to Plumber, you can automate actions at each step of the approval process:

* Send notifications when someone submits or approves
* Update spreadsheets with the latest status
* Trigger different actions based on approval or rejection

{% hint style="info" %}
**Requirements** \
\
Before you start, make sure you have:

* A **Multirespondent FormSG form** 
* Workflow steps configured in FormSG (who fills out what, in what order)
* The form must be **published**
  {% endhint %}

## How to Connect Your MRF Form

1. Click "Choose how you want your workflow to start"
2. Select "FormSG"
3. Click "Choose connection" and add new form
4. Enter your MultiRespondent form URL and secret key
5. Click "Connect"
6. Plumber will detect that your form is a Multirespondent form

## Adding action to each step

{% hint style="info" %}
MRF forms don't always require approvers, but the example in this guide will include approval steps
{% endhint %}

Now you can add actions after each workflow step. Click the + button after any step to add an action. In this example, there are two other approvers in this workflow.

### Understanding Approval Branches

When you add an approval step to your workflow, you can set up two different paths depending on the outcome:

Each approval step shows two tabs:

#### Setting Up Your Branches

1. Click on the **If approved** tab 
2. Add the actions you want to happen when approved
3. Click on the **If rejected** tab
4. Add the actions you want to happen when rejected

<figure><img src="/files/fTknjUmE5AlFztxvaLPl" alt=""><figcaption></figcaption></figure>

<figure><img src="/files/kKbva7UJnVFlaErbm2e6" alt=""><figcaption></figcaption></figure>

**"If Rejected" is currently selected**, the **Third Submission step is greyed out and will not run**. The automation is essentially **blocked at Step 2**<sub>**,**</sub> nothing downstream will trigger until the rejection is handled or the flow is redesigned.

<table><thead><tr><th width="249">Tab</th><th>What It Does</th></tr></thead><tbody><tr><td>If approved</td><td>Actions that run when someone approves the request</td></tr><tr><td>If rejected</td><td>Actions that run when someone rejects the request</td></tr></tbody></table>

## Example

Imagine you're building a leave request workflow that involves approval from both team lead and manager:

**If approved:**

* Send an email to employee that team has approved
* Send a confirmation email to the employee&#x20;
* Notify HR via email

<figure><img src="/files/bawLPEPzAN5Xx0eqUQrB" alt=""><figcaption></figcaption></figure>

**If rejected:**

* Send a rejection email with the reason

<figure><img src="/files/Ek2Bbw8gyXHNaUTHjL8E" alt=""><figcaption></figcaption></figure>

## **Tips & Good to Know**

1. **Updating step names:** Step names are pulled from FormSG. To rename a step, update it in your FormSG workflow settings, then click "Test step" in Plumber to sync the new name.
2. **MRF steps can only be managed in FormSG.** You cannot reorder, create, delete, or edit them in Plumber. After making changes in FormSG, click "Test step" in Plumber to sync.
   * You can, however, freely reorder action steps within or across MRF steps and branches.

**What Happens When MRF Steps Change**

* **Deleting an MRF step in FormSG:** After syncing via "Test step", all action steps between the deleted step and the next MRF step will also be removed from Plumber.
* **Adding a new MRF step in FormSG:** The new step appears after the last existing MRF step. If the previous last step had a rejection branch that the new step doesn't, the rejection branch will be removed.

**Limitations**

* **For-Each** and **If-Then** steps can only be added in the last MRF step, one per branch in approval branches.
* **Delay** and **Only Continue If** cannot be placed immediately before an MRF step. It will not work as intended.
* Reconnecting your pipe to a non-MRF form will wipe your entire pipe configuration.

## Common errors when using MRF integration

<details>

<summary>MRF steps didn't appear after testing</summary>

* Make sure your form is set to [**Multirespondent mode**](https://guide.form.gov.sg/user-guides/multi-respondent-form-guide) in FormSG
* Check that you have workflow steps configured in FormSG
* Make sure the form is published
* Try clicking Test step again

</details>

<details>

<summary>The form you are trying to connect is currently being used in another pipe. Continuing with this connection will cause the other pipe to break.</summary>

Ensure that current pipe is no longer in use before proceeding.

</details>

<details>

<summary>'If approved' and 'If rejected' are not showing up</summary>

<figure><img src="/files/RzcdQPRCmNn4gz5AI6Qc" alt=""><figcaption></figcaption></figure>

Ensure the 'Make this step an approval' toggle is enabled in your MRF form's workflow

</details>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://guide.plumber.gov.sg/user-guides/start-the-workflow/formsg-multi-respondent-form-integration.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.