Javascript 工作引擎

單一條件

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

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

複製記錄

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

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

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

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

/**

 * 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();
}

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

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

檢查用戶權限

您可以根據將要執行程式的用戶所在的群組進行一些條件處理。一個用戶可以在多個用戶群組中，所以通常我們可以透過呼叫 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

該方法回傳的值：下載下來的檔名

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

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 參考

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

db.getAPIQuery

entry

response

user

mailer

util

account

param

approval

approvalParam