Database Design Documentation
Database Design Documentation
If your sheet has an Approval Flow, you can apply the formulas below to return certain values related to the approval process.
Currently, we support two types of approval formulas:
1. Related to the Whole Approval Flow
2. Related to a Certain Step of Approval Flow
For more information and examples of approval formulas, please refer to this page.
About formula recalculation, please refer to this article.
| Formula | Description |
|---|---|
| APPROVAL.COUNT() | Returns the number of approval steps. |
| APPROVAL.STATUS() | Returns approval status.
N: New, indicating the approval process has not yet started or has been canceled. P: Processing, indicating the approval process is ongoing and awaiting completion. REJ: Rejected, indicating rejection by anyone approver. F: Finish, indicating completion when all approvers agree. |
| APPROVAL.SUBMITTER() | Returns the email address of the user who starts the approval process. Supported in Select User Fields. |
| APPROVAL.SUBMITTERNAME() | Returns the name of the user who starts the approval process. |
| APPROVAL.SUBMITDATE([true]) | Returns the date and time an approval process is started. Supported in Date Fields.
The [true] argument is optional; when applied, the time value will display in UTC+0. Otherwise, the time value will display in the account’s time zone. For more details, please refer to this section. |
| APPROVAL.FINISHDATE([true]) | Returns the date and time an approval process ends. An approval ends when all the approvers approve or when one of them rejects. Supported in Date Fields.
The [true] argument is optional; when applied, the time value will display in UTC+0. Otherwise, the time value will display in the account’s time zone. For more details, please refer to this section |
| Formula | Description |
|---|---|
| APPROVAL.CURRENTSTEPINDEX | Returns the index value representing the current step in the approval process.
Index 0 means the approval process has not yet been started. Index 1 means the approval process has been started but no approver has approved yet. Whenever an approver approves, "1" will be added to the index. When the approval process ends (all approve/ 1 rejects/ canceled), the index returns to "0". |
The following formulas should be prefixed with APPROVAL.STEP([stepIndex]), which indicates a specific step in the approval process using an index value. This is not a standalone formula but can be used with other approval formulas. The [stepIndex] argument is optional; if not provided, APPROVAL.CURRENTSTEPINDEX will be used as the default, representing the current step. The arguments are explained as follows:
APPROVAL.STEP(-1): Last step.
APPROVAL.STEP(): Current step. Equivalent to APPROVAL.STEP(APPROVAL.CURRENTSTEPINDEX)).
APPROVAL.STEP(0): Incorrect usage.
APPROVAL.STEP(1): First step.
APPROVAL.STEP(2): Second step.
| Formula | Description |
|---|---|
| APPROVAL.STEP([stepIndex]).NAME() | Returns the name of this step. |
| APPROVAL.STEP([stepIndex]).STATUS() | Returns the status of this step.
N: New, indicating the approval process has not yet started or has been canceled. F: Finish. If this step involves a "single approver", it indicates either approval or rejection of the request. If there are "multiple approvers", it indicates that the number of approvers who have agreed equals or exceeds the designated threshold, or someone has rejected the request. |
| APPROVAL.STEP([stepIndex]).USERS() | Returns all approvers.
E.g., Jessica Jones|Nick Fury|Steve Rogers Supported in Multiple Select Users Fields. (Since formulas cannot currently be applied to Multiple Select Fields, please set the formula first, then select Multiple Select settings.) |
| APPROVAL.STEP([stepIndex]).UNSIGNEDUSERS() | Returns the approvers who haven't approved in this step. E.g., Jessica Jones|Nick Fury|Steve Rogers
Supported in Multiple Select Users Fields. (Since formulas cannot currently be applied to Multiple Select Fields, please set the formula first, then select Multiple Select settings.) |
| APPROVAL.STEP([stepIndex]).SIGNEDUSERS() | Returns the approvers who have already approved this step.
E.g., Jessica Jones|Nick Fury|Steve Rogers Supported in Multiple Select Users Fields. (Since formulas cannot currently be applied to Multiple Select Fields, please set the formula first, then select Multiple Select settings.) |
| APPROVAL.STEP([stepIndex]).ISMULTI() | Returns "True" if this step has "multiple approvers". |
| APPROVAL.STEP([stepIndex]).THRESHOLD() | Returns the threshold number of this step, or "-1" if this step only has a single approver or no threshold was set. |
| APPROVAL.STEP([stepIndex]).SIGNEDCOUNT() | Returns the number of the approvers who have already approved this step. |
In the following formula, [email] is an optional argument (required in specific scenarios) that can be used in two ways to retrieve a specific person’s approval data in an approval step with multiple users.
1. As the email string (enclosed in ""), e.g., APPROVAL.STEP([stepIndex]).RESP("example@ragic.com")
2. Directly using the Email field or Select User Field, e.g., APPROVAL.STEP([stepIndex]).RESP(A2)
Note:
1. The [email] argument in the formula is only applicable for approval steps created after 2021/07/13.
2. When an approval formula includes multiple arguments, if the [email] argument is not needed, you must enter null.
For example, the following formula contains both [email] and [true] arguments: APPROVAL.STEP([stepIndex]).ACTIONDATE([email], [true]).
(1) If the [true] argument is not used, the [email] argument can be left empty: APPROVAL.STEP(2).ACTIONDATE().
(2) If the [true] argument is used but the [email] argument is not needed, you must enter null: APPROVAL.STEP(1).ACTIONDATE(null, true).
If null is not entered, as in: APPROVAL.STEP(1).ACTIONDATE(true), then true will be mistaken as the [email] argument, causing the formula to malfunction.
| Formula | Description |
|---|---|
| APPROVAL.STEP([stepIndex]).RESP([email]) |
Returns the response of this step. (1) One approver in an approval step: No [email] argument needed. N: Not yet, indicating that this step has not yet been approved or rejected and is still pending approval. A: Accepted, indicating that the approver has accepted the approval. A_D: Accept by Deputy, indicating that the deputy of the approver has accepted the approval. REJ: Rejected, indicating that the approver has rejected the approval. REJ_D: Reject by Deputy, indicating that the deputy of the approver has rejected the approval. (2) Multiple approvers in an approval step: Without the [email] argument: N: Not yet, indicating that the number of approvers who have accepted the approval is less than the designated number of approvers. A: Accepted, indicating that the number of approvers who have accepted the approval is greater than or equal to the designated number of approvers. REJ: Rejected, indicating that someone has rejected the approval. With the [email] argument: unsigned: The approver has not yet accepted or rejected the approval. signed: The approver has accepted the approval. signed_by_deputy: The approval has been accepted by the deputy of the approver. rejected: The approver has rejected the approval. rejected_by_deputy: The approval has been rejected by the deputy of the approver. For email argument details, please refer here. |
| APPROVAL.STEP([stepIndex]).COMMENT([email]) | Returns comments of the approver(s), or null if there is no comment.
(1) One approver in an approval step: No [email] argument needed. Returns the comment of the approver. (2) Multiple approvers in an approval step: The [email] argument is required. Returns the comment of a certain approver. For email argument details, please refer here. |
| APPROVAL.STEP([stepIndex]).SIG([email]) | Returns the signature of the approver in this step.
E.g., base64 image URL. Supported in Upload Image Fields. (1) One approver in an approval step: No [email] argument needed. Returns the signature of the approver in this step. (2) Multiple approvers in an approval step: The [email] argument is required. Returns the signature of a certain approver. For email argument details, please refer here. |
| APPROVAL.STEP([stepIndex]).SIGIMG([email], [width], [height]) | Returns the signature of the approver in this step in a predetermined image size.
The [width] and [height] arguments are optional, with default values being 300px x 150px. This formula can be applied to field descriptions with BBCode [formula]. Note: 1.To return a signature for a single approver in an approval process with dimensions 600px in length and 300px in width, use APPROVAL.STEP([stepIndex]).SIGIMG(null, 600, 300), where null should not be enclosed in " ". 2. The field type cannot be an Image/Signature field; it must be a text field (e.g., Free Text). For email argument details, please refer here. |
| APPROVAL.STEP([stepIndex]).ACTIONDATE([email],[true]) |
Returns the approve or reject time of a specific approval step. This formula needs to be applied to a Date Field. The [true] argument is optional; when applied, the time value will display in UTC+0. Otherwise, the time value will display in the account’s time zone. For more details, please refer to this section. (1) One approver in an approval step: No [email] argument needed. Returns the approver’s approval or reject date and time. (2) Multiple approvers in an approval step: Without the [email] argument: The system will return the date and time when one approver has rejected this approval or when the step is completely approved (the number of approved approvers meets the approval threshold settings). With the [email] argument: The system will return the respective user’s approval or reject time. For email argument details, please refer here. |
| APPROVAL.STEP([stepIndex]).COMMENTDATE([email], [true]) | Returns the date and time left comments of the approver(s).
The [true] argument is optional; when applied, the time value will display in UTC+0. Otherwise, the time value will display in the account’s time zone. For more details, please refer to this section. (1) One approver in an approval step: No [email] argument needed. Returns the date and time the comment was left by the approver. (2) Multiple approvers in an approval step: The [email] argument is required. Returns the date and time left the comment was left by a certain approver. For email argument details, please refer here. |
Approval formulas that return a timestamp: APPROVAL.SUBMITDATE([true]) 、 APPROVAL.FINISHDATE([true])、APPROVAL.STEP([stepIndex]).ACTIONDATE([email],[true])、APPROVAL.STEP([stepIndex]).COMMENTDATE([email],[true])
It is recommended to include the [true] argument when using these formulas, and to enable "Display Using Browser’s Time Zone" in the date field settings.
If your sheet has already started or completed the approval process, and you subsequently add a field applying an approval formula that returns time, such as APPROVAL.SUBMITDATE([true]) or APPROVAL.STEP([stepIndex]).ACTIONDATE([email],[true]), to a sheet that already contains Date values with the "Display Using Browser’s Time Zone" setting, it may result in the displayed time being adjusted based on "your browser's time zone".
For example, if you have already approved a sheet on "August 1, 2023, at 12:00 PM", and the approval time field at that time was not set to "Display Using Browser’s Time Zone", the recorded time was according to the "company time zone". When you subsequently add a "New Approval Time" field and enable "Display Using Browser’s Time Zone", it will cause the approval formula to calculate based on the "company's time zone" first. Then, it will add the value displayed using the browser's time zone (e.g., UTC+8). Consequently, the time in the "New Approval Time" field will be further increased by 8 hours and displayed as "8:00 PM on August 1, 2023".
Hence, when you encounter time zone discrepancies in the approval time, simply uncheck the "Display Using Browser’s Time Zone" option for that field. This will ensure that the sheet calculates the time based on the "company time zone".
When you check or uncheck the "Display Using Browser’s Time Zone" option, the system will display a reminder indicating that the field's date values will be converted. Therefore, please pay attention to this setting and avoid checking or unchecking it for fields that already contain date values.
