Javascript 工作引擎

所有表單都可以觸發 Ragic 的伺服器端 JavaScript 工作流程引擎來執行複雜的業務邏輯，如計算成本和發布庫存餘額。基本上，任何 Ragic現有功能無法覆蓋的複雜業務邏輯都可以透過伺服器端程式來實現。 程式引擎基於標準的 Nashorn Java 程式引擎，它包含在 Java 平台中。Nashorn 支援 ECMAScript 5.1，所以最好避免使用 ECMAScript 6 語法。此外，由 Java 處理並傳遞至 JavaScript 的數據（例如陣列）可能會受到一些特定限制，導致無法直接使用像 join、map 等 JavaScript 方法，然而，若在 workflow 中直接定義一個 JavaScript 陣列並將資料存入其中，則可以正常使用這些 JavaScript 方法。同樣地，瀏覽器專屬的 API 例如: setTimeout、setInterval、alert、document......等等，也無法在此使用。

var query = db.getAPIQuery(pathToForm);
var entry = query.getAPIResult();
var values = entry.getFieldValues(fieldId); // 回傳的是一個陣列

var str = values.join(','); //不可用，會出錯

var ary = [];
for(var i = 0; i < values.length; i ++) {
  ary.push(values[i]);
}
var str = ary.join(','); //可用

JavaScript 工作流程的功能

Ragic 的試算表設計介面可以處理大部分資料管理工作，如建立、編輯和查詢記錄。然而，手動資料維護可能會變得有點耗時和繁瑣。這時，Ragic 用戶會開始考慮如何自動化這些過程。 在 Ragic 內部，有一個非常強大的程式引擎，可以撰寫在伺服器端運行的 JavaScript，用來檢索試算表上的資料，進行修改，甚至可以一次點擊建立多個紀錄。典型的使用場景包括更新庫存，根據另一筆紀錄建立新資料（例如從報價建立銷售訂單，從Sales lead建立聯絡人），或者用資料庫資料做資料檢查。 有五種主要方式來運行您的 JavaScript 工作流程：

1. 動作按鈕
2. Post-workflow
3. Pre-workflow
4. Daily Workflow
5. Approval Workflow

還有一個 Global Workflow，您可以在其中放置多個工作流程程式共享的常用 JavaScript 函數定義。

相關名詞定義

在workflow中，有幾個專有名詞會常出現，我們將這些名詞定義如下：假如我們表單中的某筆資料，URL為https://www.ragic.com/testAP/testForm/1/3

顯示訊息

您可以像這樣顯示一個彈出訊息。請注意，訊息僅在回應狀態為 "WARN" 時顯示。預設情況下，回應物件中的訊息將不會顯示，因為通常對最終用戶沒有幫助。要特別注意的是動作按鈕不支援setStatus('CONFIRM')。

response.setStatus('WARN');
response.setMessage(message);

另外因為 workflow 不支援 console 或 alert 等 JavaScript 指令，所以如果您想進行除錯，可以透過 log.setToConsole(true) 與 log.println(message) 來顯示。

var message = "hello ragic";
log.setToConsole(true); //叫出console區塊
log.println(message); //印出hello ragic

動作按鈕

這是運行 JavaScript 工作流程最常見和最清晰的方式，通常是我們的首選推薦。您可以在工作表的sheet scope中撰寫程式，並配置動作按鈕來執行程式，當用戶點擊將顯示在右下方“動作”面板中的按鈕時。要加上 sheet scope 程式，只需右鍵點擊一個工作表，然後選擇JavaScript Workflow：

並從頂部下拉選單中選擇sheet scope：

然後，您可以轉到表單頁面設計中，加上一個類型為JS Workflow的動作按鈕，並引用您撰寫的 JavaScript 函數。

請注意，您可以使用 {id} 作為函數呼叫的參數來傳遞當前記錄的紀錄 ID，例如：

setStatus({id})

當然，我們會在接下來的章節中介紹如何撰寫這些函數。

Post-workflow

Post-workflows 在記錄儲存後立即執行。通過 Post-workflow，可以方便地自動化您希望對剛儲存的紀錄進行的變更，而這些變更是公式無法完成的。或者，您可以對其他相關工作表的紀錄進行修改，例如更新庫存餘額。要加上 Post-workflow，只需右鍵點擊一個工作表，然後選擇JavaScript Workflow：

然後從頂部下拉選單中選擇Post-workflow。 一個典型的 Post-workflow 如下所示：

var recordId = param.getNewNodeId(keyFieldId);
var query = db.getAPIQuery(pathToForm);
var record = query.getAPIEntry(recordId);

// 對檢索到的紀錄進行所需操作

請參閱我們的 API 參考 和本文件的其他部分，了解您可以做的事情。還請注意，如果您在列表頁面上修改資料，Post-workflow 將不會執行。

Pre-workflow

Pre-workflows 在記錄儲存之前執行，因此可以用作檢查的一種方式，以檢查輸入的資料是否符合資料庫中的資料。通常，大多數檢查可以通過我們的前端正則表達式檢查，或自由文本欄位的唯一核取方塊來完成。但對於更複雜的後端檢查，有時需要 Pre-workflow。 要加上 Pre-workflow，只需右鍵點擊一個工作表，然後選擇JavaScript Workflow：

然後從頂部下拉選單中選擇Pre-workflow。 這裡有一個簡單的例子：假設我們有一個列表，

我們希望確保儲存的價格不是負數。

/**

 * 主鍵欄位: 1000004

 * 欄位名稱欄位 ID
 * - - - - - - - - - - - --------
 * ID : 1000001
 * 價格 : 1000002
 * 名稱 : 1000003
 * 是否可用 : 1000005

 */
function showMsg(str) {
  // 設定狀態為 'INVALID' 或 'ERROR' 以取消儲存。
  response.setStatus('INVALID');
  response.setMessage(str);
}

function ifThePriceIsNegative() {
  // 取得要儲存的價格。
  var newPrice = param.getNewValue(1000002);
  // 將 newPrice 字串轉換為整數。
  if(parseInt(newPrice) < 0) {
    return true;
  }
}

// 如果價格為負數，則不儲存。
if(ifThePriceIsNegative()) {
  showMsg('價格為負數！！');
}

現在嘗試儲存負數價格，我們會得到

值得注意的是，在 Ragic 中撰寫 Pre-workflow 時，不能使用 entry.getFieldValue（因為 Ragic 還沒有儲存）。請嘗試使用 param 來取得舊值和新值。

Daily Workflow

Daily Workflows 每天運行一次。這對於需要每天更新結果的修改非常有用，例如根據當前日期更新公式結果。要加上 Daily Workflow，只需右鍵點擊一個標籤，然後選擇Global Javascript Workflow：

然後從頂部下拉選單中選擇Daily Workflow。

默認情況下，Daily Workflow 在 UTC 19:00 運行。您可以在公司設定中更改執行時間和時區： 1. 前往帳戶設定

2. 點擊公司設定

3. 選擇公司當地時區和Daily Workflow 執行時間並儲存。

如果您的公司設定中沒有公司當地時區和Daily Workflow 執行時間，請聯絡我們來為您更新。

Approval Workflow

Approval Workflows 在簽核建立、簽核、拒絕、取消或完成後立即執行。 要加上 Post-workflow，只需右鍵點擊一個工作表，然後選擇JavaScript Workflow：

然後從頂部下拉選單中選擇Approval Workflow。 您可以透過以下方法取得記錄 ID：

var recordId = approvalParam.getEntryRootNodeId();

approvalParam 是簽核工作流程範圍內的預定義變數。您可以透過以下方法取得簽核操作：

var action = approvalParam.getApprovalAction();

在取得上述資料後，您可以根據需求進行自訂：

var query = db.getAPIQuery(pathToForm);
var entry = query.getAPIEntry(recordId);
if (action === 'CANCEL') {
  entry.setFieldValue(STATUS_FIELD, "簽核已取消！");
}else if (action === 'FINISH') {
  entry.setFieldValue(STATUS_FIELD, "簽核已完成！");
}else if (action === 'CREATE') {
  entry.setFieldValue(STATUS_FIELD, "簽核已建立！");
}else if (action === 'REJECT') {
  entry.setFieldValue(STATUS_FIELD, "簽核已拒絕！");
}else {
  entry.setFieldValue(STATUS_FIELD, "簽核已批准！");
}
entry.save();

Global Workflow

Global Workflow 是您可以撰寫的 JavaScript 工作流程模組，其他工作流程函數可以引用它。它不會自己執行，但可以在上面列出的任何類型的工作流程中引用。這是一個很好的地方來放置可能需要在多個工作表中重複的程式。要加上 Global Workflow，只需右鍵點擊一個標籤，然後選擇Global Javascript Workflow：

取得一筆資料

有兩種不同的方式來取得用戶正在查看的當前記錄（適用於動作按鈕）或用戶剛儲存的紀錄（適用於 Pre-workflow 和 Post-workflow）。

動作按鈕

表單頁面動作按鈕透過配置動作按鈕來呼叫您在 sheet scope 中定義的函數。當您定義動作按鈕呼叫的函數時，您可以傳遞參數 {id}，即點擊動作按鈕所在記錄的 ID，來在工作流程中使用。 您可以在動作按鈕工作流程 中看到範例。

Pre-workflow

您可以透過以下方法取得記錄 ID：

var recordId = param.getNewNodeId(keyFieldId);

param 是一個預定義變數，您可以在 Pre-workflow 和 Post-workflow 中使用它。

在取得記錄 ID 之後，這是取得記錄（entry）的方式：

var query = db.getAPIQuery(pathToForm);
var entry = query.getAPIEntry(id);

Post-workflow

對於 Post-workflow，您可以使用與 Pre-workflow 相同的方法。但是，還有一種方便的方法來檢索剛剛儲存的紀錄：

var entry=param.getUpdatedEntry();

如果表單頁面上有文字遮罩欄位，默認情況下您將獲得遮罩值。您可以透過以下方式取得未遮罩的值：

var query = db.getAPIQuery(pathToForm);
query.setUpdateMode();
query.setIgnoreAllMasks(true); // 取消所有遮罩欄位的遮罩。
var entry = query.getAPIEntry(id);

您可以使用 query.addIgnoreMaskDomain(fieldId_of_the_masked_field) 而不是query.setIgnoreAllMasks(true) 來僅取消特定欄位的遮罩。有關如何在以下部分中更新資料的更多介紹，請參閱更新資料

查詢資料

如果您想透過過濾條件取得多筆紀錄： 您可以使用addFilter(fieldId, operator, value) 來加上過濾條件，並使用getAPIResultsFull() 來取得記錄列表。或是您也可以針對同一個欄位做兩次addFilter，這樣就可以做AND過濾。以下是您可以使用的操作符列表：

單一條件

使用一次addFilter篩出符合條件的紀錄

var colA = "1000002"; //欄位A
var query = db.getAPIQuery("/workflow-demo/1");
query.addFilter(colA, '=', 'Green');
var results = query.getAPIResultsFull(); // results為所有欄位A為Green的資料
var entry = results.next();
while(entry) {
  // do something
  entry = results.next();
}

複合條件(AND)

使用多次addFilter篩出符合條件的紀錄

var colA = "1000002"; //欄位A
var colB = "1000004"; //欄位B
var query = db.getAPIQuery("/workflow-demo/1");
query.addFilter(colA, '=', 'Green');
query.addFilter(colB, '=', 'Yes');
var results = query.getAPIResultsFull(); // results為所有欄位A為Green且欄位B為Yes的資料
var entry = results.next();
while(entry) {
  // do something
  entry = results.next();
}

複合條件(OR)

使用多次addFilter篩出符合條件的紀錄

var colA = "1000002"; //欄位A
var query = db.getAPIQuery("/workflow-demo/1");
query.addFilter(colA, '=', 'Green');
query.addFilter(colA, '=', 'Red');
var results = query.getAPIResultsFull(); // results為所有欄位A為Green或欄位A為Red的資料
var entry = results.next();
while(entry) {
  // do something
  entry = results.next();
}

範圍查詢

var colA = "1000006"; //欄位A
var query = db.getAPIQuery("/workflow-demo/1");
query.addFilter(colA, '>', '20');
query.addFilter(colA, '<', '40');
var results = query.getAPIResultsFull(); // results為所有欄位A大於20且欄位A小於40的資料
var entry = results.next();
while(entry) {
  // do something
  entry = results.next();
}

請注意，當您透過日期或日期時間進行過濾時，它們需要以下列格式表示：yyyy/MM/dd或 yyyy/MM/dd HH:mm:ss。 您還可以透過呼叫 setFullTextSearch(String queryTerm) 來使用全文搜尋作為查詢過濾條件，而不是 addFilter()。

更新資料

範例連結

讓我們從一個簡單的範例開始，檢索當前記錄作為物件，使用按鈕更新其值，然後將其儲存回資料庫。以下是範例表單的外觀：

我們希望設計一些按鈕，通過點擊按鈕執行簡單的伺服器端 JavaScript 工作流程來更改我們的狀態欄位值。以下是按鈕後面的程式碼：

/**

 * AP_Name:wfdemo
 * 主鍵欄位: 1000013

 * 名稱 ID
 * - - - - - - - - - - - --------
 * No.: 1000011
 * 狀態: 1000012

 */
function setStatus(recordId, status) {

var STATUS_FIELD = 1000012; // 狀態欄位的欄位ID
var query = db.getAPIQuery("/workflow-demo/2"); // 取得工作表的查詢物件
var entry = query.getAPIEntry(recordId);// 取得當前記錄的物件

// 設定當前記錄的狀態值
if (status) {
  entry.setFieldValue(STATUS_FIELD, status);
}
else { // 用於切換
  var newStatus = entry.getFieldValue(STATUS_FIELD) == 'On' ? 'Off' : 'On'; // 取得欄位的當前值
  entry.setFieldValue(STATUS_FIELD, newStatus);
}

// 儲存記錄到資料庫
entry.save();
}

在撰寫 JavaScript 工作流程時，變數

db 是預定義的，您可以在任何地方參考它。通常，我們會呼叫方法getAPIQuery(pathToForm) 來取得工作表的查詢物件。然後，您可以透過在工作表物件上使用 getAPIEntry(recordId) 檢索記錄，並使用setFieldValue(fieldId,value) 設定欄位的值，或者使用getFieldValue(fieldId) 檢索記錄中的值。請注意，當加上日期值時，它必須是以下列格式之一：

yyyy/MM/dd

yyyy/MM/dd HH:mm:ss

HH:mm:ss

如果您正在從多選欄位檢索值，其中可能有多個值，請使用 getFieldValues(fieldId) 以陣列形式檢索所有值。您還可以呼叫 setFieldValue(fieldId,value,true) 並在末尾加上一個 true 參數來指定您正在“加上”一個選項到當前的值列表，而不是覆蓋現有值。請注意，這些操作僅適用於多選欄位。

如果您想複製一個多選欄位值並覆蓋到另一個多選欄位，您不能僅僅使用 getFieldValues(fieldId) 和 setFieldValue(fieldId,value,true)。這裡有一段程式碼供您參考：

var multipleSelectionFieldValue = entry.getFieldValues(1013251); // 1013251 是一個多選欄位 
var targetMultipleSelectionField = "";

for (var i = 0; i < multipleSelectionFieldValue.length; i++) {
  if (i == 0) {
    targetMultipleSelectionField = targetMultipleSelectionField + multipleSelectionFieldValue[i];
  } 
  else {
    targetMultipleSelectionField = targetMultipleSelectionField + "|" + multipleSelectionFieldValue[i];
  }
}

entry.setFieldValue(1013252, targetMultipleSelectionField, false); // 1013251 是另一個多選欄位 

請注意，您需要檢索每個選項，並使用垂直條字元（|）格式化這些選項，就像您在從 Excel 或 CSV 文件導入現有資料時所做的一樣。

如果您要將值設定為文件上傳欄位，您可以使用 setFieldFile(int fieldId, String fileName, String fileContent) 來建立一個具有您提供的 fileName 和 fileContent 的文件。Ragic 將會儲存此文件到指定欄位，這樣文件就可以在用戶界面上下載。

完成後，只需在記錄物件上呼叫 save() 將其儲存回資料庫。

建立記錄

建立記錄與更新資料非常相似。不同的是，您需要呼叫 query.insertAPIEntry() 來建立新資料。與 getAPIEntry() 一樣，它也會回傳一個紀錄物件，您可以使用 setFieldValue 來加上欄位值。呼叫 entry.save() 之後，記錄將被建立。

這是一個簡單的範例，修改了記錄更新範例來建立新資料：

/**

 * AP_Name:wfdemo
 * 主鍵欄位: 1000013

 * 名稱 ID
 * - - - - - - - - - - - --------
 * No.: 1000011
 * 狀態: 1000012

 */
function setStatus(recordId, status) {
  var STATUS_FIELD = 1000012; // 狀態欄位的欄位ID
  var query = db.getAPIQuery("/workflow-demo/2"); // 取得工作表的查詢物件
  var entry = query.insertAPIEntry();// 建立新資料物件

  // 建立新資料到資料庫
  entry.save();
}

子表格

範例連結

如果您在工作表中有子表格，您也可以使用我們的 API 來檢索資料或進行編輯，像以下範例。表單看起來像這樣：

這個工作流程將遍歷子表格中的每一行，找到本年度的總金額（根據子表格中的日期欄位）、金額最多的一年總額，並確定哪一年具有最高總額。這被設計為一個 Post-workflow，因此這三個只讀欄位將在記錄儲存後由工作流程填寫。

/**

 * AP_Name:wfdemo
 * 主鍵欄位: 1000006

 * 日期子表格主鍵: 1000007

 * 欄位名稱 欄位 ID
 * - - - - - - - - - - - --------
 * No. : 1000001
 * 名稱: 1000002
 * 日期: 1000003
 * 金額 : 1000004
 * 本年度總額: 1000010
 * 最高年度總額 : 1000009
 * 最高總額年份 : 1000008

 */

var KEY_FIELD = 1000006;
var AMOUNT_SUBTABLE_ID= 1000007;
var DATE_FIELD= 1000003;
var AMOUNT_FIELD= 1000004;
var MAX_YEAR_FIELD= 1000008;
var MAX_TOTAL_FIELD = 1000009;
var THIS_YEAR_TOTAL_FIELD = 1000010;

var query = db.getAPIQuery("/workflow-demo/1");

var entry = query.getAPIEntry(param.getNewNodeId(KEY_FIELD));
var subtableSize = entry.getSubtableSize(AMOUNT_SUBTABLE_ID);

var yearTotal = {}
for (var i = 0; i < subtableSize; i++) {
  var year = parseInt(entry.getSubtableFieldValue(AMOUNT_SUBTABLE_ID, i, DATE_FIELD).substr(0, 4));
  var amount = parseInt(entry.getSubtableFieldValue(AMOUNT_SUBTABLE_ID, i, AMOUNT_FIELD));
  if (year in yearTotal) {
    yearTotal[year] += amount;
  } else {
    yearTotal[year] = amount;
  }
}

var maxYear;
for (var year in yearTotal) {
  if (!maxYear || yearTotal[maxYear] < yearTotal[year]) {
    maxYear = year;
  }
}

entry.setFieldValue(MAX_YEAR_FIELD, maxYear);
entry.setFieldValue(MAX_TOTAL_FIELD, yearTotal[maxYear]);
entry.setFieldValue(THIS_YEAR_TOTAL_FIELD, yearTotal[new Date().getFullYear()]);
entry.save();

基本想法是使用 getSubtableSize(subtableId) 取得記錄的子表格行數，並使用 getSubtableFieldValue(subtableId,subtableRowIndex,subtableFieldId) 檢索它們的值。當您開始編輯工作流程程式時，應該能在自動生成的註釋中找到子表格 ID 和欄位 ID 資訊。 您還可以使用 setSubtableFieldValue(subtableFieldId,subtableRootNodeId,value) 將值設定到子表格欄位。subtableRootNodeId 用於指定您所指的子表格行。要查找現有子表格行的 subtableRootNodeId，您可以使用以下呼叫 getSubtableRootNodeId(subtableId,subtableRowIndex)，它將回傳包含 subtableRootNodeId 的整數。 如果需要向子表格加上一行，可以使用負數 subtableRootNodeId 例如 -100，這樣所有設定到相同負數 subtableRootNodeId 的值將應用到同一新子表格行，而設定到不同負數 subtableRootNodeId 例如 -101 的值將建立具有這不同值集的另一行。

Pre-workflow 和 Post-workflow

如果您希望在 Pre-workflow 和 Post-workflow 中取得值，請參考以下範例：

var list = param.getSubtableEntry(AMOUNT_SUBTABLE_ID);
var arr = list.toArray();
response.setStatus('WARN');
for (var i = 0; i < arr.length; i++) {
  response.setMessage('日期: '+arr[i].getNewValue(DATE_FIELD)+', 金額: '+arr[i].getNewValue(AMOUNT_FIELD)+'\r\n');
}

訪問所有紀錄

目前我們提供兩種方式讓您遍歷 query 中的每筆紀錄，分別是使用 getAPIResultsFull 與 getAPIResultList 兩種方法。

  //getAPIResultsFull 範例
  var query = db.getAPIQuery("/workflow-demo/1");
  var results = query.getAPIResultsFull();
  var entry = results.next();
  while(entry) {
    // do something
    entry = results.next();
  }

  //getAPIResultList 範例
  var query = db.getAPIQuery("/workflow-demo/1");
  var results = query.getAPIResultList();
  for(var i = 0; i < results.length; i ++) {
    var entry = result[i];
    // do something
  }

複製記錄

範例連結：從這裡複製和 複製到這裡

複製記錄是我們遇到的最常見的工作流程程式之一。我們撰寫了一個非常簡單的函數來簡化這類操作。假設我們希望查看這個工作表中的一筆紀錄：

透過點擊按鈕，在這個工作表中生成一筆紀錄：

以下是這個動作按鈕的程式碼：

/**

 * AP_Name:wfdemo
 * 主鍵欄位: 1000022

 * S1 子表格主鍵: 1000023
 * T1 子表格主鍵: 1000029

 * 欄位名稱欄位 ID
 * - - - - - - - - - - - --------
 * A: 1000014
 * C: 1000015
 * B: 1000016
 * D: 1000017
 * S1 : 1000018
 * S2 : 1000019
 * S3 : 1000020
 * S4 : 1000021
 * T1 : 1000024
 * T2 : 1000025
 * T3 : 1000026

 */

function copyEntry(nodeId) {
  db.entryCopier(JSON.stringify({
    THIS_PATH:"/workflow-demo/3",
    THIS_NODEID:nodeId,
    NEW_PATH:"/workflow-demo/4",
    COPY:{
      1000030:1000014,// A
      1000031:1000015,// C
      1000032:1000018,// S1
      1000033:1000020 // S3
    }
  }),response);
}

在這裡，您可以看到我們可以透過一個簡單的函數呼叫entryCopier 來完成複製操作。entryCopier 接受一個 JSON字串作為其參數。只需輸入源工作表、目標工作表、我們正在複製的紀錄，以及最重要的是，哪些欄位應映射到哪些欄位。完成映射後，您可以非常輕鬆地建立動作按鈕來從一個工作表複製記錄到另一個工作表。讓我們看另一個範例。 這裡，我們希望將 Lin 從 "CopyFrom" 複製到 "CopyTo"，並將狀態設定為 new。此外，我們還希望記錄建立日期（請忽略本範例中的 $DATE 欄位的使用）。

/**
 * 欄位名稱欄位 ID
 * - - - - - - - - - - - --------
 * From-ID: 1000001
 * From-Name: 1000002
 * To-ID: 1000004
 * To-Name: 1000005
 * 狀態: 1000007
 * 註冊日期: 1000008
 */

function copyEntry(nodeId) {
  db.entryCopier(JSON.stringify({
    THIS_PATH:"/entrycopier/1",
    THIS_NODEID:nodeId,
    NEW_PATH:"/entrycopier/2",
    COPY:{
      // 目標欄位:源欄位
      1000004:1000001, 
      1000005:1000002, 
    }
  }),response);
  // 取得剛才複製的紀錄的 rootNodeId
  var newEntryRootNodeId = response.getRootNodeId();
  // 我們需要建立一個 ApiQuery 來查詢 '/entrycopier/2'
  var toApiQuery = db.getAPIQuery('/entrycopier/2');
  // 取得剛才複製的紀錄
  var newEntry = toApiQuery.getAPIEntry(newEntryRootNodeId);
  newEntry.setFieldValue(1000007, "New");
  var current = new Date();
  newEntry.setFieldValue(1000008, current.getFullYear()+'/' + (current.getMonth()+1) + '/' + current.getDate());
  newEntry.save();
}

接下來，設定動作按鈕並儲存。

然後，只需點擊動作按鈕即可顯示結果。

刪除記錄

您可以使用 query.deleteEntry(nodeId) 來刪除紀錄，若您有多筆紀錄需要刪除，則可透過 query.getAPIResultList() 來遍歷整個 query 刪除資料。

  var query = db.getAPIQuery(pathToForm);
  query.addFilter(1000001, '=', 'To Be Deleted'); //篩出 1000001 的值為 To Be Deleted 的所有紀錄
  var results = query.getAPIResultList();
  for(var i = 0; i < results.length; i ++) { //將篩出的紀錄全數刪除
    var entry = results[i];
    query.deleteEntry(entry.getRootNodeId());
  }

若您要刪除的紀錄大於 1000 筆，則須搭配 setLimitSize 使用，query 預設一次僅能處理 1000 筆資料。

  //假設有 3000 筆資料需要刪除

  var limitSize = 1500; //每個 query 的上限
  var query = db.getAPIQuery(pathToForm);
  query.addFilter(1000001, '=', 'To Be Deleted'); //篩出 1000001 的值為 To Be Deleted 的所有紀錄
  query.setLimitSize(limitSize); //非必要，此為設定 query 最大上限，預設為 1000
  var results = query.getAPIResultList();

  while(results.length > 0) {
    for(var i = 0; i < results.length; i ++) {
      var entry = results[i];
      query.deleteEntry(entry.getRootNodeId());
    }

    //每過 1000 筆資料後重新抓取 query
    var query = db.getAPIQuery(pathToForm);
    query.addFilter(1000001, '=', 'To Be Deleted');
    query.setLimitSize(limitSize);
    results = query.getAPIResultList();
  }

檢查用戶權限

您可以根據將要執行程式的用戶所在的群組進行一些條件處理。一個用戶可以在多個用戶群組中，所以通常我們可以透過呼叫 user.isInGroup(groupName) 來判斷用戶是否在該用戶群組中。以下是一個典型的使用範例，這段程式設計為 Pre-workflow，但 user 物件和 isInGroup 呼叫可以在所有類型的工作流程中使用，除了 Daily Workflow，它是由系統觸發的。

if(!user.isInGroup('SYSAdmin')){// 檢查用戶是否為 SYSAdmin
  response.setStatus('INVALID');// 如果不是，則不儲存記錄
  response.setMessage('您沒有權限進行此操作。');// 並顯示一筆訊息
}

發送電子郵件通知

有時候您可能希望根據一組條件發送電子郵件通知，或者您希望真正自訂您的通知訊息內容。您可以為此撰寫伺服器端 JavaScript 工作流程。這是發送電子郵件的程式碼，非常簡單：

// 省略...先檢索記錄物件

var name=entry.getFieldValue(1001426);
var email=entry.getFieldValue(1001428);
var title=entry.getFieldValue(1001386);

mailer.compose(
  email,// 收件人
  null, // 副本
  'support@example.com',// 回覆地址
  'Acme, Inc.',// 顯示的發件人
  title,
  '嗨 '+name+',

我們已收到您的銷售訂單，'+
  '並將很快處理您的訂單。

'+
  '您可以在 https://www.ragic.com/example/1 查看您的訂單詳情。

'+
  '謝謝。


最好的祝福,

Sophia, 銷售經理

Acme, Inc.'
);

// mailer.attach(myURL); // 您可以使用 .attach 來附加來自 URL 的內容

mailer.send();

請注意，如果您希望將電子郵件發送給多個收件人，只需用逗號分隔每個電子郵件地址。對於附件，您可以使用 mailer.attach(myURL); 來附加 Ragic 上的紀錄，使用記錄的 URL。例如，這是 Ragic 上的紀錄 URL（始終忽略哈希後的 URL）：

https://www.ragic.com/wfdemo/workflow-demo/2/9

這是其 HTML 友善列印版 URL：

https://www.ragic.com/wfdemo/workflow-demo/2/9.xhtml

這是其 Excel 版本 URL：

https://www.ragic.com/wfdemo/workflow-demo/2/9.xlsx

您還可以使用郵件合併 URL，例如，cid 是郵件合併的 ID，當嘗試下載郵件合併文件時，您可以在 URL 中取得 cid：

https://www.ragic.com/wfdemo/workflow-demo/2/9.custom?rn=9&cid=1

我們對您可以發送的電子郵件數量有限制。因此請合理發送！如果您對電子郵件發送配額有任何疑問，請發送電子郵件至 support@ragic.com。

建立和取消簽核

您可以透過在工作表中加上 Post-workflow 程式來啟動或取消記錄的簽核。首先，在設計模式中設定簽核步驟。

現在，在 Post-workflow 中設定簽核詳細資訊

function autoStartApprover() {
  var signers = [];
  signers.push({
    'stepIndex':'0',
    'approver':'kingjo@ragic.com',
    'stepName':'START'
  });
  signers.push({
    'stepIndex':'1',
    'approver':'HR0000@hr.hr',
    'stepName':'HR'
  });

  approval.create(JSON.stringify(signers));
}

autoStartApprover();

結果

{
  'stepIndex':'0',
  'approver':'kingjo@ragic.com',
  'stepName':'START'
}

是您應提供的參數格式。

stepIndex : 用於指明簽核的步驟，從零開始。 approver :用於指明誰可以簽核此步驟。 stepName : 用於設定簽核步驟名稱。

如果參數格式有誤或您提供的簽核人不符合設計模式中設定的規則，簽核將不會建立。

在這個範例中，如果您給第二步提供參數如下：

{
  'stepIndex':'1',
  'approver':'kingjo@ragic.com',
  'stepName':'HR'
}

那麼它將失敗，因為 kingjo@ragic.com 不在 HR 群組中。我們還提供了三種特殊格式，用於根據您的公司樹動態決定簽核人員。您可以參考此連結了解更多資訊。

$DS : 簽核人將設定為用戶的直屬主管。 $SS :簽核人將設定為用戶主管的主管。 $DSL : 簽核人將設定為前一個簽核人的主管。參數格式如下：

{
  'stepIndex':'1',
  'approver':'$DSL',
  'stepName':''
}

當使用這些特殊格式時，您不需要提供非空的 stepName。注意：如果特殊格式中的用戶不符合您在設計模式中設定的規則，該簽核將不會建立。

發送手機應用通知

除了電子郵件通知，您還可以發送手機應用通知。如果用戶在其行動裝置上安裝了 iOS 應用或 Android 應用，則會向其發送通知。電子郵件引用的是您在 Ragic 帳戶中註冊的用戶電子郵件地址。例如：

mailer.sendAppNotification("mike@example.com","測試手機通知");

如果您希望用戶在點擊此通知時被重定向到指定記錄，您應提供要重定向到的表單路徑（例如：/forms/1）和記錄 ID。呼叫應如下所示：

mailer.sendAppNotification("mike@example.com","測試手機通知","/forms/1",12);

簽核和其他記錄資訊

您可以首先對從 db.getAPIQuery 取得的查詢物件發出以下命令，以包括完整的紀錄資訊：

query.setIfIncludeInfo(true);

然後您可以透過以下方式取得記錄的簽核資訊：

entry.getFieldValue('_approve_status');// 取得當前簽核狀態
entry.getFieldValue('_approve_next');// 取得下一個應簽核此記錄的人
entry.getFieldValue('_create_date');// 取得記錄的建立日期
entry.getFieldValue('_create_user');// 取得記錄的建立用戶電子郵件

簽核狀態將顯示 F 表示已簽核，REJ 表示拒絕，P 表示處理中。

下載和上傳檔案

發送 HTTP 請求

您可以向 URL 發送 HTTP GET/POST/DELETE/PUT 請求並取得回傳結果：

util.getURL(String urlstring)
util.postURL(String urlstring,String postBody)
util.deleteURL(String urlstring)
util.putURL(String urlstring,String putBody)

變數 util 是預定義的。 如果您需要忽略當前 HTTP 請求的 SSL 憑證檢查，可以在發送請求前加上以下程式碼：

util.ignoreSSL()

此外，您可以呼叫 util.setHeader(String name,String value) 設定 HTTP 標頭。util.removeHeader(String name) 用於移除標頭。

下載和上傳檔案

您可以透過URL下載檔案並且取得檔案名稱：

util.downloadFile(fileUrl);
//fileUrl：檔案的來源URL
//該方法回傳的值：下載下來的檔名 

當您將檔案下載至資料庫後，可以使用setFieldValue將檔名填回檔案欄位，即可在表單中預覽或是將檔案下載至本機。

var fileFieldId = 1000087;
var fileName = util.downloadFile(fileUrl);
entry.setFieldValue(1000087, fileName);
entry.save();

您也可以上傳檔案至目標網址並取得檔案名稱：

util.postFile(sourceFileUrl, destinationUrl)
//sourceFileUrl：檔案的來源URL
//destinationUrl：檔案要上傳的目標URL
//該方法回傳的值：上傳到資料庫的檔名

關於取得完整檔案、圖片連結的方法可以參閱這篇教學。

呼叫其他表單的 workflow

使用 workflow 修改其他表單的資料時，預設是不會觸發該表單的 workflow。如果您需要觸發該表單的 post-workflow 或是 pre-workflow，可以使用以下程式碼：

var query = db.getAPIQuery(pathToForm);
var entry = query.getAPIEntry(recordId);
//執行某些動作...

entry.setIfExecuteWorkflow(true);
entry.save();

API 參考

此處列出的預定義系統全域變數可以直接訪問，無需定義。

  {
    'stepIndex': 簽核的步驟 - 從 0 開始, 
    'approver' : 簽核人的電子郵件, 
    'stepName' : 簽核人的姓名或職稱, 
  }

  範例 "單步驟簽核人" : 
  wfSigner push({
    'stepIndex':'1',
    'approver':'kingjo@ragic.com',
    'stepName':'Jo'
  })