InEight Integrations - Starting Guide for Developers

This page is the starting point for developers creating integrations with InEight. This page contains information about InEight APIs, where to find them, how to use them, what security and authentication measures are taken, and other general information that is common to all cloud application APIs.

This page does not cover specific details of each API, such as data elements, structure, prerequisites, and usage descriptions. For those details you will need to reference the InEight Integration Catalog that cover the specific APIs.

General Information About InEight Integrations

Business Rules for Integrations

While integrations for InEight are designed to be agnostic of who or what system will be using them from outside of InEight, many of them are dependent on specific business requirements for the flow of data. For example, data exposure about time worked for employees and equipment only occurs when specific activities are performed in the UI that indicate the data for those records has reached a specific state. It is important to note here because each integration might require attention to when and how it can be used. Any pertinent information regarding how, when, and what rules apply to the use of an integration are covered in the integration’s specification document.

InEight integrations are comprised of either of the following:

External Integration APIs

  • Request and Responses are in Asynchronous in nature

  • Primarily used to push data to InEight Platforms

  • Some Get APIs are exposed for retrieving the data from InEight Platforms

  • All data is expected or provided in JSON data packages

  • All are managed through our API Management Portal

Integration Frequencies

InEight supports integrations at any interval required by a customer or third-party application. However, the actual frequency of an integration should be determined by business need and amount of data being transmitted at any one time. For example, updates to Employee records could be sent to InEight in near real- time based on events such as hiring or termination that occur in an ERP or HCM system because these are infrequent and will update a very small set of records at a time. Updates to cost items for actuals, forecast, or budget have a much larger payload (potentially tens of thousands of records) and can result in better performance if it occurs either on demand by a user in InEight or at scheduled off-hour intervals.

When creating, or using integrations for InEight, discussion of the individual integrations, payloads, and frequencies must occur to determine the best impact to all systems.

Data Transformation

InEight generally does not perform transformation or mapping of any data due to the number of unique cases and needs across different customers. Data provided to external systems from InEight will be representative of the raw data in the InEight’s business operations. It is generally the responsibility of the customer receiving systems, or a middle tier of an integration to handle mapping and transformation logic.

JSON to Other File Formats

InEight integrations provide all data through externally (to InEight) accessible APIs that produce records in a JSON format. Transformation of records from JSON to other formats (e.g., XML, CSV, etc.) must be handled by the customer via a business logic application such as SAP Process Integrator, Azure Logic Apps, Microsoft BizTalk, Dell Boomi, or other proprietary logic/code.

Data Mapping

Transformation of data in a field from one context to another (e.g., a set of statuses that must be converted to a true/false flag) and mapping of customer data to an integration field between a customer system and the output from InEight APIs or expected input to InEight integrations must be handled by the customer’s integration system or middleware.

Business Logic

Business logic required to conform data, fill fields, or evaluate specific data conditions must be handled by the customer. Some examples of business logic are as follows:

  • Providing default data when a field from InEight is left blank.

  • Evaluation of one or more data fields to determine an expected end result. For example, if an employee has an active status AND does not have hours, set an "at work" field to false.

Record Identification

InEight takes into consideration the "system of record" for all stored data. When the data originates from sources that are external to the InEight cloud platform, a unique identifier is required to be provided by the external system for each record to ensure a common value can be used when exchanging, creating, or updating records through integrations. InEight integrations commonly refer to this field as "SourceSystemId".

When managing "Master Data" (data that is normally static and used to classify or provide dimensional data to transactions), it is standard practice for each InEight entity to contain the following types of fields:

  • SourceSystemId: The unique identifier that will be used to match records exchanged in integrations. This field is not normally displayed in the InEight UI.

  • Natural Key: This is also a unique identifier, but one that is recognizable by users and is always displayed in InEight UIs. In InEight integrations, this field may be labeled as "DisplayId", or "Name", or have a unique label to accommodate specific usability concerns (e.g., Email is used as the natural key for Users).

InEight separates the concept of record identification into these two fields to allow the possibility of using both a system generated identifier such as a GUID as the SourceSystemId to make system-to-system interactions easier, while also using a human recognizable unique value for all business processes handled through user interaction. In cases where an external system uses a natural key as the system-identifiable unique value, it is acceptable to set the SourceSystemId and Natural Key to the same value.

Master Data Example of Record Identification

The following example shows the JSON format for the Master Data entity "Cost Centers". In this example, there is a specific field called "SourceSystemId" and a field called "CostCenterDisplayId" that represents the Natural Key that will be used in UIs.

When the records were created the API request may have contained several records at once and appeared as follows.

When the integration is processed, records appear in the UI as follows. Notice that "SourceSystemId" is not shown, and the "CostCenterDisplayId" field is renamed to "ID" in the UI.

If a record needs to be updated, the original SourceSystemId of the record will need to be provided as reference. The below JSON shows the "Project Operations" Cost Center being deleted as an option from Cost Centers.