后端 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表示该角色是否有管理员身份
}