Integration API

Overview

The Integration API provides the ability to import and export data using a generic LeanIX Data Interchange Format (LDIF). LDIF is a JSON format with a very simple structure described in the following sections. All mapping and processing of the incoming and outgoing data is done using "Data Processors" that are configured behind the API. Configuration of the processors can be done using the UI, please see the Setup page for more information. The configurations can be managed using the Integration API as well.

Advantages

• Complexity is minimized as developers no longer have to understand the LeanIX data model
• Configuration for LeanIX is contained in every connector
• No longer having to map logic inside of code
• Integration now possible even if the external system does not allow direct access
• No need for a direct REST connection
• Flexible error handling, no failure due to a single or even multiple data issues. Data that does not meet the requirements, is simply ignored
• Cross-cutting concerns are part of the API and in each connector

Inbound and Outbound Data Processors

Definitions

Inbound Data Processors read the incoming LDIF format, process and convert it into a set of commands the Integration API can understand. Then it executes it against the LeanIX backend database (Pathfinder) or in the case of inboundMetrics the Metrics API.

Outbound Data Processors read data from the workspace and export it to an LDIF. The content of the produced LDIF will depend on the configured data processors.

General Flags

There are flags that can be set within the Processors, whether they be outbound or inbound.

LeanIX Data Interchange Format (LDIF)

All data sent (inbound Data Processor) to the LeanIX Integration API needs to be in a standard format, called LDIF. For synchronization of data from LeanIX to other systems (outbound Data Processor), the Integration API will provide all data in the same format as well.

The LDIF contains the following information:

Data sent from the external system to LeanIX. Or in the case of outbound, data extracted from LeanIX.

Metadata information to identify the connector instance that wrote the LDIF. The metadata is used to define ownership of entities in LeanIX if we need to ensure name spacing/deletion

Identification of the target workspace and the target API version

Allow customers adding some arbitrary description for any kind of grouping, notification or any unstructured notes for display purposes that is not processed by the API

Mandatory Elements

📘

Incoming data cannot be processed if the corresponding connectorType has not been configured for the LeanIX workspace.

Content Section

The content section contains a list of Data Objects. This section contains the data collected from the external system or the data to be sent to the external system. Each Data Object is defined by an "id" (typically a UUID in the source system), a type to group the source information and a map of data elements. The keys "id", "type" and "data are mandatory. The data map may be flat or hierarchical maps. Values of map entries may be single string values, maps or lists.

📘

Mandatory attributes in Content Section

The above three attributes are always required in each content block. Additional attributes like name and description can be placed under data.

Optional Elements

📘

LDIF Notes

• Additional fields in the LDIF that do not match the requirements of defined here will be silently ignored.
• Each of the values listed above, except the values in the "content" section must not be longer than 500 characters.

Example

{
 "connectorType": "cloudockit",
 "connectorId": "CDK",
 "connectorVersion": "1.0.0",
 "lxVersion": "1.0.0",
 "lxWorkspace": "workspace-id",
 "description": "Imports Cloudockit data into LeanIX",
 "processingDirection": "inbound",
 "processingMode": "partial",
 "content": [
  {
   "type": "ITComponent",
   "id": "b6992b1d-4e4d",
   "data": {
    "name": "Gatsby.j",
    "description": "Gatsby is a free and open source framework based on React that helps developers build websites and apps.",
    "category": "sample_software",
    "provider": "gcp",
    "applicationId": "28db27b1-fc55-4e44"
   }
  },
  {
   "type": "ITComponent",
   "id": "cd4fab6c-4336",
   "data": {
    "name": "Contentful",
    "description": "Beyond headless CMS, Contentful is an API-first content management infrastructure to create, manage and distribute content to any platform or device.",
    "category": "cloud_service",
    "provider": "gcp",
    "applicationId": "28db27b1-fc55-4e44"
   }
  },
  {
   "type": "ITComponent",
   "id": "3eaaa629-5338-41f4",
   "data": {
    "name": "GitHub",
    "description": "GitHub is a tool that provides hosting for software development version control using Git.",
    "category": "cloud_service",
    "provider": "gcp",
    "applicationId": "28db27b1-fc55-4e44"
   }
  },
  {
   "type": "Application",
   "id": "28db27b1-fc55-4e44",
   "data": {
    "name": "Book a Room Internal",
    "description": "Web application that's used internal to book rooms for a meeting."
   }
  }
 ]
}

Example: Lifecycles

{
 "connectorType": "cloudockit",
 "connectorId": "CDK",
 "connectorVersion": "1.0.0",
 "lxVersion": "1.0.0",
 "lxWorkspace": "workspace-id",
 "description": "Imports Cloudockit data into LeanIX",
 "processingDirection": "inbound",
 "processingMode": "partial",
 "content": [
  {
   "type": "Application",
   "id": "company_app_1",
   "data": {
    "name": "TurboTax",
    "plan": null,
    "phaseIn": "2016-12-29",
    "active": "2019-12-29",
    "phaseOut": "2020-06-29",
    "endOfLife": "2020-12-29"
   }
  },
  {
   "type": "Application",
   "id": "company_app_2",
   "data": {
    "name": "QuickBooks",
    "plan": null,
    "phaseIn": "2016-11-29",
    "active": "2019-11-29",
    "phaseOut": "2020-05-29",
    "endOfLife": "2020-11-29"
   }
  }
 ]
}

Sending an LDIF to the endpoint

Endpoint : <base_url>/services/integration-api/v1, e.g. https://app.leanix.net/services/integration-api/v1
For more information on interacting with the Integration API endpoints, please see:
Swagger API Reference
Swagger JSON

Grouped Execution of multiple Integration API configurations

A new key "executionGroups" added to the main section now allows Integration API to execute multiple Integration API configurations as if they were one. This is advanced functionality, not available in the UI but only when using the REST API. See the Swagger documentation how to call.

Example

{
 "processors": [
  {
   "processorType": "inboundTag",
   "processorName": "Set TIME tags",
   "processorDescription": "Sets the TIME tags based on existing Fact Sheet values",
   "filter": {
    "advanced": "${integration.contentIndex==0}"
   },
   "identifier": {
    "search": {
     "scope": {
      "ids": [],
      "facetFilters": [
       {
        "keys": [
         "Application"
        ],
        "facetKey": "FactSheetTypes",
        "operator": "OR"
       }
      ]
     }
    }
   },
   "run": 0,
   "updates": [
    {
     "key": {
      "expr": "name"
     },
     "values": [
      {
       "expr": "${((lx.factsheet.functionalSuitability=='unreasonable' || lx.factsheet.functionalSuitability=='insufficient') && (lx.factsheet.technicalSuitability=='inappropriate' || lx.factsheet.technicalSuitability=='unreasonable'))?'Eliminate':null}"
      },
      {
       "expr": "${((lx.factsheet.functionalSuitability=='appropriate' || lx.factsheet.functionalSuitability=='perfect') && (lx.factsheet.technicalSuitability=='inappropriate' || lx.factsheet.technicalSuitability=='unreasonable'))?'Migrate':null}"
      },
      {
       "expr": "${((lx.factsheet.functionalSuitability=='unreasonable' || lx.factsheet.functionalSuitability=='insufficient') && (lx.factsheet.technicalSuitability=='adequate' || lx.factsheet.technicalSuitability=='fullyAppropriate'))?'Tolerate':null}"
      },
      {
       "expr": "${((lx.factsheet.functionalSuitability=='appropriate' || lx.factsheet.functionalSuitability=='perfect') && (lx.factsheet.technicalSuitability=='adequate' || lx.factsheet.technicalSuitability=='fullyAppropriate'))?'Invest':null}"
      },
      {
       "expr": "No Data"
      }
     ]
    },
    {
     "key": {
      "expr": "group.name"
     },
     "values": [
      {
       "expr": "Time Model"
      }
     ]
    }
   ],
   "logLevel": "warning",
   "read": {
    "fields": [
     "technicalSuitability",
     "name",
     "functionalSuitability"
    ]
   }
  }
 ],
 "executionGroups": [
  "customGroupA",
  "anotherGroup",
  "myGroup"
 ]
}

Calling /synchronizationRuns/createSynchronizationRunWithExecutionGroup with parameter "customGroupA" will run all configurations that contain "customGroupA" in the list of "executionGroups" defined.

❗️

Advanced functionality - Use with careful management of configuratinos

The system will merge the configurations and use all processors from all configurations. There will be no ordering applied. Processors from different configurations with same run levels will run in parallel.
Conflicting settings like mixing inbound and outbound configurations will result in an error. Other special logic like settings for e.g. a data consumer will be taken from any configuration. If multiple ones are found, the run will be executed with the last found configuration.
In order to detect the "last found configuration", Integration API configurations with a matching tag will be sorted alphabetically and merged one by one. Sorting happens by type, then id, then version.

Comments in Integration API processors

Integration API allows to solve simple mapping tasks as well solving highly complex processing and aggregation use cases.
Documentation of more complex processing is key for maintenance work in case of changes. Integration API allows to add "description" keys in the locations listed in the below examples. The free text will be stored with the configuration but not be used for any processing. It is just used to document more complex expressions used.

Example: Inbound processors

{
 "identifier": {
  "description": "We iterate over all Fact Sheets of type 'Application'"
 },
 "variables": [
  {
   "description": "Write a variable for each found child to copy description to that later",
   "key": "collectedChild_${integration.variables.valueOfForEach.target.id}",
   "value": "${lx.factsheet.description}",
   "forEach": {
    "elementOf": "${lx.relations}"
   }
  },
  {
   "description": "Write all children to one variable to iterate over in later processor",
   "key": "collectedChildren",
   "value": "${integration.variables.valueOfForEach.target.id}",
   "forEach": {
    "elementOf": "${lx.relations}"
   }
  }
 ],
 "updates": [
  {
   "description": "Values to writing the field Business Fit are taken from a variable",
   "values": [
    {
     "description": "The source variable is names Businessfit_[currentFactSheetId]"
    }
   ]
  }
 ]
}

Example: Outbound Processors

{
 "output": [
  {
   "description": "xxxxx",
   "key": {
    "expr": "content.id"
   },
   "values": [
    {
     "description": "vvv"
    }
   ]
  }
 ]
}