Integration API Overview

The API is designed as a cloud-based Web Service that provides bi-directional data exchange
support between Indeavor and External Systems. API functions cover several import and export
scenarios for several Indeavor entities, including but not limited to employee demographics,
scheduling and leaves management data. The API accepts and serves content in either XML or
JSON formats over HTTP.

For direction in best design practices, please visit Interfacing Best Practices.

Integration Process

Technologically Integration process in general includes the following major data flow and processing points:

Indeavor cloud-based Data Storage:
- Stores Indeavor data to be imported or exported.
Indeavor cloud-based Integration API – based on HTTP directives received:
- Reads appropriate data from WL Data Storage and provides it for Export;
- Updates data in WL Data Storage according to appropriate Import source coming from External System.
Intermediate Data Exchange Storage – depending on Integration environment it’s dedicated to
- Storing Import source data coming from External System to the API;
- Storing Export ‘Data Model’ template;
- Storing Export result data coming from the API to External System.
External System Data Exchange Point:
- Provides source data for Indeavor to be imported;
- Provides export “directives” (appropriately formed data model template) for export;
- Receives and consumes export result data coming from Indeavor.
Data Integration Engine – depending on Integration Environment:
- Triggers External System to produce Source Data for Import into Indeavor;
- Saves Import Data on Intermediate Data Exchange Storage;
- Reads Import data from Intermediate Data Exchange Storage;
- Provides Import Data Mapping and Conversion for consumption by the API
- Sends source data to the API for processing;
- Receives result data from the API.
Data Mapping and Conversion:
- Provides Import source data conversion from “flat” format (.txt, .csv etc.) to XML format according to appropriate Indeavor entity template;
- Provides result Export data conversion from template defined XML format to the one required by External System.

Integration Scenarios

There could be multiple possible ways of integration architectural design depending on the integration middleware (Data Integration Engine) nature.

There are three major options for integration middleware:

External System integrated. The type of middleware that incorporated into external system and is capable of “directly” reading External System’s data to be transferred to Indeavor, converting the data into XML format accepted by Indeavor API (including all the data conversion and mapping), placing the integration data into Intermediate Data Exchange Storage or directly calling the API with providing the data as a HTTP request payload;
Third-party integration middleware – DELL Boomi. It’s located on AWS and provides multiple possible connectors including data access ones (FTP, Disk, DB connectors) and HTTP connector for API communication. Unless installed on premise (out of scope) the Dell Boomi environment doesn’t allow direct communication to external system storage, the only option for accessing External System’s data would be via Intermediate Data Exchange Storage: that could be either External System owned or Indeavor owned FTP site.
‘Indeavor Connect’ Service. This is on-premise software that can access/provide External System’s data via FTP site, Disk or through direct DB source connections. It also can convert data from/to any format compliant with both External System and Indeavor API data exchange.

Indeavor has experience in implementing integration scenarios based on all three mentioned integration middleware options. It worth mentioning that each of the options implies multiple architectural variations as well as different options can be combined. Below are just the integration scenarios implemented by Indeavor so far.

Scenario 1

Is based on option 1 for integration middleware: External System integrated.

External System prepares Integration source data receiving it from its data storage (connection 1 on Pic. 1) in its own format and converting it into:
- data model template for Export in the API’s predefined XML format;
- source data for Import in the API’s compliant XML format (connection 4 on Pic. 1).
External System initiates HTTP communication to Indeavor API supplying appropriate data for integration (connection 5 on Pic. 1);
External System receives response from the API with data that either reflecting Import result or representing Indeavor Export data to be transferred to the External System (connections 5, 1 on Pic. 1);

With Scenario 1 all Integration process stages are initiated (triggered) by External System.

Scenario 2

Is based on option 3 for integration middleware: Indeavor Connect installed on-premise alongside with External System.

Indeavor Connect receives source data for Import (connection 1 on Pic. 1) via direct access to External System’s data storage (DB views) or prepares XML formatted Export data model;
Indeavor Connect converts source Import data from flat view representation to the API’s compliant XML format (connection 4 on Pic. 1);
Indeavor Connect initiates HTTP communication to Indeavor API supplying appropriate (Import or Export) data for integration (connection 5 on Pic. 1);
Indeavor Connect receives response from the API (connection 5 on Pic. 1) with data that either reflecting Import result or representing Indeavor Export data to be transferred to the External System;
Indeavor Connect sends Export output to External system for consumption (connection 1 on Pic. 1) via direct communication to its data storage view(s) or uploads Import result as local network resource for analysis.

With Scenario 3 all Integration process stages are initiated (triggered) by Indeavor Connect via scheduling functionality of the Windows Task Scheduler.

Indeavor Integration API

In order to initiate any (Import or Export) integration process with Indeavor integration API access to Indeavor data must be granted via authentication process.

Authentication

To authenticate with the API, one should use Http request described below. The request data is a JSON object with username and password fields. The response will be JSON object containing details about the login operation. For successful logins, the “_r” field will be 1, and the “SessionID” field will contain a key that will be used on subsequent API calls to identify the user.

Name	Value
URL	https://interop.[ENVIROMENTNAME].indeavor.com/current/Session/SessionHandlerWS.asmx/Login
Http method	POST
Headers	Content-Type: application/json charset: utf-8
Body	{ “username”:”<UserName>@rjr”, “password”:”<Password>”, “response”:1 }

The API response returns some JSON formatted data… but what matters for subsequent import/export API calls to identify a user is a cookie container returned with Http response. It includes two listed below cookies and must be forwarded with API import/export calls:

Name	Value
ASP.NET_SessionId	(example): lkqs4bndhvk1snc4z2mxpe5s
AWSELB	(example): BF836DE70EC369F6241CF55E41A743DEB743F2E50E11C505FFF413E8CDF89B0DF47D58D512F53721BDEDFBB5FB2B2C97320B290D32DA311A71E93F0B0E1965E6ECBB108D5DC9ECF83AE34C6903E489407E5F90FBC4

Importing

Importing data is achieved by posting the data to be imported in XML form to the import handler of the API. The following are all needed.

Name	Value
URL	https://interop.[ENVIROMENTNAME].indeavor.com/current/import/importhandler.ashx
Http method	POST
Headers	Content-Type: application/x-www-form-urlencoded Accept-Encoding: deflate Cookie: <the cookie container from Authentication call or just provide the cookies as parameters as follows: SessionId=<SessionId>&AWSELB=<AWSELB_value>
Body	isBackgroundJob=true&Data=<Data to import> Explanation of parameters: - isBackgroundJob : the only recommended value for the parameter is true - <Data to import>: represents XML input data formatted according to appropriate import data template.

Once submitted as a background job – the Http request, if successful, immediately returns appropriate job “id” parameter for future use via the following JSON structure:

{

“Job”:{

“id”:”<Job Identifier>”,

“startTime”:”<Job Start Time>”

}

To check the background job status the following handler of the API must be used

Name	Value
URL	https://interop.[ENVIROMENTNAME].indeavor.com/current/import/import.asmx/GetCurrentResultForJob
Http method	POST
Headers	Content-Type: application/x-www-form-urlencoded Accept-Encoding: deflate Cookie: <the cookie container from Authentication call or just provide the cookies as parameters as follows: SessionId=<SessionId>&AWSELB=<AWSELB_value>
Body	jobID=<Job Identifier> Explanation of parameters: - <Job Identifier>: represents “id” parameter of the JSON response received from the Import handler request.

Depending on the job execution status one can receive two possible responses:

XML result if the Background Job is still running:

<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 result if the Background Job has been successfully executed (example is for Employee Leave Balances Import):
- {
- “d”:
- “<Output>
- <Results>
- <Items type=”EmployeeLeaveBalance”>
- <Item result=”0” action=”0” index=”1”/>
- <Item result=”200” action=”0” index=”2” messages=”Specified employee, leave type and accounting period combination is not allowed”/>
- <Item result=”0” action=”0” index=”3”/>
- </Items>
- </Results>
- </ Output>”

}

So, the “d” parameter of the output represents actual result of the Import execution.

Exporting

Exporting data is achieved by providing data template in XML form to the export handler of the API. The following are all needed.

Name	Value
URL	https://int erop.[ENVIROMENTNAME].indeavor.com/current/export/exportHandler.ashx
Http method	POST
Headers	Content-Type: application/x-www-form-urlencoded Accept-Encoding: deflate Cookie: <the cookie container from Authentication call or just provide the cookies as parameters as follows: SessionId=<SessionId>&AWSELB=<AWSELB_value>
Body	returnType=response&definition=<Export Data Template> Explanation of parameters: - <Export Data Template>: XML formatted data model template that includes data types, fields, and filters for the data to be exported.

The result of the Export execution is XML document structured according to the data model template and it and includes appropriate Indeavordata fetched according to provided data filters.

Common Integrations – Input and Output data Models

There are several most common Integration interfaces used by Indeavor customers:

Employees Demographics Import interface;
Employees Leave Balances Import interface;
Schedule Export interface.

Employee Demographics Import

The interface is utilizing ‘EmployeeUpdates’ data model template as a “directions” for creating Indeavor API’s XML formatted input. As a simple example (the template allows much more fields and entities to be provided for update), if the following fields are coming from External System as Employee data for an update in Indeavor:

Employee ID;
First Name;
Last Name;
Activity flag;
Activity Date;
Seniority Date;
Primary Organizational Unit;
Group Assignment

the following XML data will represent Indeavor API’s input as “<Data to Import>” (one employee example):

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

</Options>

</Fields>

</EntityMapping>

</Fields>

</OrganizationalUnitEmployee>

</OrganizationalUnitsEmployee>

</Fields>

</GroupMembership>

</GroupMemberships>

</Employee>

</EmployeeUpdate>

</EmployeeUpdates>

</Input>

Employee Leave Balances Import

The interface is utilizing ‘EmployeeLeaveBalances’ data model template as a “directions” for creating Indeavor API’s XML formatted input. In the most common case – the interface is “correcting” Indeavor balances in accordance with External System’s data - the following fields should be supplied as a source for creating API XML input:

Employee ID;
Leave Type;
Accounting Period;
Balance Effective Date;
Balance Amount;

Appropriate API’s XML input will look like (one employee example):

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

</Options>

</Fields>

</EmployeeLeaveBalance>

</EmployeeLeaveBalances>

</Input

Employee Schedule Export

The interface is utilizing ‘EmployeeScheduleReport’ data model template as a “directions” for creating Indeavor API’s XML formatted input. As a simple example (the template allows much more fields and entities to be provided for update), if the following fields are supposed to be transferred to External System:

Employee ID;
Scheduled Event Type (=0: Assignment; =4: Leave, etc.)
Scheduled Event Start Time;
Scheduled Event End Time;
Assignment Location;
Assignment Overtime Flag;
Leave ID;
Leave Accountable Duration;
Scheduled Event Date;
Assignment Duration;
Assignment Labor Code(s).

the following XML data should be supplied to Indeavor API as “<Export Query>”:

</Options>

</OutputFields>

</Filters>

</Export>

And the following output will represent the Export result data (the dates are reflecting the interface being executed on 12/26/2018):

<Item>

</Item>

<Item>

</LaborCode>

</LaborCodes>

</Item>

</Output>

Related articles