Exporting Workspace Snapshots

Overview

While we recommend working with your inventory data and collaborating inside your workspace as much as possible, there are circumstances in which you may need to regularly download snapshots of your workspace data, for example, when it's required by your organization's policies. As an administrator, you can export your workspace data to an XLSX file in the Export section of the administration area. To learn more, see Export.

This document outlines how to programmatically export workspace snapshots.

Prerequisites

Before you start, do the following:

• Get an API token by creating a technical user with admin permissions. For instructions, see Create a Technical User.
• Learn how to authenticate to SAP LeanIX services. For details, see Authentication to SAP LeanIX Services.
• Get the ID of your workspace. To do that, in the administration area, navigate to the API Tokens section, then copy the WorkspaceId value.

Step 1: Initiate an Export Job

To get started, initiate an export job by making a POST request to the following endpoint on the Pathfinder REST API:

https://{SUBDOMAIN}.leanix.net/services/pathfinder/v1/exports/fullExport

Use the exportType query parameter to specify the export type:

• SNAPSHOT: Full snapshot of the workspace data that includes information from all active fact sheets, as well as information about related objects such as relations, tag groups, tags, resources (also referred to as documents), and comments. The snapshot doesn't include archived fact sheets. In the application UI, this export type appears as Full Snapshot.
• AUDIT_LOG: Data-related changes made to the workspace within a specified time frame. The default time frame is 30 days. In the application UI, this export type appears as Changelog.
• ARCHIVE: Full snapshot of the archived workspace data that includes information from all archived fact sheets, as well as information about related objects such as relations, tag groups, tags, resources (also referred to as documents), and comments. You can use this export option to view archived fact sheets before they are deleted at the end of the retention period. For more information, see Archiving and Recovering a Fact Sheet.

📘

Note

The /exports/fullExport endpoint supports additional export types. However, we recommend using only the export types listed in this document.

Example request:

curl -X 'POST' \
  'https://{SUBDOMAIN}.leanix.net/services/pathfinder/v1/exports/fullExport?exportType=SNAPSHOT' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -d ''

Example response:

{
  "status": "OK",
  "type": "JobResponseData",
  "data": {
    "jobId": "job:374234:cmbf4fdiozzp8q7m4u0dc1jss",
    "message": "A new job is queued.",
    "synclogId": null
  }
}

The OK status in the response indicates that an export job is initiated.

Step 2: Retrieve a One-Time Download Key

Before you download a file with workspace data, retrieve a one-time key that serves as the download identifier. To do that, make a GET request to the following endpoint:

https://{SUBDOMAIN}.leanix.net/services/pathfinder/v1/exports

📘

Note

Because the export process can be time-consuming, especially for workspaces containing large volumes of data, you might need to repeatedly call the /exports endpoint to monitor the export status. Once the status updates to COMPLETED, a one-time downloadKey is generated, which can be used to download the file as outlined in the next step.

You can optionally use query parameters to filter the results returned in the response.

Example request:

curl -X 'GET' \
  'https://{SUBDOMAIN}.leanix.net/services/pathfinder/v1/exports?exportType=SNAPSHOT&pageSize=40&sorting=createdAt&sortDirection=DESC' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}'

Example response:

{
  "status": "OK",
  "type": "Export",
  "data": [
    {
      "id": "3159d0bc-f0c1-4d6a-a541-cc534ebf7102",
      "user": {
        "id": "25d63c1a-4cc9-4c46-bb4c-a82a78cb8686",
        "firstName": null,
        "lastName": "Technical User",
        "displayName": "Technical User",
        "userName": "Technical User",
        "email": null,
        "technicalUser": true,
        "role": "ACCOUNTUSER",
        "status": "ACTIVE"
      },
      "type": "SNAPSHOT",
      "status": "COMPLETED",
      "createdAt": "2024-03-26T15:04:25.378194Z",
      "deleteAt": "2024-03-26T15:14:29.515400Z",
      "dryRun": false,
      "downloadKey": "ba25c032-f399-462e-803a-016bdf13335d",
      "factSheetTypes": null,
      "factSheetCount": null,
      "columnCount": null,
      "bookmark": null
    },
    ...
  ],
  "total": 9,
  "endCursor": "YXJyYXk6OA=="
}

Once the export status updates to COMPLETED, which indicates a successful operation, a one-time download key is generated in downloadKey. Save this key from the response.

Step 3: Retrieve a File with Workspace Data

With the downloadKey of the export, you can retrieve an XLSX file with workspace data. The downloadKey is a single-use key, valid for one download only. workspaceId is a required parameter for this request.

To retrieve a file with workspace data, make a GET request to the following endpoint:

https://{SUBDOMAIN}.leanix.net/services/pathfinder/v1/exports/downloads/{workspaceId}

Example request:

curl -X 'GET' \
  'https://{SUBDOMAIN}.leanix.net/services/pathfinder/v1/exports/downloads/b7d533f1-4aa0-4132-92c6-a390a60cbghf?key=cf1d1f70-539e-4207-acf0-64d2955007d7' \
  -H 'accept: application/octet-stream' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}'

An XLSX file is returned in the response.

Next Steps

You can automate recurring tasks, such as exporting workspace snapshots, by using cron jobs. Cron jobs are time-based job schedulers in Unix-like operating systems, which can execute commands or scripts at predefined times or intervals. For more complex scheduling or tasks, consider using task scheduling software or services that offer more advanced features and error handling.

If you want to process data from the downloaded Excel file, as a best practice, always refer to specific columns in your code using field keys (first rows in the file) instead of field descriptions (second rows in the file) or column order. Field keys are unique identifiers that remain consistent, regardless of any possible changes that can be applied to file data.