> For the complete documentation index, see [llms.txt](https://docs.fabricplan.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.fabricplan.com/planning-sheets/how-tos/configure-approval-workflows.md).

# Configure approval workflows

Approval workflows manage changes made to planning data by routing updates through one or more approval levels. When multiple users update the same planning sheet, approval workflows help maintain data integrity by ensuring that changes are reviewed before they are finalized.

When a user updates a data input or forecast value, the workflow automatically perform actions such as sending Teams notifications, updating task or approval status, and modifying related field values. Approvers can then review the changes and approve or reject the request.

You can configure approval workflows in either of the following ways:

* By [using scripts](#configure-approval-workflows-by-using-scripts).
* By using the [Approval Workflow interface](#configure-approval-workflows-without-scripting) without writing scripts.

### Configure approval workflows by using scripts

You can create customized approval workflows by writing scripts in the **On Change Formula** section of data input and forecast columns. These scripts run automatically whenever a value changes.

The following example demonstrates a script-driven approval workflow. The planning sheet includes the following single select list columns: *Task Status*, *Manager Approval*, and *Director Approval* and the approvers' email columns to demonstrate the approval process.

<figure><img src="https://257222532-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUtolck8kt8atqxFPsEBn%2Fuploads%2FpPLJ6QmIlUEPliVVMLw2%2Fimage.png?alt=media&amp;token=fa5a7ab0-119b-4c64-bcd4-b8ea78052c16" alt=""><figcaption></figcaption></figure>

**Single Select** columns allow users to select only one value from a configured dropdown list. For more information, see [**Single Select columns**](/planning-sheets/how-tos/measure-and-row-based-planning/insert-manual-input-columns/dropdown.md).

To create this script-driven approval workflow:

1. To insert a text column, on the **Planning** tab, select **Insert Column** > **Text**.
2. Insert three text columns named *Associate Email*, *Manager Email*, and *Director Email*, and enter the respective email addresses in these columns.
3. On the **Planning** tab, select **Insert Column** > **List** > **Single Select**.
4. Enter the name as *Task Status* and configure the column with the following options: *InProgress*, *Submit For Review*, *Approved*, and *Reopened*.
5. In the **On Change Formula** section's formula editor, enter the following script and select **Create**.<br>

   ```
   //Notify the manager when a request is submitted
   IF(THIS == 'Submit For Review', NOTIFY_USER([Manager Email]),"")
   //Update the manager approval status to pending
   IF(THIS == 'Submit For Review', SETVALUE([Manager Approval], 'Pending'), "")
   ```
6. Insert a **Single Select** column and name it as *Manager Approval*. Configure the column with the following options: *Pending*, *Approved*, *Rejected*, and *Reopened*.
7. In the formula editor of the **On Change Formula** section, enter the following script and select **Create**.<br>

   <pre><code>//Notify the director AND the submitter when a request is approved by manager 
   IF(THIS == 'Approved', NOTIFY_USER([Associate Email]), "")
   IF(THIS == 'Approved', NOTIFY_USER([Director Email]), "")

   <strong>//Change the director approval status as pending
   </strong>IF(THIS == 'Approved', SETVALUE([Director Approval], 'Pending'), "")

   //IF the request is rejected, Notify the associate AND update the task status as reopened
   IF(THIS == 'Rejected', NOTIFY_USER([Associate Email]), "")
   IF(THIS == 'Rejected', SETVALUE([Task Status], 'Reopened'), "")

   //IF the request is reopened, Notify the associate AND update the task status as //reopened
   IF(THIS == 'Reopened', NOTIFY_USER([Associate Email]), "")
   IF(THIS == 'Reopened', SETVALUE([Task Status], 'Reopened'), "")
   </code></pre>
8. Insert a **Single Select** column and name it as *Director Approval*. Configure the column with the following options: *Pending*, *Approved*, *Rejected*, and *Reopened*.
9. In the formula editor of the **On Change Formula** section, enter the following script and select **Create**.<br>

   ```
   //If director approves, set task status as 'Approved' and notify the associate and manager.
   IF(THIS == 'Approved', SETVALUE([Task Status], 'Approved'), "")
   IF(THIS == 'Approved', NOTIFY_USER([Associate Email]), "")
   IF(THIS == 'Approved', NOTIFY_USER([Manager Email]), "")

   //If director rejects, set task status and manager approval as 'Reopened' and notify the associate and manager.
   IF(THIS == 'Rejected', SETVALUE([Task Status], 'Reopened'), "")
   IF(THIS == 'Rejected', SETVALUE([Manager Approval], 'Reopened'), "")
   IF(THIS == 'Rejected', NOTIFY_USER([Associate Email]), "")
   IF(THIS == 'Rejected', NOTIFY_USER([Manager Email]), "")
   ```

### How the workflow works

After a user updates a data input value, such as *Actuals*, they set the *Task Status* to **Submit For Review**. This triggers the configured formula in **On Change Formula** section, which executes the workflow actions.

<figure><img src="https://257222532-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUtolck8kt8atqxFPsEBn%2Fuploads%2FzYEYqQemlspPdGU9pmmK%2Fimage.png?alt=media&amp;token=82667133-d833-497f-8be1-17a9cb91b140" alt=""><figcaption></figcaption></figure>

The approval status columns also contain scripts that run automatically whenever their values change. The following image shows the script configured in the **On Change Formula** section of the *Manager Approval* column.

<figure><img src="https://257222532-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUtolck8kt8atqxFPsEBn%2Fuploads%2F6WIA6YrA4YnCExdJO9jv%2Fimage.png?alt=media&amp;token=f89829c9-f33b-4c3e-8690-d66749cde8d1" alt=""><figcaption></figcaption></figure>

The scripts primarily use the following functions:

* **SETVALUE** - Updates related fields automatically based on approval status changes.
* **NOTIFY\_USER** - Sends Microsoft Teams notifications to approvers or requesters, along with details of the updated value.

The workflow can automatically:

* Update related approval status fields.
* Send notifications to the next-level approver.
* Reopen tasks when a request is rejected.
* Mark tasks as approved after all approval levels are completed.

In the following example:

* When the user changes the *Task Status* to **Submit for Review**, the *Manager Approval* status is updated to **Pending**.<br>

  <figure><img src="https://257222532-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUtolck8kt8atqxFPsEBn%2Fuploads%2FkzEmhJVryKx9L3FBMx8B%2Fimage.png?alt=media&amp;token=6ee539eb-b221-4040-887e-3338119c0e2e" alt=""><figcaption></figcaption></figure>
* When the manager approves the request, the *Director Approval* status is updated to **Pending**.<br>

  <figure><img src="https://257222532-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUtolck8kt8atqxFPsEBn%2Fuploads%2F339ZeVCCRe8SV7tpP7km%2Fimage.png?alt=media&amp;token=7b6f8020-2754-4e0a-af63-288c7ebf3a61" alt=""><figcaption></figcaption></figure>
* When the manager rejects the request, the *Task Status* is updated to **Reopened**.<br>

  <figure><img src="https://257222532-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUtolck8kt8atqxFPsEBn%2Fuploads%2F1fUAZmE1YmlLck08lj81%2Fimage.png?alt=media&amp;token=92bf95d9-46b8-4870-9709-3d156b5de674" alt=""><figcaption></figcaption></figure>
* When the final approver approves the request, the *Task Status* is updated to **Approved**.<br>

  <figure><img src="https://257222532-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUtolck8kt8atqxFPsEBn%2Fuploads%2FK4YACapjlGZl3FG8e2xL%2Fimage.png?alt=media&amp;token=4a80261c-91d1-4b99-abb5-cf51243ffeff" alt=""><figcaption></figcaption></figure>
* If the request is rejected, both the previous approval level and the task status are updated to **Reopened**.<br>

  <figure><img src="https://257222532-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUtolck8kt8atqxFPsEBn%2Fuploads%2F7uypuNVVAkfCyPjVTj1p%2Fimage.png?alt=media&amp;token=4c4da013-2af3-4d4e-addf-2acdeee4fe1d" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}

#### TIP

You can customize the workflow logic to meet your business requirements by editing the scripts.
{% endhint %}

### Configure approval workflows without scripting

You can also create approval workflows without writing scripts by using the **Approval Workflow** interface.

To open the Approval Workflow interface:

1. Select the **Model** tab, and then select **Approval**.<br>

   <figure><img src="https://257222532-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUtolck8kt8atqxFPsEBn%2Fuploads%2FDoDwk2jrTjl8Jjeju9Gk%2Fimage.png?alt=media&amp;token=25b4252d-ed7e-479b-9f24-f3506d28c319" alt=""><figcaption></figcaption></figure>
2. The **Approval Workflow** window opens.<br>

   <figure><img src="https://257222532-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUtolck8kt8atqxFPsEBn%2Fuploads%2Fw4xpm84YmNtOQYo6Q7Gl%2Fimage.png?alt=media&amp;token=106e67df-d2de-4b5c-9173-62c82bfdff64" alt=""><figcaption></figcaption></figure>

### Configure approval levels

The first workflow level tracks the overall task status, while the remaining levels represent the approval stages.

To configure approval levels:

1. Enter a name for the task status column by selecting the edit icon. A **Single Select** column will get created with predefined values such as *In Progress*, *Submitted*, and *Reopened*.
2. Select the users who can update the task status and receive approval notifications.

   You can either:

   * Select users directly from the dropdown.
   * Select **Column** to use email addresses stored in a text column.
3. Enter a name for the first approval level column by selecting the edit icon. A **Single Select** column will get created with predefined values such as *Pending*, *Approved*, *Rejected* and *Reopened*.
4. Select one or more approvers for the approval level.
5. Optionally, select **Add** to create additional approval levels.
6. After configuring all approval levels, select **Next**.<br>

   <figure><img src="https://257222532-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUtolck8kt8atqxFPsEBn%2Fuploads%2FzZX09axadkSxMF9r5G01%2Fimage.png?alt=media&amp;token=4a06b16b-d638-4b67-9b3a-b0c2d65b8207" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}

#### NOTE

The **Column** option gets enabled only when the planning sheet contains one or more text columns with email addresses.
{% endhint %}

### Configure workflow settings

Configure the following workflow settings before creating the approval workflow.

#### Reset on rejection

Enable **Reset on Rejection** to reset all previous approval levels to *In Progress* or *Reopened* when the request is rejected by the final level approver.

This option is disabled by default.

#### Teams notifications

Enable or disable Microsoft Teams notifications for the following users:

* Approvers - Notify approvers when data is submitted for approval.
* Submitters - Notify submitters about approval decisions.

**Microsoft Teams** notifications are enabled by default.

<figure><img src="https://257222532-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUtolck8kt8atqxFPsEBn%2Fuploads%2FCRpq27BwuKsHNWUqg2PS%2Fimage.png?alt=media&amp;token=6293e9e1-765c-4a76-a40d-1b8880f2fabe" alt=""><figcaption></figcaption></figure>

Select **Submit** to create the approval workflow.

### Approval workflow behavior

After the approval workflow is created, the required **Single Select** columns are added automatically to the planning sheet.

In the following example:

* The *Task Status*, *Manager Approval*, and *Director Approval* **Single Select** columns are automatically added to the planning sheet when the approval workflow is created.<br>

  <figure><img src="https://257222532-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUtolck8kt8atqxFPsEBn%2Fuploads%2FApAmUhIqFK38YwlOVeRT%2Fimage.png?alt=media&amp;token=1f743dab-0358-4531-8506-554faa41e1d7" alt=""><figcaption></figcaption></figure>
* After editing the *Actuals* data input value, setting the *Task Status* to **Submitted** sends a Teams notification to the configured manager and updates the *Manager Approval* status to **Pending**.<br>

  <figure><img src="https://257222532-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUtolck8kt8atqxFPsEBn%2Fuploads%2Fd9HVL5a9aZhRGv9fLquB%2Fimage.png?alt=media&amp;token=0edaf340-5e28-4338-a684-44a523825c28" alt=""><figcaption></figcaption></figure>
* When the manager approves the request, a Teams notification is sent to the configured Director, and the *Director Approval* status is updated to **Pending**.<br>

  <figure><img src="https://257222532-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUtolck8kt8atqxFPsEBn%2Fuploads%2FrdpTyzC8HHSjJWNydWvS%2Fimage.png?alt=media&amp;token=7ad00989-6139-49b6-91c2-ce2f81ac0d1d" alt=""><figcaption></figcaption></figure>
* If the manager rejects the request, the *Task Status* is updated to **Reopened**.<br>

  <figure><img src="https://257222532-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUtolck8kt8atqxFPsEBn%2Fuploads%2FS5lpAlT5C5rheO2jVr7P%2Fimage.png?alt=media&amp;token=562dd7cc-29a3-4a35-8eac-d68561a9c2b5" alt=""><figcaption></figcaption></figure>
* If the director approves the request, the workflow ends. If the director rejects the request, the *Manager Approval* status is updated to **Reopened**.<br>

  <figure><img src="https://257222532-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUtolck8kt8atqxFPsEBn%2Fuploads%2FtFi1AJGgq8ag7U5zeEp0%2Fimage.png?alt=media&amp;token=8e3200b7-f48e-4848-adf2-b139bb46a491" alt=""><figcaption></figcaption></figure>

If [**Reset on Rejection**](#reset-on-rejection) is enabled, both the *Task Status* and *Manager Approval* columns are updated to **Reopened** when the director rejects the request.

<figure><img src="https://257222532-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUtolck8kt8atqxFPsEBn%2Fuploads%2Fdz1X9s6rQCQ6WxbdkVNp%2Fimage.png?alt=media&amp;token=6f75b605-b5e8-4f65-aadb-9eda35f194bf" alt=""><figcaption></figcaption></figure>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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, and the optional `goal` query parameter:

```
GET https://docs.fabricplan.com/planning-sheets/how-tos/configure-approval-workflows.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.