一体化API概述

API是一项基于云的网络服务，在Indeavor和外部系统之间
提供双向数据交换支持。API功能涵盖多个Indeavor实体的多个导入和导出
方案，包括但不限于员工人口统计、
时间表编排和休假管理数据。API可通过HTTP接受和提供XML或
JSON格式的内容。

有关最佳设计实践的指导，请访问接口最佳实践。

一体化过程

从技术上说，一体化过程一般包括以下主要数据流和处理点：

Indeavor基于云的数据存储器：
- 存储待导入或导出的Indeavor数据。
Indeavor基于云的一体化API — 基于收到的HTTP指令：
- 从WL数据存储器中读取适当的数据并将其导出；
- 根据来自外部系统的相应导入源更新WL数据存储器中的数据。
中间数据交换存储器 — 取决于相关一体化环境
- 将来自外部系统的导入源数据存储到API；
- 存储导出“数据模型”模板；
- 将来自API的导出结果数据存储到外部系统；
外部系统数据交换点：
- 为Indeavor提供要导入的源数据；
- 提供导出“指令”（合理构建的数据模型模板）进行导出；
- 接收并使用来自Indeavor的导出结果数据。
数据一体化引擎 — 取决于一体化环境：
- 触发外部系统生成源数据以导入Indeavor；
- 将导入数据保存在中间数据交换存储器中；
- 从中间数据交换存储器中读取导入数据；
- 提供导入数据映射和转换供API使用
- 向API发送源数据进行处理；
- 接收来自API的结果数据。
数据映射和转换：
- 根据适当的Indeavor实体模板，提供从“平面”格式（.txt、.csv等）到XML格式的导入源数据转换；
- 提供从模板定义的XML格式到外部系统要求格式的结果导出数据转换。

下图以图形方式显示一体化进程连接：

一体化方案

一体化架构设计可以有多种方法，具体取决于一体化中间件（数据一体化引擎）的性质。

一体化中间件主要有三个选项：

与外部系统实现一体化。纳入外部系统的中间件类型，能够“直接”读取待传输至Indeavor的外部系统数据，可以将数据转换为Indeavor API所接受的XML格式（包括所有数据转换和映射），将一体化数据放入中间数据交换存储器或直接调用API，并以HTTP请求有效载荷的形式提供数据。
第三方一体化中间件 — DELL Boomi。它位于AWS上，提供多种可能的连接器，包括数据访问连接器（FTP、磁盘、数据库连接器）和HTTP连接器，用于API通信。除非在本地（超出范围）安装，否则Dell Boomi环境不允许与外部系统存储器直接通信，只能通过中间数据交换存储器（可以是外部系统拥有的FTP 站点，也可以是Indeavor拥有的FTP站点）来访问外部系统数据。
“Indeavor Connect”服务。这是一个内部软件，可通过FTP站点、磁盘或直接数据库源连接来访问/提供外部系统的数据。该软件还可以将数据转化为符合外部系统和Indeavor API数据交换标准的任何格式，或者从符合外部系统和Indeavor API数据交换标准的任何格式转化成其他格式。

Indeavor在实施基于上述三种一体化中间件选项的一体化方案方面经验丰富。需要注意的是，每个选项都涉及多种架构变化，并且不同的选项还可以相互组合。下面是Indeavor截至目前已经实施的一体化方案。

方案1

基于一体化中间件的选项1：与外部系统实现一体化。

外部系统准备从其数据存储器（图1中的连接1）以系统自身的格式接收一体化源数据并将其转换成：
- 数据模型模板，用于以API预定义的XML格式导出；
- 源数据，用于以API兼容的XML格式导入（图1中的连接4）。
外部系统启动与Indeavor API的HTTP通讯，为实现一体化提供适当的数据（图1中的连接5）；
外部系统接收来自API的响应，其中的数据可能会反映导入结果，也可能会代表将被转移到外部系统的Indeavor导出数据（图1中的连接5、1）；

在方案1中，所有一体化流程阶段均由外部系统启动（触发）。

方案2

基于一体化中间件的选项2：DELL Boomi。

外部系统以系统自身格式准备一体化源数据，并执行以下任一操作（具体取决于外部系统功能）：
- 可以将数据按原样（以外部系统的格式）上传到安全的FTP站点（图1中的连接1）；
- 也可以将数据转换为API兼容的XML格式，并上传到安全的FTP站点（图1中的连接2）。

源数据的上传按照对DELL Boomi中间件公开的预定义时间表进行。

DELL Boomi从FTP下载源数据（图1中的连接3），并将其转换为API兼容的XML格式（图1中的连接4），除非已由外部系统在前一阶段完成；
DELL Boomi启动与Indeavor API的HTTP通讯（图1中的连接5），为实现一体化提供适当的数据；
DELL Boomi接收来自API的响应（图1中的连接5），其中的数据可能会反映导入结果，也可能会代表将被转移到外部系统的Indeavor导出数据；
Dell Boomi将API响应（导入结果或导出输出）上传到专门的安全FTP站点，供外部系统下载和使用（图1中的连接3）。

在方案2中，除了第一个一体化进程阶段外，所有其他阶段均由DELL Boomi启动（触发），并与外部系统的FTP上传/下载时间表适当同步。

方案3

基于一体化中间件的选项3：Indeavor Connect与外部系统一起安装在本地。

Indeavor Connect通过直接访问外部系统的数据存储器（DB视图）或准备XML格式的导出数据模型来接收导入的源数据（图1中的连接1）；
Indeavor Connect将源导入数据从平面视图表示转换为API兼容的XML格式（图1中的连接4）；
Indeavor Connect启动与Indeavor API的HTTP通讯，为实现一体化提供适当的（导入或导出）数据（图1中的连接5）；
Indeavor Connect接收来自API的响应（图1中的连接5），其中的数据可能会反映导入结果，也可能会代表将被转移到外部系统的Indeavor导出数据；
Indeavor Connect通过与其数据存储视图的直接通信将导出输出发送至外部系统进行使用（图1中的连接1），或将导入结果作为本地网络资源上传进行分析。

在方案3中，所有一体化进程阶段均由Indeavor Connect通过Windows任务调度程序的调度功能进行启动（触发）。

Indeavor一体化API

为启动与Indeavor一体化API的任何（导入或导出）一体化进程，必须通过身份验证过程授予对Indeavor数据的访问权限。

身份验证

要使用API进行身份验证，应使用下述Http请求。请求数据为带有用户名和密码字段的JSON对象。响应信息应为包含登录操作相关详细信息的JSON对象。要顺利登录，“_r”字段应为1，而“SessionID”字段应包含用于后续API调用以识别用户身份的密钥。

名称	值
URL	https://interop.[ENVIROMENTNAME].indeavor.com/current/Session/SessionHandlerWS.asmx/Login
Http方法	发布
标题	Content-Type: application/json charset: utf-8
正文	{ “username”:”<UserName>@rjr”, “password”:”<Password>”, “response”:1 }

API响应会返回一些JSON格式数据......但对于随后的导入/导出API调用以识别用户身份来说，重要的是与Http响应一起返回的cookie容器。其中包括下列两个cookie，必须通过API导入/导出调用进行转发：

名称	值
ASP.NET_SessionId	（示例）：lkqs4bndhvk1snc4z2mxpe5s
AWSELB	（示例）：BF836DE70EC369F6241CF55E41A743DEB743F2E50E11C505FFF413E8CDF89B0DF47D58D512F53721BDEDFBB5FB2B2C97320B290D32DA311A71E93F0B0E1965E6ECBB108D5DC9ECF83AE34C6903E489407E5F90FBC4

导入

导入数据通过将要导入的数据以XML格式发布到API的导入处理程序来实现。需要提供以下信息。

名称	值
URL	https://interop.[ENVIROMENTNAME].indeavor.com/current/import/importhandler.ashx
Http方法	发布
标题	Content-Type: application/x-www-form-urlencoded Accept-Encoding: deflate Cookie：<按如下方式从身份验证调用中获取cookie容器，或者直接提供cookie作为参数：SessionId=<SessionId>&AWSELB=<AWSELB_value>
正文	isBackgroundJob=true&Data=<Data to import> 参数说明： - isBackgroundJob：此参数的唯一推荐值为真 - <Data to import>：代表根据适当的导入数据模板格式化的XML输入数据。

一旦作为后台作业提交，如果成功，该Http请求将立即通过以下JSON结构返回适当的作业“id”参数，供未来使用：

{

“Job”:{

“id”:”<Job Identifier>”,

“startTime”:”<Job Start Time>”

}

要检查后台作业状态，必须使用以下API处理程序

名称	值
URL	https://interop.[ENVIROMENTNAME].indeavor.com/current/import/import.asmx/GetCurrentResultForJob
Http方法	发布
标题	Content-Type: application/x-www-form-urlencoded Accept-Encoding: deflate Cookie：<按如下方式从身份验证调用中获取cookie容器，或者直接提供cookie作为参数：SessionId=<SessionId>&AWSELB=<AWSELB_value>
正文	jobID=<Job Identifier> 参数说明： - <Job Identifier>：代表从导入处理程序请求中收到的JSON响应的“id”参数。

根据作业执行状态，一项作业可能会收到两个响应：

如果后台作业仍在运行，则返回XML结果：

<Output>

<Results>

<Error Value=”No opertion results found” />

<Job id=”<Job Identifier>” currentStep=”0” totalSteps=”1” startTime=”2018-11-26T16:05:25.0000000” />

</Results>

</Output>

如果后台作业已成功执行，则显示JSON结果（下面以员工休假余额导入为例）：
- {
- “d”:
- “<Output>
- <Results>
- <Items type=”EmployeeLeaveBalance”>
- <Item result=”0” action=”0” index=”1”/>
- <Item result=”200” action=”0” index=”2” messages=”不支持指定的员工、休假类型和会计期间组合”/>
- <Item result=”0” action=”0” index=”3”/>
- </Items>
- </Results>
- </ Output>”

}

因此，输出的"d"参数代表导入执行的实际结果。

导出

导出数据通过以XML格式向API的导出处理程序提供数据模板来实现。需要提供以下信息。

名称	值
URL	https://int erop.[ENVIROMENTNAME].indeavor.com/current/export/exportHandler.ashx
Http方法	发布
标题	Content-Type: application/x-www-form-urlencoded Accept-Encoding: deflate Cookie：<按如下方式从身份验证调用中获取cookie容器，或者直接提供cookie作为参数：SessionId=<SessionId>&AWSELB=<AWSELB_value>
正文	returnType=response&definition=<Export Data Template> 参数说明： - <Export Data Template>：XML格式的数据模型模板，包括要导出数据的数据类型、字段和筛选器。

导出执行的结果为根据数据模型模板构建的XML文档，其中包含根据提供的数据筛选器获取的适当Indeavor数据。

通用一体化 — 输入和输出数据模型

Indeavor客户使用的最常见一体化接口有：

员工人口统计导入接口；
员工休假余额导入接口；
时间表导出接口。

员工人口统计信息导入

该接口以“EmployeeUpdates”数据模型模板为“指令”来创建Indeavor API的XML格式化输入。举个简单的例子（实际模板支持提供更多字段和实体进行更新），如果以下字段来自外部系统，并将作为员工数据在Indeavor中更新：

员工ID；
名字；
姓氏；
活动标志；
活动日期；
资历日期；
主要组织单位；
组分配

以下XML数据将代表“<Data to Import>”中的Indeavor API输入值（以一个员工为例）：

<?xml version='1.0' encoding='UTF-8'?>

</Options>

</Fields>

</EntityMapping>

</Fields>

</OrganizationalUnitEmployee>

</OrganizationalUnitsEmployee>

</Fields>

</GroupMembership>

</GroupMemberships>

</Employee>

</EmployeeUpdate>

</EmployeeUpdates>

</Input>

员工休假余额导入

该接口以“EmployeeLeaveBalances”数据模型模板为“指令”来创建Indeavor API的XML格式化输入。在最常见的情况下 - 接口会根据外部系统的数据来“纠正”Indeavor余额 - 应提供以下字段作为创建API XML输入的来源：

员工ID；
休假类型；
会计期间；
余额生效日期；
余额；

适当的API XML输入如下所示（以一个员工为例）：

<?xml version='1.0' encoding='UTF-8'?>

</Options>

</Fields>

</EmployeeLeaveBalance>

</EmployeeLeaveBalances>

</Input

员工时间表导出

该接口以“EmployeeScheduleReport”数据模型模板为“指令”来创建Indeavor API的XML格式化输入。举个简单的例子（实际模板支持提供更多字段和实体进行更新），如果需要将以下字段导入外部系统：

员工ID；
时间表事件类型(=0：工作分配；=4：休假等)
时间表事件开始时间；
时间表事件结束时间；
工作地点；
工作分配加班标志；
休假ID；
休假期限；
时间表事件日期；
工作持续时间；
工作分配人工代码。

应将以下XML数据作为“<Export Query>”提供给Indeavor API：

</Options>

</OutputFields>

</Filters>

</Export>

以下输出将代表导出结果数据（日期反映的是接口是在2018年12月26日执行的）：

<Item>

</Item>

<Item>

</LaborCode>

</LaborCodes>

</Item>

</Output>