Step3:触点名单接入

本小结内容主要为开发人员准备，业务老师可以了解整体过程，阅读上也没有难度。

前提：在阅读本章节之前，IT团队与业务团队已经明确了触点名单的字段。本章由开发人员阅读，你需要达成以下目标：

1. 生成名单表配置文件
2. 通过Web API接口接入

首先，进入“接触点1”的“名单配配置”tab页，点击“上传或更新”名单格式，会弹出如下图所示的问卷上传框：

选择一个预先配置好的名单格式文件Demo.xml, 本章节的稍后会重点介绍如何准备这份xml名单格式文件。

以下将详细向您介绍名单接入的一些技术细节和步骤，整体来说过程也非常简洁，主要分两步：“生成名单配置文件”和“通过Web API接口接入想应”

1.生成名单表配置文件

在业务人员梳理好触点字段后，会交付予你一份名单字段列表，你首先要确认该列表上每一个字段都能在你的业务系统中能获取到，否则，应该与业务人员进行协商修改。如果确认没问题，你可以通过以下规则来生成一份XML格式的名单表配置文件demo.xml：

整个示例的名单格式文件demo.xml内容如下：

<?xml version="1.0" encoding="utf-8"?>
<!-- 必填；1代表字符串；2代表数字；3代表日期。 -->
<config>
    <version>0.1</version>
    <projectId>P2661557806138876</projectId>
    <touchpointId>1557806138876P</touchpointId>
    <basicFields>
          <!-- 固定字段 -->
          <!-- 姓名 -->
        <field>
            <keyDesc>姓名</keyDesc>
            <sysName>name</sysName>
            <fieldId>1</fieldId>
            <isIdentityField>false</isIdentityField>
            <isPrimitiveField>true</isPrimitiveField>
            <order>1</order>
        </field>
        <!-- 性别 -->
         <field>
            <keyDesc>性别</keyDesc>
            <sysName>sex</sysName>
            <fieldId>2</fieldId>
            <isIdentityField>false</isIdentityField>
            <isPrimitiveField>true</isPrimitiveField>
            <order>2</order>
        </field>
        <!-- 年龄 -->
        <field>
            <keyDesc>年龄</keyDesc>
            <sysName>age</sysName>
            <fieldId>3</fieldId>
            <isIdentityField>false</isIdentityField>
            <isPrimitiveField>true</isPrimitiveField>
            <order>3</order>
        </field>
        <!-- 手机号 -->
        <field>
            <keyDesc>手机号</keyDesc>
            <sysName>telephone</sysName>
            <fieldId>5</fieldId>
            <isIdentityField>true</isIdentityField>
            <isPrimitiveField>true</isPrimitiveField>
            <order>4</order>
        </field>
        <!-- 微信公众号id -->
        <field>
            <keyDesc>微信openId</keyDesc>
            <sysName>wxOpenId</sysName>
            <fieldId>10</fieldId>
            <isIdentityField>false</isIdentityField>
            <isPrimitiveField>true</isPrimitiveField>
            <order>5</order>
        </field>
        <!-- 邮箱 -->
        <field>
            <keyDesc>邮箱</keyDesc>
            <sysName>mail</sysName>
            <fieldId>6</fieldId>
            <isIdentityField>false</isIdentityField>
            <isPrimitiveField>true</isPrimitiveField>
            <order>6</order>
        </field>
    <!-- 用户定义的字段 -->
       <field>
            <isIdentityField>false</isIdentityField>
            <keyDesc>客户等级</keyDesc>
            <sysName>clientLevel</sysName>
            <type>1</type>
            <length>128</length>
            <format></format>
            <isPrimitiveField>false</isPrimitiveField>
            <order>7</order>
        </field>

    </basicFields>
    <!-- 用来mapping上游系统传过来的json中的字段与名单系统里的name -->
    <fieldMappings>
            <name>name</name>
            <sex>sex</sex>
            <age>age</age>
            <telephone>telephone</telephone>
            <wxOpenId>wxOpenId</wxOpenId>
            <mail>mail</mail>
            <clientLevel>clientLevel</clientLevel>            
    </fieldMappings>
</config>

<config>：整个文档应包含于<config>标签内

<projectId>：项目id，表明该配置文件应用于哪一个项目

<touchpointId>：触点id，表明该配置文件应用于哪一个触点（注：projectId和touchpointId联合唯一对应一份名单配置文件）

<basicFields>：字段列表，每一个<field>代表一个字段，<field>的配置项如下：

<KeyDesc>：字段的中文描述，用于在前端显示

<sysName>：字段的英文描述，用于后端存储于检索

<fieldId>与<isPrimitiveFIeld>：搭配使用，当isPrimitiveFIeld为true时，表明该字段为系统的内置字段，fieldId需要设置为系统规定的id值，系统内所有的固定字段见附表1

<isIdentityField>：字段是否为标识字段。插入记录时，当标识字段相等则更新，不相等则插入新记录，可以设置多个字段为联合标识字段

<type>：字段的类型，1代表字符串类型，2代表数字类型，3代表日期类型。固定字段不用设置此项

<format>：正则检查，可填入一个正则表达式进行正则检查，不填则表示不进行检查

<length>：字段的长度。固定字段不用设置此项

<order>：字段在数据库表列中的显示顺序，值越小越靠左

<fieldMappings>：Web API中传入JSON参数中的key值与数据库字段的映射，此属性下的key值对应Web API JSON参数中的key值，value值对应数据库字段的sysName值。此属性设置的目的是方便修改API参数而不用修改数据库字段。
名单配置文件制作好保存之后，在触点名单配置页面上传此XML文件即可，上传成功后，你将会在触点名单页面看到你在XML文件中配置的字段。

2.通过Web API接口接入

在配置好了步骤1里的名单格式之后，您仅需要调用我们平台的一个简单的API接入即可，该接口会将匹配的名单数据推送到发送队列中，下图展示了Web接入接口在整个流程中的关键位置。

该API的主要功能为：它通过接口规约，将步骤1里规s约好的名单格式，从生产系统中接收由上后下放的名单数据，这些数据将会通过该API接口的Post的消息 body里得到体现，具体后面会clientInfoField参数。

Web API规约如下：

接口地址：http://HOST:PORT/iformmaster/touchpoint/handler/task/post

注意：HOST和PORT为动态环境变量，根据想应具体部署的环境而定，为想应部署的服务器地址和端口号。

请求类型：POST

参数body类型：application/json;charset=UTF-8

请求参数示例：
{
    "touchPointId": "", //触点Id
    "projectId": "", //项目Id
    "sourceSysId": "BPM", //来源系统号
    "clientInfoField": {
        "name": "", //申请人姓名
        "telephone": "", //手机号
        ...
    }
}

注:凡是在XML文件<fieldsMappinds>中配置的字段，都必须出现在clientInfoField参数中，没有值的用null / "null" / "" 表示即可。

成功返回示例：
{
    "reply": "N",
    "errorCode": "000", // 其他errorCode都是不成功状态
    "message": "success"
}

在你的业务系统合适的位置对想应Web API进行调用，将业务数据传递至想应，即可完成接入！