后端 JSF 函数开发说明
JSF 函 数采用 JavaScript 作为脚本语言,支持 ES 2017 语法。脚本中可以使用 JavaScript 基本能力、Backend SDK 以及 qiqi 内置模块。
JSF按使用场景,有不同的上下文变量和返回值, 目前backend仅支持流程调用这一种后端场景函数, 实际在编写JSF函数时,只需要提供函数体即可。
文档导航
| 内容 | 文档 |
|---|---|
| 数据查询、增删改、GraphQL、内部 API、邮件和批处理 | Backend SDK |
| 调用外部 HTTP/HTTPS 接口(目前仅本地化部署支持) | qiqi.http |
| 对象、集合和数值工具函数 | qiqi.util |
| 日期处理和精确计算 | qiqi.dayjs 与 qiqi.math |
内置模块使用方式
内置模块支持两种使用方式:
- 直接通过全局对象调用:
qiqi.util、qiqi.dayjs、qiqi.math、qiqi.http。 - 当脚本以
import开头时,通过@qiqi/util、@qiqi/dayjs、@qiqi/math、@qiqi/http导入。util、dayjs、http支持默认导入和具名导入,math使用默认导入。
qiqi.http目前 仅本地化部署环境支持,其他部署形态暂不可用。
import util, { isEmpty } from '@qiqi/util';
import math from '@qiqi/math';
if (isEmpty(variables)) {
return math.add(0.1, 0.2).value;
}
return util.keys(variables);
流程场景函数
流程场景函数,是在一个单据执行的工作流程过程中,可以调用的函数,比如单据生效后调用,单据弃审后调用等。
场景函数的模板:
function ${funcName}(userContext, objectType, objectId, variables) {
${jsfContent}
}
场景函数的参数说明
| 字段名称 | 字段说明 | 类型 | 必填 | 备注 |
|---|---|---|---|---|
| userContext | 只读当前用户上下文对象 | object | Y | 当前调用的上下文对象, 不需要用户传递,为只读类型, 字段说明参考运行上下文 |
| objectType | 当前流程的单据对象类型 | string | Y | - |
| objectId | 当前流程的单据对象ID | string | Y | - |
| variables | 流程中设置的变量 | object | 它是一个 KV 结构, key为变量名,value为变量值对象(例如: {"var1": {"type": "String", "value": "var1Value"}}) | |
| qiqi | 内置模块集合 | object | Y | 可以直接使用,例如 qiqi.util.isNumber(1)、qiqi.math.add(0.1, 0.2).value,参考内置模块使用方式 |
场景函数返回值规则
返回值说明:通常的返回值格式如下:
{
status: "success|error|warning", //函数是否成功执行的状态
code: "", //如果执行不成功时,提供的错误码
message: "", //如果执行不成功时,提供的错误提示信息
description: "", //如果执行不成功时,提供的错误详细描述
data: null, //成功时需要返回的数据对象
args: null, //如果出错时,需要返回的其他错误数据
}
返回值属性说明:
| 字段名称 | 字段说明 | 类型 | 必填 | 备注 |
|---|---|---|---|---|
| status | 执行函数状态 | string | Y | 函数是否成功执行的状态, 取值为 success/error/warning |
| code | 错误码 | string | - | 如果执行不成功时,提供的错误码 |
| message | 错误信息 | string | - | 如果执行不成功时,提供的错误提示信息 |
| description | 错误描述 | string | - | 如果执行不成功时,提供的错误详细描述 |
| data | 返回的数据 | any | - | 成功时需要返回的数据对象 |
| args | 错误附加参数 | map | - | 如果出错时,需要返回的其他错误数据 |
| logs | 函数中输出的日志信息 | array | - | 函数中输出的日志信息 |
如果 JSF 函数体没有返回数据,或者返回的数据中没有 status 字段,则默认函数执行成功,并把返回值放入 data:
return {status: "success", data: {id: "123"}}; 等价于 return {id: "123"};。
场景函数示例:
a) 收款单增加额外的逻辑检查,如果收款部门为’AA'并且收款金额>100时,检查不通过,打回单据,并显示错误信息为“XX部门收款不能超过100"。
if (objectType != 'Receipt') {
return;
}
var result = await query(objectType, ['id'], `id = '${objectId}' and ownerDept.name = 'AA' and amount > 100`);
if (result.status != 'success') {
return result;
}
if (result.data.length == 1) {
return {
status: 'error',
message: 'AA部门收款不能超过100'
};
}
return true;
说明: objectType, objectId为参数,
query为 Backend SDK 函数
b) 执行一个插入Comment的操作及删除自动插入的评论操作
return create('Comment', {
objectType: objectType,
objectId: objectId,
content: '这是一个自动增加的评论'
});
c) 执行一个删除自动添加的评论的操作
var result = await query('Comment', ['id'], `objectType = '${objectType}' and objectId = '${objectId}' and content='这是一个自动增加的评论'`);
if (result.status != 'success') {
return result;
}
if(result.data.length != 0){
return remove('Comment', result.data[0].id);
}
d) 发票增加额外弃审检查,发票金额>1000,不允许弃审,并提供弃审错误信息“发票金额大于1000,不允许弃审”。
if (objectType != 'Invoice') {
return;
}
var result = await query(objectType, ['id'], `id = '${objectId}' and amount > 1000`);
if (result.status != 'success') {
return result;
}
if (result.data.length == 1) {
return {
status: 'error',
message: '发票金额大于1000,不允许弃审'
};
}
return true;
运行上下文
上下文对象为JSF函数运行时上下文信息对象, 它包括以下内容:
{
rootRequestId: string; //根请求ID, 如果当前请求是别的请求触发的,保存的别的请求的requestId, 以便输出日志时,用来跟踪调用链
requestId: string; //当前请求ID,当前请求的唯一标识;相同requestId以相同参数调用时,后端只响应第一次成功调用结果
tenantId: string; //当前租户ID
userId: string; //当前用户ID
departmentId: string; //当前用户所属部门ID
currentRoleId: string; //当前用户使用的角色ID
currentOrgId: string; //当前的组织ID
isDisableDataScope: boolean; //是否禁用数据权限
roles: Map<string, boolean>; //当前用户具有的角色信息, key为角色ID, value表示该角色是否有管理员身份
}