用户手册_04主数据星瀚适配器
[TOC]
# 引言
# 编写目的
本文是金蝶天燕主数据星瀚适配器v7.5（以下对主数据星瀚适配器简称MADP）用户操作手册。为客户深入了解主数据星瀚适配器的功能、操作步骤以及注意事项等提供帮助。
# 平台概述
# 应用菜单
| 云 | 应用 | 一级功能 | 二级子功能 | 功能简述 |
|---|---|---|---|---|
| 天燕数据管理云 | 主数据星瀚适配器 | 首页 | 快速发起卡片 | 在主数据星瀚适配器首页自由定义入口的快捷卡片 |
| 天燕数据管理云 | 主数据星瀚适配器 | 首页 | 消息中心卡片 | 在主数据星瀚适配器首页自由定义消息提醒卡片 |
| 天燕数据管理云 | 主数据星瀚适配器 | 首页 | 单据统计卡片 | 在主数据星瀚适配器首页自由定义所需要展示的基础资料或单据的统计卡片 |
| 天燕数据管理云 | 主数据星瀚适配器 | 首页 | 自定义卡片(主数据质量) | 在主数据星瀚适配器页摆放有关的监控统计图及表格卡片 |
| 天燕数据管理云 | 主数据星瀚适配器 | 同步配置 | 数据映射配置 | 数据映射配置是为了星瀚基础资料与外部API报文字段对应关系以及对发送和接收相关的配置。 |
| 天燕数据管理云 | 主数据星瀚适配器 | 同步配置 | 接收服务API | 定义主数据星瀚适配器的相关服务。 |
| 天燕数据管理云 | 主数据星瀚适配器 | 集成调度 | 调度任务类名 | 主数据星瀚适配器系统预置的处理插件，可扩展。 |
| 天燕数据管理云 | 主数据星瀚适配器 | 集成调度 | 调度计划 | 主数据星瀚适配器系统内的调度计划，通过设定时间规则，执行调度作业。完成数据的定时发送，以及其它类型调度作业的执行。 |
| 天燕数据管理云 | 主数据星瀚适配器 | 集成调度 | 调度作业 | 主数据星瀚适配器系统内的数据同步调度作业，执行向外部应用系统下发数据的任务。 |
| 天燕数据管理云 | 主数据星瀚适配器 | 集成日志 | 同步日志 | 记录每一条数据同步的日志，数据流向的类型包含：发送、接收。 |
| 天燕数据管理云 | 主数据星瀚适配器 | 集成日志 | 服务日志 | 记录主数据星瀚适配器的API服务被调用时和向外发送发起请求时的日志。 |
| 天燕数据管理云 | 主数据星瀚适配器 | 基础配置 | 插件注册 | 解决在数据发送和接收中适应各个系统的认证、报文以及个性化业务场景，适配器支持在数据同步过程中干预数据和收发报文。 |
| 天燕数据管理云 | 主数据星瀚适配器 | 基础配置 | 客户端 | 对接收系统API相关参数的配置，支持自定义支持明文、加密的参数。 |
| 天燕数据管理云 | 主数据星瀚适配器 | 待同步数据 | 星瀚适配器被等待向外发送的缓冲区数据。 |
# 基本操作
| 序号 | 名称 | 功能说明 |
|---|---|---|
| 1 | 新增 | 形式：列表或单据详情页面按钮。 增加一条新数据。 |
| 2 | 提交 | 形式：列表或单据详情页面按钮。 未定义工作流时，将数据状态变更为已提交。 已定义工作流时，将数据状态变更为已提交，同时提交到工作流程内。 |
| 3 | 撤回 | 形式：列表或单据详情页面按钮。 提交的反向动作。 未定义工作流时，将数据状态变更为暂存。 已定义工作流时，且流程第一个节点尚未处理时，允许撤回。 |
| 4 | 审核 | 形式：列表或单据详情页面按钮，或工作流中最后一个节点的同意按钮。 未定义工作流时，将数据状态变更为已审核。 已定义工作流时，则流程正常流转结束后变更为已审核。 |
| 5 | 反审核 | 形式：列表或单据详情页面按钮。 将数据状态变更为暂存。 |
| 6 | 禁用 | 形式：列表或单据详情页面按钮。 将使用状态从启用变更为禁用。 |
| 7 | 启用 | 形式：列表或单据详情页面按钮。 将使用状态从禁用变更为启用。 |
| 8 | 删除 | 形式：列表或单据详情页面按钮。 物理删除一条记录。 删除数据时，平台将校验数据引用关系，被删除数据（通常指基础资料）如果被其它基础资料或单据引用，则不能删除。 |
| 9 | 保存 | 形式：单据详情页面按钮。 保存新增或修改后的记录，保存时需通过当前基础资料或单据的保存校验规则，例如必录项以及插件逻辑的校验。 |
| 10 | 退出 | 形式：列表或单据详情页面按钮。 退出当前页面。 |
| 11 | 刷新 | 形式：列表或单据详情页面按钮。刷新显示当前页面最新状态。 |
# 首页布局
MADP应用位于【天燕数据管理云】，点击【主数据星瀚适配器】打开首页面。
图1-1
MADP首页为聚合页面，默认显示公共首页，每个用户点击右侧工具栏，可按照个性化需要自定义个性化首页方案。
首页可放置多种卡片，可拖动改变卡片位置，或调整卡片打下。首页卡片包括快捷方式、单据统计卡片、统计图、分析表、待办任务、通知消息等。
# 首页设置
- 调整布局：参见下图，点击右侧首页菜单栏【调整布局】，可调整首页布局。在调整布局过程中，点击下方“添加卡片”可增加自定义卡片，设置个性化首页。
- 切换：参见下图，点击右侧首页菜单栏【切换】，可在个性方案和默认方案之间切换。
- 刷新：参见下图，点击右侧首页菜单栏【刷新】，可刷新当前应用的首页面。
- 设为默认：参见下图，点击右侧首页菜单栏【设为默认】，可将当前页面布局设为当前用户的默认方案。
# 首页卡片
快捷卡片：首页为聚合页面，每个用户可按照个性化需要自定义多种卡片，包括快速发起卡片，单据统计卡片，统计图，分析表，待办任务，通知消息等。大大增强了用户的使用体验。
- 速发起卡片：用户自定义常用快捷方式，点击可打开一个功能的列表或新增页面。
- 自定义卡片：主数据应用内预置了多种统计图表类卡片，用户可根据需要添加到个性化首页中。
# 主数据星瀚适配器工作流程图
# 数据实时发送流程图
# 数据异步发送流程图
# 同步配置
# 数据映射配置
用途：数据映射配置是为了星瀚基础资料与外部API报文字段对应关系以及对发送和接收相关的配置。
入口：点击菜单【同步配置】-【数据映射配置】进入“数据映射配置”列表页面。
- 基本约束说明：无
# 新增
点击【新增】按钮，打开一个新增页面。
- 新增页面：
- 字段说明-基本信息：
| 序号 | 字段名称 | 是否必录 | 类型 | 功能说明 |
|---|---|---|---|---|
| 1 | 星瀚基础资料 | 是 | 基础资料 | 该字段为数据映射配置最重要的字段，选择任意一个星瀚基础资料，对这个基础资料进行数据同步配置 |
| 2 | 同步类型 | 是 | 下拉 | 同步类型包括：发送并接收、发送、接收，对星瀚基础资料支持同步类型定义 |
| 3 | 配置编码 | 是 | 文本 | 编码必须唯一。 |
| 4 | 配置名称 | 是 | 文档 | 填写星瀚基础资料名称，有助于在后续引用的识别。 |
| 5 | 配置说明 | 是 | 文本 |
- 字段说明-配置信息-数据映射：
点击【字段选择】按钮弹出星瀚基础资料对应字段，将需要同步的字段进行勾选。
| 序号 | 字段名称 | 是否必录 | 类型 | 功能说明 |
|---|---|---|---|---|
| 1 | 字段编码 | 是 | 文本 | 原字段标识，选择字段后自动填写，不能修改 |
| 2 | 字段 | 否 | 文本 | 原字段名称，选择字段后自动填写，不能修改 |
| 3 | 接口标识 | 否 | 文本 | 默认原字段标识，选择字段后自动填写，可根据接口定义属性自由修改 |
| 4 | 是否发送 | 否 | 复选框 | 发送报文只处理已勾选的字段进行报文拼装。 |
| 5 | 发送默认值 | 否 | 文本 | 发送报文中，如果原数据没有值并且勾选是否发送，将赋默认值 |
| 6 | 是否接收 | 否 | 复选框 | 接收报文只处理已勾选的字段进行报文解析。 |
| 7 | 接收默认值 | 否 | 文本 | 接收报文中，如果报文属性没有值并且勾选是否接收，将赋默认值 |
| 8 | 唯一字段标识 | 否 | 下拉 | 下拉包括：内码、编码，当字段为基础资料时，需要选择交互唯一标识，在报文解析时，先获取报文内交互标识和值去查找对应数据，如果找不到会返回数据找不到的错误 |
| 9 | 字段类型 | 否 | 下拉 | 原字段类型，选择字段后自动填写，不能修改 |
| 10 | 是否单据体字段 | 否 | 复选框 | 标记原字段是否为单据体字段，选择字段后自动填写，不能修改 |
| 11 | 单据体标识 | 否 | 文本 | 当是否单据体字段打开时，会显示对应单据体标识，选择字段后自动填写，不能修改 |
| 12 | 是否基础资料 | 否 | 复选框 | 标记原字段类型是否为基础资料，选择字段后自动填写，不能修改 |
| 13 | 基础资料类型编码 | 否 | 文本 | 当是否基础资料打开时，会显示对应基础资料的编码，选择字段后自动填写，不能修改 |
- 字段说明-配置信息-发送配置：当同步类型为发送并接收、发送时，显示该页签配置。
| 序号 | 字段名称 | 是否必录 | 类型 | 功能说明 |
|---|---|---|---|---|
| 1 | 发送动作 | 否 | 选择文本 | 数据发送重要配置，系统会监听星瀚基础资料对应操作，执行数据发送动作 |
| 2 | 数据过滤条件 | 否 | 大文本 | 当需要发送的数据满足该条件时，不执行数据发送 |
| 3 | 客户端 | 否 | 基础资料 | 对应【基础配置】-【客户端】基础资料 |
| 4 | 发送插件 | 否 | 基础资料 | 对应【基础配置】-【插件注册】基础资料，允许二开插件对数据发送部分动作处理自己的业务逻辑，例如：目标客户端需要先认证才允许对数据接收 |
| 5 | 实时数据同步 | 否 | 复选框 | 打开时，监听星瀚基础资料对应操作触发，直接将数据发送到对应客户端。 关闭时，监听星瀚基础资料对应操作触发，将数据先存储在【待同步数据】中 |
| 6 | 目标系统是否主数据 | 否 | 复选框 | 当打开时，需要维护请求报文(reqinfo)的参数信息 |
| 7 | 请求报文-唯一字段标识 | 否 | 下拉列表 | 1、内码(id)：向主数据发送的请求报文中，将当前配置的星瀚基础资料内码，作为主数据新增或修改的标识。 2、编码(number)：向主数据发送的请求报文中，将当前配置的星瀚基础资料编码，作为主数据新增或修改的标识。 |
| 8 | 请求报文-应用系统编码 | 否 | 文本 | 以当前映射配置向主数据发送数据时，应以某个应用系统的身份进行发送，当前设置即表示星瀚适配器以哪个应用系统的身份进行发送。主数据API接口或微服务接口，将对请求报文进行校验，如果应用系统编码不存在，或不存在对应的主数据采集配置，则拒绝接收。 |
| 9 | 请求报文-主数据类型编码 | 否 | 文本 | 以当前映射配置向主数据发送数据时，应表明发送的是哪一种数据类型（主数据管理中定义的数据类型）。主数据API接口或微服务接口，将对请求报文进行校验，如果数据类型不存在，或不存在对应的主数据采集配置，则拒绝接收。 |
- 字段说明-配置信息-接收配置：当同步类型为发送并接收、接收时，显示该页签配置。
| 序号 | 字段名称 | 是否必录 | 类型 | 功能说明 |
| ---------------------------------------------------------- | ------------------------------------------------------------ | ------------------------------------------------------------ | ---------------------------------------------------------- | ------------------------------------------------------------ |
| 1 | 接收服务API | 否 | 基础资料 | 选择API服务预置的“适配器接收服务” |
| 2 | 数据类型编码 | 否 | 文本 | 主数据向星瀚适配器发送的主数据报文，包含了主数据的数据类型编码，此处设置主数据的数据类型编码后，在接收主数据时进行校验，数据类型编码一致是成功接收的必要条件。 |
| 3 | 接收插件 | 否 | 基础资料 | 选择对接收报文进行处理的插件，包含了出厂预置的标准插件，或项目中定制的客户化插件。 |
| 4 | 来源主数据 | 否 | 复选框 | 开启：接收的主数据来源于主数据管理系统，此时需要维护接收主数据的相关参数。
关闭：接收主数据管理之外的第三方系统数据。 | | 5 | 数据唯一字段标识 | 否 | 下拉列表 | 应用系统唯一标识（sysDataId）：接收主数据时，在星瀚中新增或修改当前配置的基础资料，以星瀚基础资料的id作为识别字段。
主数据唯一标识(mdmDataId)：接收主数据时，在星瀚中新增或修改当前配置的基础资料，以主数据的内码（主数据唯一标识）作为识别字段。 | | 6 | 接收配置前置条件 | 否 | 大文本 | |
# 审核
【审核】按钮操作时，如果同步类型=发送并接收、发送时，向对应星瀚基础资料的操作注册监听插件。如果在星瀚基础资料操作时未执行数据发送，需要重新对【数据映射配置】执行审核操作。
# 反审核
【饭2审核】按钮操作时，如果同步类型=发送并接收、发送时，删除对应星瀚基础资料操作监听插件。
# 其他操作
- 操作说明：参见【基本操作】说明。
# 接收服务API
用途：定义主数据星瀚适配器的相关服务。预置1个服务。
预置接口说明：
协议类型为http，报文格式为Json。
编码：receiving
用途：用于接收外部系统发送的数据。
URL地址 http://ip:port/app (opens new window)/gov_madp/receiving
插件注册名称：apusic.mdm.adp.service.ReceivingServicePlugIn
- 入口：点击菜单【同步配置】-【接收服务API】进入列表页面。
- 基本约束说明：API服务是开发服务云-开放平台内的基础功能。
# 新增
点击【新增】按钮，打开一个新增页面。
- 新增页面：选择自定义服务，定义服务操作码，名称，所属应用，描述，生成url格式访问地址。注册服务对应的插件。
# 修改
满足操作的条件：当前用户已分配新增按钮的【功能权限】。否则只能打开查看状态的详情页面。
操作说明：在列表中点击字段“编码”链接，则打开修改状态的详情页面。
# 删除
满足操作的条件：
- [x] 且当前用户已分配按钮的【功能权限】。
操作说明：通过校验后，数据被物理删除。
# 禁用及启用
满足禁用操作的条件：当前【数据状态】为已审核，并且当前用户已分配【功能权限】。
禁用操作说明：在列表中选择数据击按钮【禁用】，通过校验后，数据的【使用状态】变为禁用。
满足启用操作的条件：当前数据【使用状态】为禁用，并且当前用户已分配【功能权限】。
启用操作说明：在列表中选择数据击按钮【启用】，通过校验后，数据的【使用状态】变为启用。
# 应用授权
- 满足操作的条件：具有菜单权限，不需要按钮权限。
- 操作说明： 控制一个业务云，或一个苍穹的应用系统内的API接口是否可以访问，默认允许访问，可“禁止访问”关闭接口服务。
# 用户授权
满足操作的条件：具有菜单权限，不需要按钮权限。
操作说明： 为每个API服务单独授权，权限授予苍穹内的人员。只有完成用户授权，才能访问相应的API服务。
# 刷新及退出
- 操作说明：参见【基本操作】说明。
# 集成调度
# 星瀚适配器调度作业
- 用途：主数据星瀚适配器系统内的数据同步调度作业执行向外部应用系统下发数据的任务。支持定制开发其它类型的作业，在后台定时执行，例如日志清理，数据的转移等等。
- 入口：点击菜单【集成调度】-【调度作业】进入列表页面。
- 基本约束说明：调度作业是苍穹平台基础功能
# 新增
点击【新增】按钮，打开一个新增页面。
- 字段说明：参见《金蝶Apusic主数据管理软件V7.5_用户手册_主数据管理》相关章节，主数据调度作业。
# 禁用及启用
满足禁用操作的条件：当前【数据状态】为已审核，并且当前用户已分配【功能权限】。
禁用操作说明：在列表中选择数据击按钮【禁用】，通过校验后，数据的【使用状态】变为禁用。
满足启用操作的条件：当前数据【使用状态】为禁用，并且当前用户已分配【功能权限】。
启用操作说明：在列表中选择数据击按钮【启用】，通过校验后，数据的【使用状态】变为启用。
# 刷新及退出
- 操作说明：参见【基本操作】说明。
# 星瀚适配器调度计划
用途：主数据星瀚适配器系统内的调度计划，通过设定时间规则，执行调度作业。完成数据的定时发送，以及其它类型调度作业的执行。
入口：点击菜单【集成调度】-【调度计划】进入列表页面。
- 基本约束说明：调度作业是苍穹平台基础功能
# 新增
点击【新增】按钮，打开一个新增页面。
- 新增页面：
新增页面字段说明：参见《金蝶Apusic主数据管理软件V7.5_用户手册_主数据管理》相关章节，主数据调度计划。
保存：参见【基本功能】说明。
# 修改
满足操作的条件：当前数据为暂存状态，并且当前用户已分配新增按钮的【功能权限】。否则只能打开查看状态的详情页面。
操作说明：在列表中点击字段“编码”链接，则打开修改状态的详情页面。
# 删除
满足操作的条件：
[x] 【数据状态】=暂存。
[x] 未被其它实体（基础资料或单据）引用。
[x] 且当前用户已分配按钮的【功能权限】。
操作说明：通过校验后，数据被物理删除。
# 禁用及启用
满足禁用操作的条件：当前【数据状态】为已审核，并且当前用户已分配【功能权限】。
禁用操作说明：在列表中选择数据击按钮【禁用】，通过校验后，数据的【使用状态】变为禁用。
满足启用操作的条件：当前数据【使用状态】为禁用，并且当前用户已分配【功能权限】。
启用操作说明：在列表中选择数据击按钮【启用】，通过校验后，数据的【使用状态】变为启用。
# 刷新及退出
- 操作说明：参见【基本操作】说明。
# 集成日志
# 服务日志
用途：记录主数据星瀚适配器的API服务被调用时和向外发送发起请求时的日志，一次调用执行过程中，可能会涉及多条数据的同步，可通过服务日志【查看同步日志】查询有关的“同步日志”。
入口：点击菜单【集成日志】-【服务日志】进入列表页面。
- 基本约束说明：无
# 查询
满足操作的条件：当前用户已分【功能权限】的查询按钮权限。
操作说明：在列表中点击字段“编码”链接，则打开详情页面。点击“异常信息”后的图标，可查看详细的失败原因。如果当前日志执行过程中存在数据同步，并且生成了数据同步日志，则可联查同步日志。
# 刷新及退出
- 操作说明：参见【基本操作】说明。
# 同步日志
用途：记录每一条数据同步的日志，数据流向的类型包含：发送、接收。
入口：点击菜单【集成日志】-【同步日志】进入列表页面。
- 基本约束说明：无
# 查询
满足操作的条件：当前用户已分【功能权限】的查询按钮权限。
操作说明：在列表中点击字段“编码”链接，则打开详情页面。点击“异常信息”后的图标，可查看详细的失败原因。如果当前日志执行过程中存在向外部发送或从外部接收数据同步，则可联查服务日志。
# 刷新及退出
- 操作说明：参见【基本操作】说明。
# 基础配置
# 插件注册
用途：插件注册是为了解决在数据发送和接收中适应各个系统的认证、报文以及个性化业务场景，适配器支持在数据同步过程中干预数据和收发报文（当前版本只支持发送插件扩展，后续会支持接收插件扩展）。
入口：点击菜单【基础配置】-【插件注册】进入“插件注册”列表页面。
- 基本约束说明：无
# 新增
点击【新增】按钮，打开一个新增页面。
- 新增页面：
- 新增页面字段说明：
| 序号 | 字段名称 | 是否必录 | 类型 | 功能说明 |
|---|---|---|---|---|
| 1 | 编码 | 是 | 文本 | 唯一 |
| 2 | 名称 | 是 | 文本 | 唯一 |
| 3 | 用途 | 是 | 下拉 | 用途包括：发送、接收 |
| 4 | 插件路径 | 是 | 文本 | 必须填写插件全类名，例如 apusic.mdm.adp.service.impl.OrgRecvServiceImpl |
# 插件开发说明
发送插件开发需要实现apusic.mdm.adp.client.IClientProxy接口，以下为各个方法说明
| 方法名 | 说明 |
|---|---|
| afterLoadBaseDataHandle | 加载待分发数据后对DynamicObject数据的处理，插件可以再此对实体存在但未填写数据表的数据进行预置，例如：星瀚物料对象中无单据体数据，但是在发送时需要发送单据体数据，此时可以再此对DynamicObject进行改变来满足单据体发送的需求。 |
| auth | 在系统拼装请求报文后，会调用此方法，可以在此做接口认证鉴权。 |
| handleReqBody | 插件可以在此处理请求报文，处理完成后记得将请求报文设置到上下文中（clientContext.setRequestBody(requestJsonStr);），否则无法记录日志中请求报文。 |
| beforeRequest | 在客户端发起请求前，会调用此方法。 |
| clientRequest | 客户端发起请求，处理完成后记得将响应报文设置到上下文中（clientContext.setResponseBody(responseBody);），否则无法记录日志中响应报文 |
| afterRequest | 客户端发起请求后处理，会调用此方法。 |
# 刷新及退出
- 操作说明：参见【基本操作】说明。
# 星瀚适配器客户端
用途：客户端是对接收系统API相关参数的配置，支持自定义支持明文、加密的参数。
入口：点击菜单【基础配置】-【客户端】进入“客户端”列表页面。
- 基本约束说明：无
# 新增
点击【新增】按钮，打开一个新增页面。
- 新增页面：
- 新增页面字段说明：
| 序号 | 字段名称 | 是否必录 | 类型 | 功能说明 |
|---|---|---|---|---|
| 1 | 编码 | 是 | 文本 | 唯一 |
| 2 | 名称 | 是 | 文本 | 唯一 |
| 3 | URL | 是 | 文本 | 外部系统接收API地址 |
| 自定义参数 | ||||
| 4 | 参数描述 | 是 | 文本 | 描述参数用途以及含义，方便后续维护 |
| 5 | 参数名称 | 是 | 文本 | 在自定义插件中通过参数名称来获取到参数值 |
| 6 | 参数值 | 是 | 文本 | 明文参数值 |
| 7 | 密文参数值 | 是 | 文本 | 【密文参数值】用于密码相关值存储，【参数值】和【密文参数值】二选一填写即可。 请注意：当【参数值】和【密文参数值】同时有值时，客户端上下文优先取【密文参数值】。 |
# 其他操作
- 操作说明：参见【基本操作】说明。
# 待同步数据
【待同步数据】为异步发送数据队列，当【数据映射配置】中【发送配置】未勾选实时同步时，在星瀚基础资料对应操作执行时，系统会向【待同步数据】执行新增，由【星瀚适配器调度计划】依据数据映射配置，按创建时间顺序向外发送数据。
# 查询
打开待同步数据页面，展示待同步数据列表。
# 刷新及退出
- 操作说明：参见【基本操作】说明。