How to connect to Integration API from an external system.
Overview
In the previous documents in this series the focus is on utilizing the Integration API via the built-in UI. This is an excellent way to quickly get started, and to test different scenarios. In addition, it can be used with real data in "one-off" situations where you quickly need to get an answer to a question using the Outbound Processor, or even doing a simple one time import via the Inbound Processors. However, in other more complex cases such as when you need to connect an "other vendor" system to LeanIX, it will eventually be necessary to build a REST API.
If you haven't done so already please see Integration API in order to familiarize yourself with the basics of the Integration API.
This document will review the process of getting started with the REST API. Please see below for the Swagger, JSON, authentication, and reference information.
Integration runs in two steps and a minimum two calls are required to start a Sync run. Please see below for the integration flow including calls.
Create a processor
Create a Processor under Integration API, with the below details:
Connector Type: importProjectsExample
Connector Id: importProjectsExample
Connector Version: 1.0.0
Processing Direction: inbound
Place the below details in the Processor :
{
"processors": [
{
"processorType": "inboundFactSheet",
"processorName": "Projects from prj",
"processorDescription": "Creates LeanIX Projects from external LDIF",
"type": "Project",
"filter": {
"type": "prj|subp"
},
"identifier": {
"external": {
"id": {
"expr": "${content.id}"
},
"type": {
"expr": "externalId"
}
}
},
"run": 0,
"updates": [
{
"key": {
"expr": "name"
},
"values": [
{
"expr": "${data.displayName} (${content.id})"
}
]
},
{
"key": {
"expr": "description"
},
"values": [
{
"expr": "${data.processDescription}"
}
]
},
{
"key": {
"expr": "lifecycle.active"
},
"values": [
{
"expr": "${data.startActive}"
}
]
}
],
"enabled": true,
"variables": [],
"logLevel": "warning"
}
],
"variables": {}
}
Synchronisation
In this step, you will need to send the file to the LeanIX Endpoint along with the processor information.
Endpoint : https://<customerdomain>.leanix.net/services/integration-api/v1/synchronizationRuns
Method : POST
{
"connectorType": "importProjectsExample",
"connectorId": "importProjectsExample",
"connectorVersion": "1.0.0",
"lxVersion": "1.0.0",
"processingDirection": "inbound",
"description": "Imports Projects from default project connector",
"content": [
{
"type": "prj",
"id": "0123-459",
"data": {
"displayName": "Save the company",
"processDescription": "Most important project of our 'Herkömmliche AG'",
"startActive": "2019-12-12",
"tags": [
"Importance:High",
"Some invalid Content to be ignored",
"Effort:Medium"
]
}
}
]
}
The response of the above call will provide the id of the Synchronisation run. This id can be used in order to start the Synchronisation in the next call.
{
"id": "xxxx523c-2c03-4b16-a1f1-xxxxc9dc6e6df"
}
Start the Synchronisation
In order to start the Synchronisation which was initialised in the previous step, please make the below call.
Endpoint : https://<customerdomain>.leanix.net/services/integration-api/v1/synchronizationRuns/<id>/start
Method : POST
Check Status of Synchronisation
In order to check the status of synchronisation which was started in the last step, please make the below call. Use the same id that received as a response when the POST call to /SynchronisationRuns was made.
{
"id": "xxxx523c-2c03-4b16-a1f1-xxxxc9dc6e6df"
}
Endpoint : https://<customerdomain>.leanix.net/services/integration-api/v1/synchronizationRuns/<id>/status
Method : GET
Example response of call to /status:
{
"id": "xxxx523c-2c03-4b16-a1f1-xxxxc9dc6e6df",
"status": "FINISHED"
}
Check Details of the Synchronisation
In order to make the calls below, use the id that you received as a response to the first call made to:
https://<customerdomain>.leanix.net/services/integration-api/v1/synchronizationRuns
| Method | Endpoint | Details |
|---|---|---|
| GET | https://.leanix.net/services/integration-api/v1/synchronizationRuns/runId/status | Provides status of the Synchronization, for example FINISHED. |
| GET | https://.leanix.net/services/integration-api/v1/synchronizationRuns/runId/results | This call will produce an LDIF. The LDIF includes all Fact Sheet data which is defined in the corresponding Processor declared in the workspace. |
| GET | https://.leanix.net/services/integration-api/v1/synchronizationRuns/runId/warnings | Any issues with the run, are available. For example if an attribute that is included in the Processor, does not exist in the workspace, this will be included in the warnings. |
| POST | https://.leanix.net/services/integration-api/v1/synchronizationRuns/runId/stop | To stop a run after having initialized a run via Start. |
Import collection to Postman
You can also get the above calls by importing the below file into Postman.
- Postman data can be imported using the Import button in the header toolbar.
{
"info": {
"_postman_id": "d5fc07f1-cef1-4b28-b965-97f2c662eb4b",
"name": "Connect Integration API with Sample Connector",
"description": "Check documentation for more details :- https://dev.leanix.net/docs/connect-to-integration-api",
"schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
},
"item": [
{
"name": "Post LDIF to LeanIX",
"request": {
"method": "POST",
"header": [
{
"key": "Content-Type",
"name": "Content-Type",
"type": "text",
"value": "application/json"
}
],
"body": {
"mode": "raw",
"raw": ""
},
"url": {
"raw": "https://{{base_url}}/services/integration-api/v1/synchronizationRuns",
"protocol": "https",
"host": [
"{{base_url}}"
],
"path": [
"services",
"integration-api",
"v1",
"synchronizationRuns"
]
}
},
"response": []
},
{
"name": "Start the Sync",
"request": {
"method": "POST",
"header": [],
"url": {
"raw": "https://{{base_url}}/services/integration-api/v1/synchronizationRuns/:id/start",
"protocol": "https",
"host": [
"{{base_url}}"
],
"path": [
"services",
"integration-api",
"v1",
"synchronizationRuns",
":id",
"start"
],
"variable": [
{
"key": "id",
"value": "e546e34b-cbe5-43f2-9f43-2cbcda4c5405"
}
]
}
},
"response": []
},
{
"name": "Status of Sync",
"request": {
"auth": {
"type": "oauth2",
"oauth2": [
{
"key": "accessToken",
"value": "",
"type": "string"
},
{
"key": "tokenType",
"value": "bearer",
"type": "string"
},
{
"key": "addTokenTo",
"value": "header",
"type": "string"
}
]
},
"method": "GET",
"header": [],
"url": {
"raw": "https://{{base_url}}/services/integration-api/v1/synchronizationRuns/:id/status",
"protocol": "https",
"host": [
"{{base_url}}"
],
"path": [
"services",
"integration-api",
"v1",
"synchronizationRuns",
":id",
"status"
],
"variable": [
{
"key": "id",
"value": "e546e34b-cbe5-43f2-9f43-2cbcda4c5405"
}
]
}
},
"response": []
},
{
"name": "Results of Sync",
"request": {
"method": "GET",
"header": [],
"url": {
"raw": "https://{{base_url}}/services/integration-api/v1/synchronizationRuns/:id/results",
"protocol": "https",
"host": [
"{{base_url}}"
],
"path": [
"services",
"integration-api",
"v1",
"synchronizationRuns",
":id",
"results"
],
"variable": [
{
"key": "id",
"value": "e546e34b-cbe5-43f2-9f43-2cbcda4c5405"
}
]
}
},
"response": []
},
{
"name": "Warnings of Sync",
"request": {
"method": "GET",
"header": [],
"url": {
"raw": "https://{{base_url}}/services/integration-api/v1/synchronizationRuns/:id/warnings",
"protocol": "https",
"host": [
"{{base_url}}"
],
"path": [
"services",
"integration-api",
"v1",
"synchronizationRuns",
":id",
"warnings"
],
"variable": [
{
"key": "id",
"value": "e546e34b-cbe5-43f2-9f43-2cbcda4c5405"
}
]
}
},
"response": []
}
],
"auth": {
"type": "oauth2",
"oauth2": [
{
"key": "accessToken",
"value": "",
"type": "string"
},
{
"key": "tokenType",
"value": "bearer",
"type": "string"
},
{
"key": "addTokenTo",
"value": "header",
"type": "string"
}
]
},
"event": [
{
"listen": "prerequest",
"script": {
"id": "ec73502c-9e67-4cf0-85cf-cf8170200181",
"type": "text/javascript",
"exec": [
""
]
}
},
{
"listen": "test",
"script": {
"id": "74a45df7-6d1e-4161-9f91-cf050d515c92",
"type": "text/javascript",
"exec": [
""
]
}
}
],
"variable": [
{
"id": "99861109-e4a2-4607-9ed3-75857900a6ab",
"key": "base_url",
"value": "app.leanix.net",
"type": "string"
}
],
"protocolProfileBehavior": {}
}
Import collection to Postman
Within the Postman UI, Edit the Collection at the Parent level, updating the Authorization by clicking Get New Access Token, and providing an API token from your LeanIX workspace
Updated the raw body of the 'Post LDIF to LeanIX 'step to reflect the identifiers of the Integration API connector you would like to test
Send the Post LDIF to LeanIX request, and notice that an id is returned in the response. { "id": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" }
Pass this id to Start the Sync, and each subsequent step as a Path Variable, id. Note: Start the Sync returns no Body, just a status 200 OK
-
Import collection to Postman
-
Within the Postman UI, Edit the Collection at the Parent level, updating the Authorization by clicking Get New Access Token, and providing an API token from your LeanIX workspace.
-
Updated the raw body of the 'Post LDIF to LeanIX 'step to reflect the identifiers of the Integration API connector you would like to test.
-
Send the Post LDIF to LeanIX request, and notice that an id is returned in the response { "id": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" }
-
Pass this id to Start the Sync, and each subsequent step as a Path Variable, id. Note: Start the Sync returns no Body, just a status 200 OK.