Setting Up Your Custom Reports Project

Overview

The LeanIX Reporting CLI is a tool designed to aid in the creation of custom reports within the LeanIX Reporting Framework. The LeanIX Reporting CLI enables you to scaffold a project skeleton equipped with all the necessary files and dependencies, which significantly accelerates your development workflow.

In this tutorial, you'll learn how to configure your system using the scaffolder of the LeanIX Reporting CLI.

By the end of this tutorial, you'll be able to scaffold your custom reports project.

📘

Note

While the LeanIX Reporting Library does not enforce a specific JavaScript framework or CSS preprocessors, it provides a basic setup with JavaScript ES6 and Webpack.

Prerequisites

Before you start, install NodeJS LTS on your system.

This tutorial assumes you have basic knowledge of:

• LeanIX Reporting Library
• LeanIX reports
• JavaScript (ES6)
• Webpack
• Chart.js
• Tailwind CSS

📘

Recommendation

While our tutorials are framework-agnostic for ease of understanding, incorporating a framework such as Tailwind CSS or Vue.js can significantly decrease the amount of manual code needed for complex reports. We highly recommend exploring these frameworks to streamline your development process.

Step 1: Install the LeanIX Reporting CLI

To get started, install the LeanIX Reporting CLI using the following command:

npm install -g @leanix/reporting-cli

To verify the installation, run the following command:

lxr --version
1.0.0-beta.21

Step 2: Create Your Project Directory

To create a directory where you want to host your project, run the following command:

mkdir custom-reports-demo

To switch to the directory that you created, run the following command:

cd custom-reports-demo

Step 3: Scaffold Your Project

Scaffold your project using the init command in the LeanIX Reporting CLI :

lxr init

The scaffolder uses an interactive terminal prompt to assist you with the initial project setup.

Initializing new project...
? Name of your project for package.json My Custom Report Project
? Unique id for this report in Java package notation (e.g. net.leanix.barcharts) custom.report.demo
? Who is the author of this report (e.g. LeanIX GmbH) LeanIX GmbH
? A title to be shown in LeanIX when report is installed Custom Report Demo
? Description of your project Custom Report Demo
? Which licence do you want to use for this project? UNLICENSED
? Which host do you want to work with? app.leanix.net
? Which is the workspace you want to test your report in? test
? API-Token for Authentication (see: https://dev.leanix.net/docs/authentication#section-generate-api-tokens) {{YOUR_API_TOKEN}}
? Are you behind a proxy? No

Once you've finished answering the scaffolder's questions, it generates a basic project structure with the necessary directories and an initial set of files essential for your project.

├── README.md
├── lxr.json
├── package.json
├── src
│   ├── assets
│   │   ├── bar.css
│   │   └── main.css
│   ├── fact-sheet-mapper.js
│   ├── index.html
│   ├── index.js
│   └── report.js
└── webpack.config.js

The basic project structure includes the following files that provide a foundation for your application:

• lxr.json: The file contains the configuration for the development server and your LeanIX workspace.
• package.json: The file contains information about your project, such as its name, version, dependencies, and scripts. It's used for managing the project's dependencies and automating tasks using npm.
• Base configuration files required for the project.

The following files contain guidance to help you build your first custom report:

• index.js: The file serves as the primary entry point for your custom report project. It's generated with a basic set of code to guide you through the initial stages of development.
• report.js: The file serves as an example showing how to poll data to be used within your custom report from LeanIX. It provides general guidance on developing your own custom report. The specific module is imported within index.js.

To learn how to create your first report, complete this tutorial and see Next Steps.

Congratulations! A basic skeleton for your custom report project is now ready. If you need to modify the project configuration, you can do it by following the instructions in the following step.

Step 4: Configure Your Project

You can change the configuration of your project in the lxr.json and package.json files.

lxr.json

The lxr.json file contains the configuration for the development server and your LeanIX workspace.

{
  "host": "app.leanix.net",
  "workspace": "",
  "apitoken": "{{YOUR_API_TOKEN}}",
  "proxyURL": "",
  "localPort": "8080"
}

If you're working behind a proxy, you can specify the proxy URL using the proxyURL property. By default, the development web server runs on port 8080. If this port is already in use by another application on your system, you can modify the port using the localPort property.

The LeanIX Reporting CLI development server generates a self-signed SSL certificate for development purposes. If you prefer to use your own generated SSL certificate, you can specify it using the ssl property.

{
  "host": "app.leanix.net",
  "workspace": "",
  "apitoken": "{{YOUR_API_TOKEN}}",
  "proxyURL": "",
  "localPort": "8080",
  "ssl" {
    "cert": "/path/to/cert",
    "key": "/path/to/key"
  }
}

package.json

If you have experience with npm, you know that the package.json file is an essential element of any Node.js project. Understanding how to use the file is required to work with Node.js, npm, and modern JavaScript.

This file is also used in the LeanIX Reporting Library for configuring custom report projects.

The scaffolding process also generates specific settings for the LeanIX Reporting Library in the package.json file.

{
  "name": "Custom Reports Demo",
  "author": "LeanIX GmbH",
  "version": "1.0.0",
  "description": "This is a custom reports demo",
  "leanixReport": {
    "id": "custom.reports.demo",
    "title": "Custom Reports Demo",
    "defaultConfig": {}
}

The following table contains configurable fields within the package.json file.

The leanixReport object contains fields listed in the following table.

📘

Note

id adheres to the Java package naming convention, which specifies alphanumeric strings with underscores _ and dots . allowed ([a-z,0-9,_,.]).

The id value must not end with a dot or comma. This ensures consistency and readability within the codebase.

The part of the id parameter following the last dot is the unique identifier that is displayed in the reporting menu. To avoid overriding existing reports, ensure that this identifier is unique.

Step 5: Install Dependencies

The scaffolder automatically generates the package.json file that contains the essential entries and dependencies for your project. Once the package.json file is created, you can proceed with installing the project dependencies using the appropriate npm command.

npm install

This command downloads and installs all dependencies listed in the package.json file.

Step 6: Install Chart.js

To be able to generate charts for your custom reports, install a charting library.

📘

Note

The power of LeanIX custom reports lies in their flexibility. The framework doesn't limit you to a specific charting library – you can select the one you prefer. In our tutorials, we use the Chart.js library. For complete setup instructions, refer to the Chart.js documentation.

To install Chart.js, run the following command:

npm install [email protected]

Step 7: Install Tailwind CSS

To be able to style your custom reports, install a CSS framework.

📘

Note

You can use your preferred CSS library to build custom reports. In this tutorial, we use Tailwind CSS. For complete setup instructions, refer to the official Tailwind CSS documentation.

To install Tailwind CSS, run the following command:

npm install [email protected]

Step 8: Verify Your Project Setup

To ensure that all dependencies have been installed and your configuration is set up correctly, start the development server.

$ npm start

Your workspace is CustomReportDemo
Starting development server and launching with url: https://app.leanix.net/CustomReportDemo/reports/dev?url=https%3A%2F%2Flocalhost%3A8080
--https --port 8080
ℹ ｢wds｣: Generating SSL Certificate

ℹ ｢wds｣: Project is running at https://localhost:8080/

ℹ ｢wds｣: webpack output is served from /
[...]
ℹ ｢wdm｣: Compiled successfully.

Open the following url to test your report:
https://app.leanix.net/CustomReportDemo/reports/dev?url=https%3A%2F%2Flocalhost%3A8080#access_token={{ACCESS_TOKEN}}

In the code sample, we've truncated the output for better readability.

📘

Note

You can also initiate the development server by executing the lxr start command. This action has the same result as running npm start.

Upon initial launch, the development server generates a self-signed SSL certificate for secure communication. However, if you've already configured a custom SSL certificate in the lxr.json file, this step is skipped. Subsequently, the development server binds to the specified local port as defined in the localPort configuration.

When you execute the npm start command, the terminal displays two URLs:

• Localhost URL: This URL points to the localhost address of your machine, for example, https://localhost:8080.
• LeanIX URL: This URL points to the host configured in your lxr.json file. It appears as https://app.leanix.net/CustomReportDemo/reports/dev. In this URL, app.leanix.net and CustomReportDemo point to the host and workspace properties of your lxr.json configuration, respectively.

To validate the operation of your web server, open a web browser and navigate to the LeanIX URL displayed in the terminal window after executing the npm start command. If the web server is functioning correctly, you should be able to access the application. If you encounter any issues accessing the LeanIX URL, verify your installation using the localhost URL.

Troubleshooting: Bypassing Browser Errors for Self-Signed Certificates

While developing custom reports, you might encounter browser errors related to self-signed certificates. To learn how to allow self-signed certificates in some popular browsers, follow the instructions in this section.

📘

Remember

Allowing the use of self-signed certificates in your browser should be strictly limited to the development phases, as it can expose your browser to security risks.

Google Chrome

Follow these steps:

1. Navigate to chrome://flags/#allow-insecure-localhost in the address bar.
2. Set the Allow invalid certificates for resources loaded from localhost option to Enabled.

Mozilla Firefox

Follow these steps:

1. Type about:config in the address bar and press Enter (Windows) or Return (macOS).
2. On the warning page, click Accept the Risk and Continue.
3. In the search bar, type network.stricttransportsecurity.preloadlist and set its value to false.

For more information, refer to the Mozilla Firefox documentation.

Safari

Follow these steps:

1. Click Show Certificate.
2. Select the checkbox to trust [website] when connecting to [website].
3. Click Continue.

For more information, refer to the Safari documentation.

Summary

In this tutorial, you learned how to configure your system using the scaffolder of the LeanIX Reporting CLI, which enables you to create a project skeleton equipped with all the necessary files and dependencies for building custom reports.

Next Steps

Once you've installed all the dependencies and configured your environment, you're now ready to start developing your first custom reports. For more information, see Building Your First Custom Report.