GraphQL Basics

Here we describe how to interact with the Inventory via the GraphQL API

Queries

A good source for learning the GraphQL syntax and concepts can be found here. The easiest way to execute a query is using the GraphiQL in-browser IDE which is embedded into the LeanIX Administration (Go to menu entry Developers / Tools). The following examples demonstrate some example queries and mutations based on the default out-of-the-box data model. If you have customized the data model, please make sure to adapt your queries.

The endpoint for queries is: https://<instance>.leanix.net/services/pathfinder/v1/graphql.

GraphiQL

You can explore the schema of your workspace on the right hand side in GraphiQL. An exclamation mark behind an attribute indicates a must field (may not be null).

Get a list of Fact Sheets

The following example shows how to pass a limit of 2 and a filter to the allFactSheets query. The result includes nodes of the type BaseFactSheet the displayName and the type of each Fact Sheet.

{
  allFactSheets(first: 2, filter: {facetFilters: [{facetKey: "FactSheetTypes", keys: ["Application"]}]}) {
    totalCount
    edges {
      node {
        id
        displayName
        type
      }
    }
  }
}
{
  "data": {
    "allFactSheets": {
      "totalCount": 116,
      "edges": [
        {
          "node": {
            "id": "RlM6ZWVkNTU2ZWQtZDRkZi00MDRkLTliMGUtMjYzNmQ3NjZhOWJj",
            "displayName": "AC Management",
            "type": "Application"
          }
        },
        {
          "node": {
            "id": "RlM6YTVmM2EyOTMtNmYzZS00ZWQ1LWIyNjYtMmQzYzUwMTk2Y2M4",
            "displayName": "AttorneyNet",
            "type": "Application"
          }
        }
      ]
    }
  }
}

Get a list of filtering facet keys

This example shows how to fetch a list of all the facet keys in a workspace.

{
  allFactSheets{
    filterOptions {
      facets {
        facetKey
        results {
          name
          key
        }
      }
    }
  }
}
{
  "data": {
    "allFactSheets": {
      "filterOptions": {
        "facets": [
          {
            "facetKey": "FactSheetTypes",
            "results": [
              {
                "name": "BusinessCapability",
                "key": "BusinessCapability"
              },
              {
                "name": "Process",
                "key": "Process"
              },
              {
                "name": "UserGroup",
                "key": "UserGroup"
              },
              {
                "name": "Project",
                "key": "Project"
              },
              {
                "name": "Application",
                "key": "Application"
              },
              {
                "name": "Interface",
                "key": "Interface"
              },
              {
                "name": "DataObject",
                "key": "DataObject"
              },
              {
                "name": "ITComponent",
                "key": "ITComponent"
              },
              {
                "name": "Provider",
                "key": "Provider"
              },
              {
                "name": "TechnicalStack",
                "key": "TechnicalStack"
              }
            ]
          },
          {
            "facetKey": "hierarchyLevel",
            "results": [
              {
                "name": "1",
                "key": "1"
              },
              {
                "name": "2",
                "key": "2"
              },
              {
                "name": "3",
                "key": "3"
              }
            ]
          },
          {
            "facetKey": "DataQuality",
            "results": [
              {
                "name": "noResponsible",
                "key": "_noResponsible_"
              },
              {
                "name": "qualitySealBroken",
                "key": "_qualitySealBroken_"
              },
              {
                "name": "noDescription",
                "key": "_noDescription_"
              },
              {
                "name": "noLifecycle",
                "key": "_noLifecycle_"
              }
            ]
          },
          {
            "facetKey": "_TAGS_",
            "results": [
              {
                "name": "Headquarter",
                "key": "aa51ccc9-db61-48df-89d1-f217f37757ea"
              },
              {
                "name": "Tag2",
                "key": "819d3d4f-f044-470a-8f5d-c11bc15eff67"
              }
            ]
          }
        ]
      }
    }
  },
  "errors": null
}

Paging

For paging a list of results, the concept of cursors is employed. We use the concept of Relay Cursor Connections.

Pagination is done by inserting a cursor for the after argument. For the initial cursor, the empty string can be used (or the argument can be omitted, as in the example above).

The following query will retrieve the first 2 Fact Sheets from the beginning:

{
  allFactSheets(first: 2, after: "") {
    edges {
      cursor
      node {
        name
      }
    }
  }
}
{
  "data": {
    "allFactSheets": {
      "edges": [
        {
          "cursor": "YXJyYXljb25uZWN0aW9uOjA=",
          "node": {
            "name": "AC Management"
          }
        },
        {
          "cursor": "YXJyYXljb25uZWN0aW9uOjE=",
          "node": {
            "name": "accenture"
          }
        }
      ]
    }
  },
  "errors": null
}

A PageInfo object can be included in the request. This object contains informations about the paging state, e.g. if there are more pages available hasNextPage and the position of the current paging cursor endCursor.

{
  allFactSheets(first: 2, after: "") {
    pageInfo {
      hasNextPage
      endCursor
    }
    edges {
      cursor
      node {
        name
      }
    }
  }
}
{
  "data": {
    "allFactSheets": {
      "pageInfo": {
        "hasNextPage": true,
        "endCursor": "YXJyYXljb25uZWN0aW9uOjE="
      },
      "edges": [
        {
          "cursor": "YXJyYXljb25uZWN0aW9uOjA=",
          "node": {
            "name": "AC Management"
          }
        },
        {
          "cursor": "YXJyYXljb25uZWN0aW9uOjE=",
          "node": {
            "name": "accenture"
          }
        }
      ]
    }
  },
  "errors": null
}

In order to retrieve the next 2 results in the example above, one has to enter the value of endCursor for the argument after:

{
  allFactSheets(first: 2, after: "YXJyYXljb25uZWN0aW9uOjE=") {
    pageInfo {
      hasNextPage
      endCursor
    }
    edges {
      cursor
      node {
        name
      }
    }
  }
}
{
  "data": {
    "allFactSheets": {
      "pageInfo": {
        "hasNextPage": true,
        "endCursor": "YXJyYXljb25uZWN0aW9uOjM="
      },
      "edges": [
        {
          "cursor": "YXJyYXljb25uZWN0aW9uOjI=",
          "node": {
            "name": "Account"
          }
        },
        {
          "cursor": "YXJyYXljb25uZWN0aW9uOjM=",
          "node": {
            "name": "acctur"
          }
        }
      ]
    }
  },
  "errors": null
}

Access type-specific attributes

In the example above, only common attributes of the BaseFactSheet, such as displayName can be accessed. We use the concept of Union Types to cast the nodes to the right type and access specific attribute, in this case businessCriticality.

{
  allFactSheets(first: 2, filter: {facetFilters: [{facetKey: "FactSheetTypes", keys: ["Application"]}]}) {
    totalCount
    edges {
      node {
        id
        displayName
        ... on Application {
          businessCriticality
        }
      }
    }
  }
}
{
  "data": {
    "allFactSheets": {
      "totalCount": 109,
      "edges": [
        {
          "node": {
            "id": "b94dd413-7423-44f0-90ba-de794e55e2f0",
            "displayName": "AC Management",
            "businessCriticality": "missionCritical"
          }
        },
        {
          "node": {
            "id": "cfd7f79a-2ce2-4931-b4f4-91f69e48ff7e",
            "displayName": "AttorneyNet",
            "businessCriticality": "businessCritical"
          }
        }
      ]
    }
  },
  "errors": null
}

Filter for lifecycle attributes

This example shows how to fetch a list of all factsheets of a certain type (here: Applications) with a certain lifecycle (here: End of Life).
Make sure to add a date filter.

query allFactSheetsQuery($filter: FilterInput!) {
  allFactSheets(filter: $filter) {
    totalCount
    edges {
      node {
        ... on Application {
          id
          displayName
          ApplicationLifecycle: lifecycle {
            asString
          }
        }
      }
    }
  }
}


{"filter":{"facetFilters":[{"facetKey":"FactSheetTypes","operator":"OR","keys":["Application"]},
  {"facetKey":"lifecycle","operator":"OR","keys":["endOfLife"],
    "dateFilter":{"type":"TODAY","from":"2018-11-27","to":"2018-11-27"} } ] } }

{
  "data": {
    "allFactSheets": {
      "totalCount": 29,
      "edges": [
        {
          "node": {
            "id": "04ffff0d-490d-46db-9ad3-5124f790eee1",
            "displayName": "ABC",
            "ApplicationLifecycle": {
              "asString": "endOfLife"
            }
          }
        },
        {
          "node": {
            "id": "92ffc60e-a0e7-4139-a4a5-4d4271dfec23",
            "displayName": "QWERT",
            "ApplicationLifecycle": {
              "asString": "endOfLife"
            }
          }
        },
        {
          "node": {
            "id": "bfffd9a2-69ea-4245-8ebd-ed0aeecf384d",
            "displayName": "XYZ",
            "ApplicationLifecycle": {
              "asString": "endOfLife"
            }
          }
        },

Access related Fact Sheets and Children.

In the following example, we fetched all related IT Components of a single TechStack and his children with their related IT Components.

{
  factSheet(id: "7638b02f-edb3-4b21-94eb-b4098e3b18d9") {
    displayName
    ... on TechnicalStack {
      relTechnologyStackToITComponent {
        edges {
          node {
            id
            factSheet {
              name
              displayName
            }
          }
        }
      }
      relToChild {
        edges {
          node {
            id
            factSheet {
              displayName
              ... on TechnicalStack {
                relTechnologyStackToITComponent {
                  edges {
                    node {
                      id
                      factSheet {
                        name
                        displayName
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}
{
  "data": {
    "factSheet": {
      "displayName": "Database",
      "relTechnologyStackToITComponent": {
        "edges": [
          {
            "node": {
              "id": "bc961789-4038-41ba-a364-2355c7d036b1",
              "factSheet": {
                "name": "Application Hosting",
                "displayName": "Acoce Application Hosting"
              }
            }
          },
          {
            "node": {
              "id": "243ceda1-9a57-406c-bfe4-24b380992c57",
              "factSheet": {
                "name": "Application Hosting",
                "displayName": "Application Hosting"
              }
            }
          },
          {
            "node": {
              "id": "cef20cca-eed8-42e7-bd4b-ab393f584ec6",
              "factSheet": {
                "name": "Application Hosting",
                "displayName": "AutoCAD Application Hosting"
              }
            }
          }
        ]
      },
      "relToChild": {
        "edges": [
          {
            "node": {
              "id": "034c78d6-4a40-447e-8b99-1a43d6cb4d67",
              "factSheet": {
                "name": "Non-relational Database",
                "displayName": "Database / Non-relational Database",
                "relTechnologyStackToITComponent": {
                  "edges": [
                    {
                      "node": {
                        "id": "8896dfb3-c33a-490f-bc06-601bd7446720",
                        "factSheet": {
                          "name": "Application Hosting",
                          "displayName": "Customer King Application Hosting"
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          {
            "node": {
              "id": "764fb9d4-9bb5-4909-a8f2-26ae9db382e0",
              "factSheet": {
                "name": "Relational Database",
                "displayName": "Database / Relational Database",
                "relTechnologyStackToITComponent": {
                  "edges": [
                    {
                      "node": {
                        "id": "c9586ed8-cf40-4a07-8efb-26f63f3a04de",
                        "factSheet": {
                          "name": "SQL Server",
                          "displayName": "Microsoft SQL Server 2000 Standard Edition / 2000 Standard Edition"
                        }
                      }
                    },
                    {
                      "node": {
                        "id": "2ff1948a-2b30-4b26-9997-60c97f443102",
                        "factSheet": {
                          "name": "SQL Server",
                          "displayName": "Microsoft SQL Server 2005 Express Edition / 2005 Express Edition"
                        }
                      }
                    },
                    {
                      "node": {
                        "id": "cc6766d1-0d6c-4ebd-9081-05a2a676439e",
                        "factSheet": {
                          "name": "SQL Server",
                          "displayName": "Microsoft SQL Server 2008 Enterprise / 2008 Enterprise"
                        }
                      }
                    },
                    {
                      "node": {
                        "id": "b8ca2bf6-bbfe-4661-9871-6f0ae8343de9",
                        "factSheet": {
                          "name": "SQL Server",
                          "displayName": "Microsoft SQL Server 2008 Web / 2008 Web"
                        }
                      }
                    },
                    {
                      "node": {
                        "id": "2be23cc9-5f29-48c5-85f5-94007eeef491",
                        "factSheet": {
                          "name": "Database",
                          "displayName": "Oracle Database 10g 10.2 / 10g 10.2"
                        }
                      }
                    },
                    {
                      "node": {
                        "id": "9ebc63af-5dc3-4053-85ba-eee4ba0e15ad",
                        "factSheet": {
                          "name": "Database",
                          "displayName": "Oracle Database 11g 11.1 / 11g 11.1"
                        }
                      }
                    },
                    {
                      "node": {
                        "id": "6873451b-978a-423b-9213-eed9a7498e1a",
                        "factSheet": {
                          "name": "Database",
                          "displayName": "Oracle Database 11g 11.2 / 11g 11.2"
                        }
                      }
                    },
                    {
                      "node": {
                        "id": "e3c6e0ae-6700-490c-aac8-5a5fc7e82f20",
                        "factSheet": {
                          "name": "MySQL Database",
                          "displayName": "Oracle MySQL Database 5.0 / 5.0"
                        }
                      }
                    },
                    {
                      "node": {
                        "id": "b01dae8e-bd96-4d54-ad11-05171c7d1ff1",
                        "factSheet": {
                          "name": "MySQL Database",
                          "displayName": "Oracle MySQL Database 5.1 / 5.1"
                        }
                      }
                    },
                    {
                      "node": {
                        "id": "78e1bd28-80be-4ae5-8c70-8a511fefd118",
                        "factSheet": {
                          "name": "MySQL Database",
                          "displayName": "Oracle MySQL Database 5.5 / 5.5"
                        }
                      }
                    }
                  ]
                }
              }
            }
          }
        ]
      }
    }
  },
  "errors": null
}

Get a single Fact Sheet

A single Fact Sheet can be retrieved via its unique ID.

query {
  factSheet(id: "b94dd413-7423-44f0-90ba-de794e55e2f0") {
    displayName
    ... on Application {
      businessCriticality
    }
  }
}
{
  "data": {
    "factSheet": {
      "displayName": "AC Management",
      "businessCriticality": "missionCritical"
    }
  },
  "errors": null
}

Get a FactSheet by its External ID

If you want to search for Fact Sheets by the ExternalID field "externalId" and you want to find all matching the ID "1234", use the following query.

query {
  allFactSheets(first: 1, filter: {externalIds: ["externalId/1234"]}) {
    totalCount
    edges {
      node {
        id
        displayName
        ... on Application {
          externalId {
            externalId
          }
        }
      }
    }
  }
}
{
  "data": {
    "allFactSheets": {
      "totalCount": 1,
      "edges": [
        {
          "node": {
            "id": "2d774e7c-6a48-48d3-a1d3-38b3c0cba713",
            "displayName": "Test",
            "externalId": {
              "externalId": "1234"
            }
          }
        }
      ]
    }
  },
  "errors": null
}

Mutations

GraphQL Mutations are used to create, update or delete Fact Sheets.

Create a Fact Sheet

To add a Fact Sheet, the mutation createFactSheet is used. The fields name and type of the BaseFactSheetInput are mandatory to create a new Fact Sheet. The result includes the newly created id and revision rev.

mutation ($input: BaseFactSheetInput!) {
  createFactSheet(input: $input) {
    factSheet {
      id
      name
      rev
      type
    }
  }
}

Query Variables:
{
  "input":{"name":"New Fact Sheet", "type": "Application"}
}
{
  "data": {
    "createFactSheet": {
      "factSheet": {
        "id": "142d61ce-3dfc-4516-a108-a871fbe3f929",
        "name": "New Fact Sheet",
        "rev": 1,
        "type": "Application"
      }
    }
  },
  "errors": null
}

Update a Fact Sheet

The updateFactSheet mutation changes an existing Fact Sheet by following the "JSON Patch" logic described in RFC 6902. A list of mutations is passed to the mutation, the result can include a query to the Fact Sheet. If a revision rev is given, it must match the current version in the inventory. Via the parameter validateOnly it is possible to test the mutation for potential errors.

mutation ($patches: [Patch]!) {
  result: updateFactSheet(id: "142d61ce-3dfc-4516-a108-a871fbe3f929", 
    rev: 1, patches: $patches, validateOnly: false) {
    factSheet {
      ... on Application {
        rev
        displayName
        name
        release
        displayName
        alias
        description
      }
    }
  }
}

Query Variables:
{
 "patches": [{"op":"replace","path":"/name","value":"New Name"}]
}
{
  "data": {
    "result": {
      "factSheet": {
        "rev": 2,
        "displayName": "New Name",
        "name": "New Name",
        "release": "",
        "alias": "",
        "description": null
      }
    }
  },
  "errors": null
}

Adding relations between Fact Sheets

The updateFactSheet mutation can also be used in order to add one or more relations from one Fact Sheet to another Fact Sheet. A patch object with operation "add" needs to be provided with a "path" that identifies the relation attribute. Several adds on the same relation path can be done within a single request. To distinguish possible errors in the response we have to add a suffix /new_1 (for the next relation /new_2 and so on) to the paths to get dedicated error messages.

mutation ($patches: [Patch]!) {
  updateFactSheet(id: "142d61ce-3dfc-4516-a108-a871fbe3f929", rev: 2, patches: $patches) {
    factSheet {
      id
      displayName
      ... on Application {
        relApplicationToUserGroup {
          edges {
            node {
              id
            }
          }
        }
      }
    }
  }
}

Query Variables:
{
  "patches": [
    {
      "op": "add",
      "path": "/relApplicationToUserGroup/new_1",
      "value": "{\"factSheetId\":\"5e85b861-97f7-4b87-987e-7566694d8fdf\"}"
    },
    {
      "op": "add",
      "path": "/relApplicationToUserGroup/new_2",
      "value": "{\"factSheetId\":\"ad45f3e0-4739-4533-a62b-dd2074420d55\"}"
    }
  ]
}

The following JSON response contains an example for an error message that might be returned by the server. Please note that the path now identifies the corresponding patch operation from the request.

{
  "message": "[FS_VALIDATION_RELATION_NOT_UNIQUE_OUTGOING] Outgoing relation to the same Fact Sheet occurred twice! relation name = 'applicationUserGroupRelation', from = 'New Name', from type = 'Application', to = 'Australia', to type = 'UserGroup'",
  "gqlPath": "updateFactSheet",
  "errorType": "MODEL_COMPLIANT",
  "entityType": "FACT_SHEET",
  "objectId": "142d61ce-3dfc-4516-a108-a871fbe3f929",
  "path": "/relApplicationToUserGroup/new_1"
}

Removing relations

Removing relations works with the updateFactSheet mutation as well, only with patch operation "remove". Note that you require the id of the relation in the patch.

mutation ($patches: [Patch]!) {
  updateFactSheet(id: "142d61ce-3dfc-4516-a108-a871fbe3f929", rev: 2, patches: $patches) {
    factSheet {
      id
      displayName
      ... on Application {
        relApplicationToUserGroup {
          edges {
            node {
              id
            }
          }
        }
      }
    }
  }
}

Query Variables:
{
  "patches": [
    {
      "op": "remove",
      "path": "/relApplicationToUserGroup/8c0bc078-1585-4b05-9450-2d83d970441f"
    }
  ]
}

Adding documents and subscriptions to a Fact Sheet

This topic is described in the advanced section here

Delete and recover a Fact Sheet

In LeanIX, deleting a Fact Sheet means changing its internal status to ARCHIVED. This change is executed via the updateFactSheet mutation. A comment needs to be provided. The Fact Sheet can be recovered again by setting the status to ACTIVE.

mutation ($patches: [Patch]!) {
  result: updateFactSheet(id: "142d61ce-3dfc-4516-a108-a871fbe3f929", 
    rev: 1, comment: "Delete FS", patches: $patches, validateOnly: false) {
    factSheet {
      ... on Application {
        status
        rev
        type
      }
    }
  }
}

Query Variables:
{
 "patches":[{"op":"add","path":"/status","value":"ARCHIVED"}]
}
{
  "data": {
    "result": {
      "factSheet": {
        "status": "ARCHIVED",
        "rev": 4,
        "type": "Application"
      }
    }
  },
  "errors": null
}

Schema

Explore the meta-data

The following query retrieves the meta-data about the GraphQL schema. This introspection functionality is also used by the GraphiQL in-browser IDE to show the documentation on the right-hand side and to provide the typeahead functionality in the editor.

query {
  __schema {
    types {
      name
      kind
      interfaces {
        kind
        name
      }
      fields {
        name
      }
      inputFields {
        name
        defaultValue
      }
    }
    queryType {
      name
    }
  }
}

Updated 5 months ago

GraphQL Basics


Here we describe how to interact with the Inventory via the GraphQL API

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.