Backend SDK

Backend SDK 是 JSF 脚本访问 77hub 数据和内部服务的主要方式。脚本结构、上下文和返回值规则见后端 JSF 函数开发说明。

目前backend sdk支持以下函数

查询对象：query(objectType: string, fields: string[], criteriaStr: string, sorts: object, offset: number, limit: number, asAdmin: boolean, headers: Map<string, string>): Promise<RestResponse>
新增对象：create(objectType: string, data: object, asAdmin: boolean, headers: Map<string, string>): Promise<RestResponse>
修改对象： update(objectType: string, data: object, asAdmin: boolean, headers: Map<string, string>): Promise<RestResponse>
删除对象： remove(objectType: string, id: string, asAdmin: boolean, headers: Map<string, string>): Promise<RestResponse>
Gql查询：graphql(gql: string, asAdmin: boolean, headers: Map<string, string>): Promise<RestResponse>
通用api调用： restapi(appName: string, method: string, url: string, data: object, asAdmin: boolean, headers: Map<string, string>): Promise<RestResponse>
发送邮件： emailTo(data: object, asAdmin: boolean, headers: Map<string, string>): Promise<RestResponse>
新增变更单：change(objectType: string, data: object, headers: Map<string, string>): Promise<RestResponse>
异步批量触发 JSF 函数：batch(objectType: string, execUserId: string, criteriaStr: string, bindVars: Record<string, any>, batchSize: number, jsfDefName: string, remarks: string, headers: Map<string, string>): Promise<RestResponse>

其中返回值 RestResponse对象结构为：

{
    status: string;
    code: string;
    message: string;
    description: string;
    data: any;
    args: any;
}

字段说明如下：

字段名称	字段说明	类型	必填	备注
status	执行函数状态	string	Y	函数是否成功执行的状态，取值为 `success/error/warning`
code	错误码	string	-	如果执行不成功时，提供的错误码
message	错误信息	string	-	如果执行不成功时，提供的错误提示信息
description	错误描述	string	-	如果执行不成功时，提供的错误详细描述
data	返回的数据	any	-	成功时需要返回的数据对象
args	错误附加参数	map	-	如果出错时，需要返回的其他错误数据

查询对象 query:

query(objectType: string, fields: string[], criteriaStr: string, sorts: object, offset: number, limit: number, asAdmin: boolean, headers: Map<string, string>): Promise<RestResponse>

参数说明：

字段名称	字段说明	类型	必填	备注
objectType	查询对象名	string	Y
fields	查询的字段列表	string[]	Y	至少指定一个字段
criteriaStr	查询条件表达式	string	-	指定查询的eql条件表达式, 与postgresql sql条件表达式一致，只字段使用的是对象属性名，并且支持级联（a.b.c)，不指定条件表示无条件查询
sorts	排序	object	-	要排序的字段列表，例如：`[{name: "name"}, {name: "createdTime", isDesending: true}]`
offset	查询起始行	integer	-	从0开始的起始行，不指定表示从0开始
limit	返回最大的行数	integer	-	不指定表示返回所有记录，但受系统最大行10000限制
asAdmin	以管理员权限运行	boolean	-	如果不指定或者为false，表示以当前用户身份执行
headers	附加请求头	Map<string,string>	-	目前支持 `Ignore-Warn=true`，表示忽略警告错误

成功执行后返回值中data值为查询的对象的数据列表

执行 query('User', ['id', 'name', 'createdTime'], "id='1'") 返回值示例:

{
  "status": "success",
  "code": null,
  "message": null,
  "description": null,
  "data": [
    {
      "id": "1",
      "name": "小企",
      "createdTime": 1626916982389
    }
  ],
  "args": null
}

新增对象 create:

create(objectType: string, data: object, asAdmin: boolean, headers: Map<string, string>): Promise<RestResponse>

参数说明：

字段名称	字段说明	类型	必填	备注
objectType	新增对象名	string	Y
data	新增对象结构化数据	object	Y	为一个Json对象，包括key为字段名，值为字段值的数据项
asAdmin	以管理员权限运行	boolean	-	如果不指定或者为false，表示以当前用户身份执行
headers	附加请求头	Map<string,string>	-	目前支持 `Ignore-Warn=true`，表示忽略警告错误

成功执行后返回值中data值新增加的对象的ID

执行 create('Role', {code: '001', name: 'manager'}) 返回值示例:

{
  "status": "success",
  "code": null,
  "message": null,
  "description": null,
  "data": "NEP8HV515KG0008",
  "args": null
}

执行 create('User', {code: '001', name: 'testuser'}) 执行出错返回值示例:

{
  "status": "error",
  "code": "0010",
  "message": "提交的数据存在问题",
  "description": "Object validation found 2 problems, error codes: [0011, baseapp-200108]",
  "data": null,
  "args": {
    "problems": {
      "default": {
        "ERROR": [
          {
            "fieldPath": "department",
            "type": "error",
            "code": "0011",
            "message": "字段的值必须指定"
          },
          {
            "fieldPath": "jobRelationships",
            "type": "error",
            "code": "baseapp-200108",
            "message": "用户任职记录中必须包含一条主职记录",
            "args": {
              "jobRelationships": "用户任职记录中必须包含一条主职记录"
            }
          }
        ]
      }
    }
  }
}

修改对象 update:

update(objectType: string, data: object, asAdmin: boolean, headers: Map<string, string>): Promise<RestResponse>

参数说明：

字段名称	字段说明	类型	必填	备注
objectType	新增对象名	string	Y
data	修改对象结构化数据	object	Y	为一个Json对象，包括key为字段名，值为字段值的数据项, 其中id必须指定，表示要修改的对象ID
asAdmin	以管理员权限运行	boolean	-	如果不指定或者为false，表示以当前用户身份执行
headers	附加请求头	Map<string,string>	-	目前支持 `Ignore-Warn=true`，表示忽略警告错误

执行 update('Role', {id: 'NEP8HV515KG0008', code: '001', name: 'manager2'}) 返回值示例:

{
  "status": "success",
  "code": null,
  "message": null,
  "description": null,
  "data": "",
  "args": null
}

删除对象 remove:

remove(objectType: string, id: string, asAdmin: boolean, headers: Map<string, string>): Promise<RestResponse>

参数说明：

字段名称	字段说明	类型	必填	备注
objectType	新增对象名	string	Y
id	删除的对象的ID	string	Y
asAdmin	以管理员权限运行	boolean	-	如果不指定或者为false，表示以当前用户身份执行
headers	附加请求头	Map<string,string>	-	目前支持 `Ignore-Warn=true`，表示忽略警告错误

执行 remove('Role','NEP8HV515KG0008') 返回值示例:

{
  "status": "success",
  "code": null,
  "message": null,
  "description": null,
  "data": "",
  "args": null
}

执行 remove('Role','NEP8HV515KG0008') 出错返回值示例:

{
  "status": "error",
  "code": "0100",
  "message": "对象不存在或已被删除",
  "description": "entity Role not found: NEP8HV515KG0008",
  "data": null,
  "args": {
    "objectType": "Role",
    "objectId": "NEP8HV515KG0008"
  }
}

Gql查询 graphql:

graphql(gql: string, asAdmin: boolean, headers: Map<string, string>): Promise<RestResponse>

参数说明：

字段名称	字段说明	类型	必填	备注
gql	gql查询语法	string	Y
asAdmin	以管理员权限运行	boolean	-	如果不指定或者为false，表示以当前用户身份执行
headers	附加请求头	Map<string,string>	-	目前支持 `Ignore-Warn=true`，表示忽略警告错误

执行 graphql('{User{id,name}}') 返回值示例:

{
  "status": "success",
  "code": null,
  "message": null,
  "description": null,
  "data": {
    "User": [
      {
        "id": "1",
        "name": "小企"
      }
    ]
  },
  "args": null,
  "logs": []
}

执行 graphql('{User{id,name1}} 出错返回值示例:

{
  "status": "error",
  "code": "400",
  "message": "查询出错",
  "description": "[{\"message\":\"Validation error of type FieldUndefined: Field 'name1' in type 'UserSchemaType' is undefined\",\"locations\":[{\"line\":1,\"column\":10}],\"description\":\"Field 'name1' in type 'UserSchemaType' is undefined\",\"validationErrorType\":\"FieldUndefined\"}]",
  "data": null,
  "args": null,
  "logs": []
}

通用api调用 restapi:

restapi(appName: string, method: string, url: string, data: object, asAdmin: boolean, headers: Map<string, string>): Promise<RestResponse>

该方法为支持特定的场景使用的方法，可以访问租户服务的api, 调用成功后，返回值的data中为接口实际的返回结果。

参数说明：

字段名称	字段说明	类型	必填	备注
appName	restapi所在的服务名,eg: baseapp	string	Y
method	请求类型：get,post,put,delete	string	Y
url	restapi相对于服务的url, 比如："/User/1"	string	Y
data	请求数据	object	-	`get`、`delete` 请求会将键值对作为 URL 查询参数，其他请求会将其作为 JSON 请求体
asAdmin	以管理员权限运行	boolean	-	如果不指定或者为false，表示以当前用户身份执行
headers	附加请求头	Map<string,string>	-	目前支持 `Ignore-Warn=true`，表示忽略警告错误

执行 restapi('graphql', 'post', '/', {query:'{User{id,name}}'}) 返回值示例:

{
  "status": "success",
  "code": null,
  "message": null,
  "description": null,
  "data": {
    "data": {
      "User": [
        {
          "id": "1",
          "name": "小企"
        }
      ]
    },
    "errors": []
  },
  "args": null,
  "logs": []
}

发送邮件 emailTo

emailTo(data: object, asAdmin: boolean, headers: Map<string, string>): Promise<RestResponse>

参数说明：

字段名称	字段说明	类型	必填	备注
data	邮件内容	object	Y
asAdmin	以管理员权限运行	boolean	-	如果不指定或者为false，表示以当前用户身份执行
headers	附加请求头	Map<string,string>	-	目前支持 `Ignore-Warn=true`，表示忽略警告错误

data参数说明：

字段名称	字段说明	类型	必填	备注
objectType	单据对象	string	Y
objectId	单据id	string	Y
receiverDefIds	接收人角色ids	string	N	“,”分隔
userIds	接收用户ids	string	N	“,”分隔
purposeId	邮件用途	string	Y	MailPurpose.billIssued-出账；MailPurpose.dunning-催缴； MailPurpose.share-分享
messageTmplId	消息模板	boolean	Y
subject	邮件主题	string	Y
content	邮件内容	string	Y
remarks	备注	string	N
attachmentIds	附件ids	string	N	“,”分隔
billTypeTemplateId	打印模板id	string	N
mailSenderId	发件人邮件账户	string	N
isFeedbackRead	是否需要反馈已读	boolean	Y

新增变更单 change:

change(objectType: string, data: object, headers: Map<string, string>): Promise<RestResponse>

change 函数支持：自定义单据新增变更单

参数说明：

字段名称	字段说明	类型	必填	备注
objectType	新增变更单对象	string	Y
data	对象结构化数据	object	Y	数据以增量形式来提交，其中baseBillId 和baseBillItemId无需指定，系统会自动根据id 补齐，和修改接口参数一致
headers	附加请求头	`Map<string,string>`	-	目前支持 `Ignore-Warn=true`，表示忽略警告错误

执行 change('CsZiDingYiBianGengDan01', {id: 'NEP8HV515KG0008', code: '001', name: 'manager2'}) 返回示例值：

{
    "status":"success",
    "code":null,
    "message":null,
    "description":null,
    "data":"SXTF6662XC500EH", // 新增的变更单id
    "args":null
}

执行 change('CsZiDingYiBianGengDan01', {id: 'NEP8HV515KG0008', code: '001', name: 'manager2'}) 执行出错返回值示例:

{
    "status":"error",
    "code":"500",
    "message":"服务器端运行您的请求出现错误！",
    "description":"post http://inventory/inventory/PickingApply/changeBill: NoSuchElementException No value present",
    "data":null,
    "args":null
}

异步批量触发jsf函数 batch:

batch(objectType: string, execUserId: string, criteriaStr: string, bindVars: Record<string, any>, batchSize: number, jsfDefName: string, remarks: string, headers: Map<string, string>): Promise<RestResponse>

异步批量触发jsf函数。当jsf 函数批量处理大量数据时，可以考虑使用此函数来拆分，防止jsf 函数执行超时。

参数说明：

字段名称	字段说明	类型	必填	备注
objectType	jsf 待处理的对象	string	Y
execUserId	执行人	string	Y	以执行人的身份触发jsf 函数
criteriaStr	包含占位符的gql查询条件	string	Y
bindVars	查询条件中的占位符绑定变量	`Record<string, any>`	-
batchSize	每批数据量大小	number	-	默认值10
jsfDefName	jsf 函数名	string	Y	异步批量调用的jsf 函数
remarks	备注	string	-
headers	附加请求头	`Map<string,string>`	-	目前支持 `Ignore-Warn=true`，表示忽略警告错误

执行 batch("CsZiDingYiBianGengDan01", "GK63GT50E7U0032", "billFullStatus=:billStatusTest", { billStatusTest: "BillStatus.draft" }, 1, "testJsfDSL", "测试一下", null) 返回示例值：

{
    "status":"success",
    "code":null,
    "message":null,
    "description":null,
    "data":"J1SF6662XC5007X", // 用于查询异步任务的执行情况
    "args":null
}

可以根据返回的J1SF6662XC5007X 使用 GQL 查看异步任务的执行情况

{
  JsfBatch(criteriaStr:"id='J1SF6662XC5007X'") {
    id
    backlogNbr // 按criteriaStr查询出的符合条件的记录总数
    asyncTaskId
    asyncTask{
      beanName
      params
      isCompleted
      successRate
      asyncTaskItems{
        batchNo
        lastErrorMsg
      }
    }
   }
}

执行 batch("CsZiDingYiBianGengDan01", "GK63GT50E7U0032", "billFullStatus=:billStatusTest", { billStatusTest: "BillStatus.draft" }, 1, "testJsfDSL", "测试一下", null) 执行出错返回值示例:

{
    "status":"error",
    "code":"500",
    "message":"服务器端运行您的请求出现错误！",
    "description":"post http://baseapp/baseapp/JsfBatch: StringIndexOutOfBoundsException String index out of range: -1",
    "data":null,
    "args":null
}

查询对象 query:​

新增对象 create:​

修改对象 update:​

删除对象 remove:​

Gql查询 graphql:​

通用api调用 restapi:​

发送邮件 emailTo​

新增变更单 change:​

异步批量触发jsf函数 batch:​

查询对象 query:

新增对象 create:

修改对象 update:

删除对象 remove:

Gql查询 graphql:

通用api调用 restapi:

发送邮件 emailTo

新增变更单 change:

异步批量触发jsf函数 batch: