API-Based Integrations (2024)

Overview of API-based integrations

You initiate the integration and deliver the payload by API calls from an application to Integration Hub but not by way of the user interface.
The payload can vary according to the source.
Integration Hub can be configured to transform or map the incoming or outgoing data.
Primarily, you use this type of process for transactional updates from source applications.

API-based integrations

Are not available in the Integrations grid or list views.
Cannot access cross-reference tables.
Expose a REST end point. The end point is asynchronous and returns an identifier (ID) which aids monitoring of the process status from another API.
Are synchronous so that failures are detected early and status is updated immediately even if the integration has failures or is blocked.
You cannot use Transaction Assistant to resubmit failed API integrations.
Because API-based integrations bypass Integration Hub, you do not need to configure a GDAP or an SFTP server.

Validations:

Validity of the API integration key
Validity of user-provided parameters
Presence of user-prompted parameters

How to configure API-based integrations

Configure the API-Based People ImportIntegration
Configure the API-Based Punches ImportIntegration
Configure the API-Based Accruals ImportIntegration

Run API-based integrations

Install the API-based integration
(Optional) If not already done, install or "deploy" API-based integration packs to make them available as integration templates for running or scheduling.
1. Click Tap Main Menu > Administration > Application Setup > Integrations Setup > Install Integrations.
2. Click Tap Create . Enter a unique Integration Name.
3. Select API Integration.
4. Select the integration template from the table. Click Tap Assign.
5. Add, edit, or delete parameters
  Parameters or external files are required or optional when you run or schedule an integration. Parameters vary by integration and can include settings for licenses, to disqualify active or inactive employees, for seniority date, pay period for a location, or job status.
  - Create, edit, or remove a parameter.
    - Click Tap Create . Enter a Parameter Name.
      Tip: Use camel case for parameter names. Example: DisqualifyTerminated.
    - Select a parameter. Click Tap Edit.
    - Select a parameter. Click Tap Delete.Click Tap Yes to confirm.
  - Select a Template Parameter to be the source of the parameter.
  - Select the Parameter Type to define the data format of the parameter:
    - Boolean — Select True or False, On or Off, or Yes or No.
    - Text
    - Password
    - Time Period — Select a time range.
    - Number — Requires a numeric entry.
    - Date — Select a date.
    - Hyperfind query — Select groups of employees.
  - Enter a Default Value.
  - Select User Prompted so that this parameter prompts when the user must enter or select a value.
  - Click Tap Save.
  - Repeat for more parameters.
6. Click Tap Save.
7. Repeat for more API-based integration packs.
Copy the API integration key
The API integration key is generated when you install an API integration, and is needed only for API integration REST API calls. In contrast, the API key calls all external REST APIs from the HTTP request header.
1. Do one of the following:
  - Click Tap Main Menu>Maintenance > Integrations.In the list, search for API integrations.
  - Submit an API call.
2. Copy the Near Real Time API Key.
Run the integration from an application
Example: Postman
1. Select POST or GET.
2. Paste the API integration key into the URI as a parameter after /execute/.
  Caution: When you paste the key, it may include a trailing space. Delete that space. Otherwise, the key will not link to the URI.
  Example: POST: http://{host}/wfc/restcall/v1/ihub/integrations/real_time/execute/{APIIntegrationKey}
3. Select Send.
4. When the integration completes, check Response for details, the status, and any errors.
Log in to verify that the integration ran.

Exposed APIs

Get the list and details of all installed API integrations

GET

URL: http://<host>:<port>/v1/ihub/integrations/real_time

Response-

[

{

"name": "integration_1",

"description": "sample_integration",

"nearRealTimeApiKey": "r-337428fa-229e-4c7c-a4b7-3d878da8efe2-3",

"parameters": [

{

"name": "param1",

"description": "value1"

{

"name": "param2",

"description": "value2"

...

{

"parameters":[

{

"name": "DisqualifyInactive",

"value": "true"

{

"name": "DisqualifyTerminated",

"value": "true"

"data": [

{

"name": "EmployeeID",

"value": "899172"

"name": "EmailID",

"value": "[emailprotected]"

...

{

"name": "EmploymentStatus",

"value": "Active"

}

]

}

Example punch import API integration.postman_collection.json

{

"id": "8d98117b-5d78-e6ec-6f7d-385a89d8a7ef",

"name": "API integration",

"description": "",

"order": [

"c36d07f4-4e02-6ce9-301f-c1d07cf0d873",

"dbcf3d77-016e-faf9-f3c7-2678115d52f9"

"folders": [],

"timestamp": 1479357830283,

"owner": 0,

"public": false,

"requests": [

{

"id": "c36d07f4-4e02-6ce9-301f-c1d07cf0d873",

"headers": "Content-Type: application/json\n",

"url": "http://{{host}}/wfc/restcall/v1/ihub/integrations/real_time/execute/r-253fd076-8285-4ce1-a3f7-b400488d1e1f-1?tenantId=healthcare",

"preRequestScript": null,

"pathVariables": {},

"method": "POST",

"data": [],

"dataMode": "raw",

"version": 2,

"tests": null,

"currentHelper": "normal",

"helperAttributes": {},

"time": 1481888949875,

"name": "API integration punch import sample",

"description": "",

"collectionId": "8d98117b-5d78-e6ec-6f7d-385a89d8a7ef",

"responses": [],

"rawModeData": "{\r\n \"parameters\": [\r\n {\r\n \"name\": \"batchName\",\r\n \"value\": \"Punch Import\"\r\n },\r\n {\r\n \"name\": \"RunSinglePunch\",\r\n \"value\": \"true\"\r\n },\r\n {\r\n \"name\": \"enableTransactionAssistant\",\r\n \"value\": \"false\"\r\n },\r\n {\r\n \"name\": \"UpdateExistingPunches\",\r\n \"value\": \"false\"\r\n }\r\n ],\r\n \"data\": [\r\n {\r\n \"name\": \"Employee\",\r\n \"value\": \"20008\"\r\n },\r\n {\r\n \"name\": \"Date\",\r\n \"value\": \"12/18/2016\"\r\n },\r\n {\r\n \"name\": \"Time\",\r\n \"value\": \"10:30:00\"\r\n },\r\n {\r\n \"name\": \"OverrideType\",\r\n \"value\": \"2\"\r\n }\r\n ]\r\n}"

{

"id": "dbcf3d77-016e-faf9-f3c7-2678115d52f9",

"headers": "",

"url": "http://{{host}}/wfc/restcall/v1/ihub/integrations/real_time/7/status?tenantId=healthcare",

"preRequestScript": null,

"pathVariables": {},

"method": "GET",

"data": null,

"dataMode": "params",

"tests": null,

"currentHelper": "normal",

"helperAttributes": {},

"time": 1481870725958,

"name": "Fetch status",

"description": "",

"collectionId": "8d98117b-5d78-e6ec-6f7d-385a89d8a7ef",

"responses": []

}

]

}