設計手冊
設計手冊
如果你的表單有設定簽核流程，就可以套用以下公式來傳回簽核相關的資料。
目前與簽核有關的公式，主要有兩大類：
1. 與整體簽核流程有關
2. 與特定簽核階層有關
更完整的簽核公式使用說明與範例請參考此頁面。
關於簽核公式重算請參考這篇說明
| 公式 | 敘述 |
|---|---|
| APPROVAL.COUNT() | 傳回簽核的總階層數。 |
| APPROVAL.STATUS() | 傳回簽核的狀態。
N: New，尚未開始簽核或取消簽核 P: Processing，開始簽核後等待簽核完成 REJ: Rejected，有任何一階拒絕簽核 F: Finish，全部簽核人都同意時，代表完成 |
| APPROVAL.SUBMITTER() | 傳回開始簽核的使用者E-mail。可以套用在使用者欄位。 |
| APPROVAL.SUBMITTERNAME() | 傳回開始簽核的使用者名稱。 |
| APPROVAL.SUBMITDATE([true]) | 傳回開始簽核的日期和時間。可以套用在日期欄位上。True為選填參數，填入代表用UTC+0，沒有則使用公司時區，詳細說明參考此章節。 |
| APPROVAL.FINISHDATE([true]) | 傳回簽核結束的日期和時間。簽核「結束」指的是全部簽核人都同意或是有人拒絕簽核，可以套用在日期欄位上。True為選填參數，填入代表用UTC+0，沒有則使用公司時區，詳細說明參考此章節。 |
| 公式 | 敘述 |
|---|---|
| APPROVAL.CURRENTSTEPINDEX | 目前這一階層的索引值。從 0 開始，0 代表尚未開始簽核，開始簽核後會變成 1，代表第 1 階。
每次完成一階層的簽核時這個值都會加 1，直到總階層數為止。 當結束簽核(全部階層都同意/或某一階拒絕/或取消簽核)時也傳回 0。 |
以下公式前面都要加上 APPROVAL.STEP([stepIndex])，代表用索引值指定某一階層，非單獨使用的公式，是用於搭配使用的簽核公式參數。
stepIndex 為選擇性的參數，如果不填入參數，表示使用 APPROVAL.CURRENTSTEPINDEX 作為 stepIndex，代表目前這一階層，參數說明：
APPROVAL.STEP(-1) : 上一階
APPROVAL.STEP() : 目前這一階 (等同於 APPROVAL.STEP(APPROVAL.CURRENTSTEPINDEX))
APPROVAL.STEP(0) : 錯誤，不能這樣用
APPROVAL.STEP(1) : 第一階
APPROVAL.STEP(2) : 第二階
| 公式 | 敘述 |
|---|---|
| APPROVAL.STEP([stepIndex]).NAME() | 傳回這一階層的名稱。 |
| APPROVAL.STEP([stepIndex]).STATUS() | 傳回這一階層的狀態。
N: New，這階尚未同意或拒絕簽核，處於簽核中 F: Finish，如果這階是單人，代表該簽核人同意或拒絕簽核；如果這階是多人，代表已同意簽核人數大於等於擇辦人數，或是有人拒絕簽核 |
| APPROVAL.STEP([stepIndex]).USERS() | 傳回這一階所有的簽核人。範例值: 王小美|李曉明|彭大海。可以將此公式套用在使用者多選欄位(因為目前多選欄位不支援套用公式，請先設定好公式，再點選多選設定)。 |
| APPROVAL.STEP([stepIndex]).UNSIGNEDUSERS() | 傳回這一階未簽核的人。
範例值：王小美|李曉明|彭大海。可以將此公式套用在使用者多選欄位(因為目前多選欄位不支援套用公式，請先設定好公式，再點選多選設定)。 |
| APPROVAL.STEP([stepIndex]).SIGNEDUSERS() | 傳回這一階已同意簽核的人。
範例值： 王小美|李曉明|彭大海。可以將此公式套用在使用者多選欄位(因為目前多選欄位不支援套用公式，請先設定好公式，再點選多選設定)。 |
| APPROVAL.STEP([stepIndex]).ISMULTI() | 傳回這一階是否為多人簽核。會回傳 true 或 false。 |
| APPROVAL.STEP([stepIndex]).THRESHOLD() | 傳回這一階的擇辦人數。如果這階是單人簽核或是沒有設定擇辦人數，值為 -1。 |
| APPROVAL.STEP([stepIndex]).SIGNEDCOUNT() | 傳回這一階已同意簽核的人數。 |
以下公式中的[email]為選擇性參數，可以使用以下兩種方式代入參數，用來在多人簽核時取得某個人的簽核資料。
1. 信箱字串(需加上"")，例如：APPROVAL.STEP([stepIndex]).RESP("example@ragic.com")
2. 直接使用 Email 欄位或使用者欄位，例如：APPROVAL.STEP([stepIndex]).RESP(A2)
(注意：公式內的[email]參數僅可套用於參照 2021/07/13 後所建立的簽核步驟)
| 公式 | 敘述 |
|---|---|
| APPROVAL.STEP([stepIndex]).RESP([email]) | 傳回這一階層的回應。
單人簽核：不需要帶 email 參數 N: Not yet，這階尚未同意或拒絕簽核，處於簽核中。 A: Accepted，該簽核人同意簽核 A_D: Accept by deputy，該簽核人的代理人同意簽核 REJ: Rejected，該簽核人拒絕簽核 REJ_D: Reject by deputy，該簽核人的代理人拒絕簽核 多人簽核： (1) 沒有帶 email 參數： N: Not yet，已同意簽核人數小於擇辦人數 A: Accepted，已同意簽核人數大於等於擇辦人數 REJ: Rejected，有人拒絕簽核 (2) 有帶 email 參數： unSigned: 該簽核人尚未同意或拒絕簽核 signed: 該簽核人同意簽核 signed_by_deputy: 經由該簽核人的代理人同意簽核 rejected: 該簽核人拒絕簽核 rejected_by_deputy: 經由該簽核人的代理人拒絕簽核 |
| APPROVAL.STEP([stepIndex]).COMMENT([email]) | 傳回這一階的簽核人在同意或拒絕簽核時留下的理由。如果還沒同意或拒絕簽核，或是做了這兩個動作但沒有留下理由，回傳空值。
單人簽核：不需要帶 email 參數，傳回該簽核人的理由 多人簽核：一定要帶 email 參數，取得某人的理由 |
| APPROVAL.STEP([stepIndex]).SIG([email]) | 傳回這一階的簽核人的電子簽名。值為 base64 圖片網址字串，如果沒有簽名傳回空值。可以將這公式套用在圖片欄位上。
單人簽核：不需要帶 email 參數，傳回該簽核人的電子簽名 多人簽核：一定要帶 email 參數，傳回該簽核人的電子簽名 |
| APPROVAL.STEP([stepIndex]).SIGIMG([email], [width], [height]) | 傳回這一階的簽核人的電子簽名。類似APPROVAL.STEP([stepIndex]).SIG([email])，只是這公式的值為bbcode [image]，width 與 height 為可選參數，設定圖片的寬與高，如果沒設定，預設寬為 300px 高為 150px。可以配合 bbcode 公式將結果呈現在文字敘述上。
注意： 1.如果要呈現單人簽核而且長為 600px 寬為 300 px 的簽名圖，要寫成 APPROVAL.STEP([stepIndex])SIGIMG(null, 600, 300)，此處的 null 不需加引號。 2. 欄位種類不能使用圖片/簽名欄位，必須使用字串欄位(例如：自由輸入)。 |
| APPROVAL.STEP([stepIndex]).ACTIONDATE([email],[true]) | 傳回這一階簽核人同意或拒絕的日期和時間。套用在日期欄位。True為選填參數，填入代表用UTC+0，沒有則使用公司時區，詳細說明參考此章節。
單人簽核：不需要 email 參數，傳回該簽核人的同意或拒絕的日期和時間。 多人簽核：沒有帶 email 參數時，傳回有人拒絕或是有人同意簽核而且達標(已同意簽核人數大於擇辦人數)的日期和時間。 有帶 email 參數時，傳回該簽核人同意或拒絕的日期和時間。 |
| APPROVAL.STEP([stepIndex]).COMMENTDATE([email],[true]) | 傳回這一階的簽核人在同意或拒絕簽核時寫下理由的日期和時間。如果還沒同意或拒絕簽核，或是做了這兩個動作但沒有留下理由，回傳空值，可以將這公式套用在日期欄位上。True為選填參數，填入代表用UTC+0，沒有則使用公司時區，詳細說明參考此章節。
單人簽核：不需要帶 email 參數，傳回該簽核人寫下理由的日期和時間。 多人簽核：一定要帶 email 參數，傳回某人寫下理由的日期和時間。 |
回傳時間的簽核公式：APPROVAL.SUBMITDATE([true]) 、 APPROVAL.FINISHDATE([true])、APPROVAL.STEP([stepIndex]).ACTIONDATE([email],[true])、APPROVAL.STEP([stepIndex]).COMMENTDATE([email],[true])
建議使用公式時加上 true 這個參數，同時在日期欄位設定勾選「以瀏覽器時區顯示」。
特別提醒，如果你的表單已經開始或完成了簽核流程，後續在已經有日期資料的表單，去新增欄位套用會回傳時間的簽核公式，並且勾選了以瀏覽器時區顯示，可能會讓顯示的時間被加上/減去你所在的時區。
舉例來說，如果你已經在 2023/08/01 12:00 先進行了簽核，而此時的簽核時間欄位並未勾選以瀏覽器時間顯示，儲存的時間會以公司時區被儲存。當你後續新增一個「新的簽核時間」欄位，並勾選了以瀏覽器時區顯示，會導致簽核公式在計算的時候，先算出了以公司時區做計算的值，接著又加上了以瀏覽器時區顯示（若為 UTC+8）的值，此「新的簽核時間」欄位的時間會再被多加 8 小時，顯示為 2023/08/01 20:00。
因此，當發現簽核時間有上述的時區差異，取消勾選該欄位的以瀏覽器時區顯示，讓表單計算回歸到公司時區即可。
當你勾選或取消勾選以瀏覽器時區顯示的時候，系統會顯示提醒，告知欄位日期資料會被轉換，因此請特別留意此設定，盡量不要在已經有日期資料的欄位勾選或取消勾選。
