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