Overview

There are many options for creating, reading, updating, deleting data from and to LeanIX. Many of these options overlap which can be utilized in multiple use cases. This guide might suggest that the Integration API is the best choice for a particular use case. However, it does not suggest that you cannot achieve similar results using GraphQL for example.

Prior to taking a look at available technical tools, it is useful to have basic knowledge of the LeanIX Data Model. For an introduction to the Data Model please see Data Model.

To see the full list of APIs and details on how to use them please see the Available API section.

We have a built-in editor for many of these tools. To access them go to your Administration area click the user icon on the top right corner and select Administration:

To access GraphiQL, Webhooks, and the Integration API built-in editors see the below:

Integration API: Import/Export Data

About the API

The Integration API is extremely flexible and powerful. One of the main reasons is at the heart it is driven by a generic LeanIX Data Interchange Format (LDIF). This imparts many benefits, which include but are not limited to:

Complexity is minimized as developers no longer have to understand the LeanIX data model

No longer have to map logic inside a code

The Integration API can be utilized to build an integration between LeanIX and another vendor system. One major advantage is that the CRUD operations for any inbound (other vendor system to LeanIX ) is managed within LeanIX, which removes a great deal of complexity.

The ability to define variables, exceptions, use JUEL expressions to extract or import only particular values that meet what you define, is powerful.

Additional benefits

In addition, there are other benefits imparted by the Integration API that are not specifically related to the LDIF structure:

Configuration for LeanIX is contained in every connector

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

It can also be used to import/export from your workspace. This can be useful in cases where the built in import/export functionality doesn't have the capability that is required. An example of such a case are attributes which exist on relations. At this time it is not possible to mass update attributes on relations using the UI.

The flexibility of the Integration API shines in more complex cases such as: when the data from the source system is not in a "clean" state. In this case the Integration API would be a good option due to its error handling capabilities. It is flexible and any errors can be ignored (this is not the case with built-in Inventory import/export or GraphQL). In addition, the Integration API supports the use of JUEL/RegEx which imparts the ability to transform the source data, for example you can utilize .sum() to add up costs and then file that into a cost attribute in LeanIX. Please see the Integration API documentation for detailed information.

Use Cases

• Build an integration with an external system for example ITSM Integration.
• Make one-off updates to your workspace which you would normally use in the import/export functionality via UI.
• Merge two or more separate physical workspaces. This might be necessary in case of an acquisition or merger.

GraphQL: insights from data

GraphQL allows you to query the data on your fact sheets as well as mutate (e.g update, delete) the data. In addition, GraphQL is utilized to create custom reports, specifically to pull data from the workspace and present it using charts and other graphics.

Use the built-in GraphiQL Tool available within your LeanIX Administration area when you need answers to your fact sheet data. In addition, the GraphiQL Tool allows you to interactively develop and test queries and mutations. Which later can be utilized in scripts to automate work or custom reports.

Once in the Administration area, from the "Developers" tab select "Tools" then select GraphiQL.

GraphQL Basics

In order to get a fundamental understanding of GraphQL. You need to understand two main ideas, queries and mutations.

A query allows you to formulate precisely what arguments to return and what filters to apply.

A mutation allows you to apply patches (updates) or delete objects. Again, you can combine patches or define precisely what arguments to return.

Benefits of GraphQL

GraphQL Capabilities

The best cases for utilizing the GraphiQL Tool:

• Focus on queries, and or mutations that are one-off in nature or for which you do not need to regularly (e.g monthly, weekly) get up-to-date information.

• Where you need to pull relatively simple information. While complex queries are very much possible to an extent, there are other alternatives such as the Integration API which you might find an easier and flexible choice.

• GraphQL features heavily in custom reports because it is used to pull information from the workspace which is presented using charts and other graphics.

Endpoints and scripts

The GraphQL API endpoint can be utilized to create scripts and build a REST API. It might be best to review the functionality available within the Integration API because it is expressly created to resolve or minimize several challenges developers face when building an integration.

Please see the GraphQL in 10 minutes documentation for more detailed information on GraphQL and GraphQL Advanced.

The public LeanIX GitHub contains many scripts that utilize GraphQL. Some of the scripts are listed below:

• Update Costs
• Import Metrics
• Create Resources

More about GraphQL: reporting:

• Custom Report - Table
• Custom Report - Querying Data
• Custom Report - Visualizing Data

Webhooks: Event-Driven Information

Webhooks allow an application in LeanIX to supply other applications with real-time information. Which allows webhooks to furnish data to other applications as it occurs. In contrast to traditional APIs where to get up-to-date information, the app would need to send a request. This makes webhooks an efficient choice for providers and consumers.

What are events? Events in this context are actions that end users take within an application. Some examples are entering a response within an attribute such as the Description field, creating a new fact sheet, or even logging into LeanIX. When you need an event-driven integration, webhooks is the answer. One such use case is when you need to trigger notifications to be sent based on when a fact sheet (or an attribute/field on the fact sheet(s)) is updated, created, or deleted**.

Many systems offer a built-in user interface to allow end-users to easily create simple webhooks. LeanIX offers a user interface within the Administration area of your workspace in addition to an API endpoint.

To get an introduction to webhooks please see the "Getting Started Webhooks" documentation.

Use Cases

• Send Alerts to Slack and Teams.

• Build a Slack Bot using webhooks.

• The technical suitability is updated on a fact sheet, this event can trigger a tag to be automatically added to the fact sheet. Please see the Azure Function Tutorial: TIME tutorial for an example of this implemented with Webhooks and Azure function.

• Utilizing the responses from a LeanIX survey to calculate a particular score and the score can be automatically set to be associated with a fact sheet.

Metrics: Data Over Time

With Metrics you can store time series data in LeanIX and create interactive charts to display the data. In addition, the data can be linked to Fact Sheets presented on Dashboard or be displayed within the Reports area.

Metrics consist of several objects including measurements. Measurements contain data-points stored over time, which are related to the same topic. Each data-point is stored for a specific moment and has one or more values for that instance of time.

Metrics are very specific to cases when there are data points that are time based. One such example is when expenses or other costs need to be understood on the basis of time.

For more information please see Getting Started with Metrics.

Available APIs

LeanIX is built with a Microservices architecture, with different services and API endpoints. Below is a list of all public APIs. For each entry, the main resources, endpoint URL and links to Swagger API References are listed.

Your Endpoint Base URL (often referred to with the variable 'base_url' in our public scripts and tutorial examples) will vary depending the domain of your workspace. The simplest way to determine your endpoint base URL is to pull it directly from the URL displayed in your browser when navigating your workspace "https://...leanix.net".

For example:

If my main dashboard URL were https://MyCompany.leanix.net/MyCompanyWorkspace/dashboard/184710fa-4272-4163-ba99-ddfcb46eaf4a, my endpoint URL would be https://MyCompany.leanix.net

To access the APIs as well as to see what your workspace instance is. Select About LeanIX and then Browse API:

Pathfinder API: Inventory

Information about used applications, technologies, projects and more objects can be stored in the IT Inventory of LeanIX. LeanIX provides a Data Model called "Fact Sheets" out of the box. Via Pathfinder API you can interact with this data model.

Endpoint : <base_url>/services/pathfinder/v1, e.g. https://app.leanix.net/services/pathfinder/v1

Pathfinder: Scripts

• Archive fact sheets
• Export Costs

MTM API: Authentication & User Management

User Management

MTM stands for Multi-Tenancy Manager. It is a central service of LeanIX to manage workspaces and user accounts. It also provides OAuth2 endpoints for authentication of users.

Not all resources with the MTM API are available to ADMINs. There are endpoints that are visible within the Swagger documentation which are only available to LeanIX employees. Such are marked as "Restricted to LeanIX internal use only." in the endpoint description.

Below is a list of the resources available to customers. Please note that this is not the exhaustive list.

Admins role cannot see all API Tokens in a workspace. API tokens are personalized identification tokens specific to a user. The user's credentials are part of the encryption of the token. This is also what binds API-tokens to a specific user, any updates performed by the API token will be performed in the user's name. It is by design that API tokens are not visible to other users, even Admins. If you have shared services (Integrations, webhooks, etc.) which use API-tokens which you would like multiple people to have access to please make use of the technical user functionality. The technical user functionality is designed with that use case in mind.

Who can see what:

• User X is only able to see their own API-tokens.
• Even the SUPERADMIN support user can only see our own tokens.

Additionally, the moment an Admin archived a user all issued API-tokens for that user become invalid immediately.

📘

Information

We have configured it in such a way that the tokens will expire after a specific time period due to inactivity.

Please see the highlighted image below for the specific endpoints available to ADMINs under workspaces:Manage workspaces:

Endpoint : <base_url>/services/mtm/v1, e.g. https://app.leanix.net/services/mtm/v1

Please do not use API tokens if you have central management as a requirement. We offer Technical users for such use cases. Technical user tokens can be generated by an administrator and will be manageable and visible by all administrators in our UI.

🚧

Attention!

For user management, please always use the endpoint:
https://eu-svc.leanix.net/services/mtm/v1/docs/#!/workspaces

USA customers please utilize:
https://us-svc.leanix.net/services/mtm/v1/docs/#!/workspaces

Also, see User Management

MTM: Scripts

• Correct User Account

• Get Users

Webhooks API: Event Subscriptions

Webhooks allows you to receive information about events as they happen near real-time in LeanIX. You can then extend, customize, and integrate LeanIX with your own extensions or even with other applications.

Endpoint : <base_url>/services/webhooks/v1, e.g. https://app.leanix.net/services/webhooks/v1**

Metrics API: Real-Time Data

The Metrics add-on allows you to store time-series data in LeanIX. This data can come from various sources which are relevant to Business, Development or Operations.

Endpoint : <base_url>/services/metrics/v1, e.g. https://app.leanix.net/services/metrics/v1

Metrics: Scripts

• Import Metrics

Poll API: Custom Surveys

With the Survey add-on, admins can design own questionnaires in LeanIX which they send out to get the answers from users. The results of the surveys are displayed in context of LeanIX and can be accessed via API.

Endpoint: <base_url>/services/poll/v2, e.g. https://app.leanix.net/services/poll/v2

Integration API: Import/Export Data and Build Integrations

The Integration API provides the ability to import/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. In addition, building integrations between LeanIX and other vendor systems is simplified using the Integration API. One of the reason is because all mapping and processing of the incoming and outgoing data is done using "Data Processors" that are configured behind the API. For detailed information including use cases please see Integration API.

Endpoint : <base_url>/services/integration-api/v1, e.g. https://app.leanix.net/services/integration-api/v1