01 Introduction

Introduction to the ENLYZE API data source for Grafana.

What You'll Learn

• Understand when and why to use the ENLYZE API data source

• Make your first API request to the ENLYZE platform API

• Parse JSON responses using JSONPath

• Display API data in Grafana panels

Prerequisites

• Completed Part 1-3 tutorials (basic Grafana knowledge)

• Access to Grafana with both ENLYZE data sources configured

---

Overview

So far, you've used the ENLYZE data source to build dashboards. It's simple and effective for most use cases. But for advanced scenarios, you need the ENLYZE API data source (powered by the Infinity plugin).

ENLYZE Data Source vs. ENLYZE API Data Source

Feature	ENLYZE	ENLYZE API
Ease of use	Point-and-click	Query configuration
Time series data	Excellent	Possible (more setup)
API queries	Not supported	Full control
Variables/dropdowns	Limited	Full support
Alerting	Not supported	Required for alerts
Custom transformations	Basic	Advanced (JSONPath/JSONata)
Learning curve	Low	Medium

When to Use the ENLYZE API Data Source

Use the ENLYZE API data source when you need:

1. Dashboard variables – Dynamic dropdowns for site, machine, product selection

2. Alerting – Grafana alerts only work with the ENLYZE API data source

3. OEE/Productivity metrics – The productivity-metrics API endpoint

4. Production runs and downtimes – Historical production data

5. Custom data combinations – Joining data from multiple endpoints

---

Understanding the ENLYZE Platform API

The ENLYZE API data source connects directly to the ENLYZE platform API. Let's understand how it works.

Base URL

All API requests go to:

https://app.enlyze.com/api/v2/

This is pre-configured in your Grafana instance.

Authentication

Your Grafana instance has API authentication pre-configured. You don't need to add any tokens or credentials – it's already set up.

Response Format

All ENLYZE API endpoints return paginated JSON responses:

{
  "data": [
    { "uuid": "...", "name": "Machine 1", ... },
    { "uuid": "...", "name": "Machine 2", ... }
  ],
  "next_cursor": null
}

Key points:

• data – Array containing the actual results

• next_cursor – Pagination token (null if no more pages)

---

Your First ENLYZE API Query

Let's create a panel that lists all machines using the API.

Step 1: Create a New Panel

1. Create a new dashboard or open an existing one

2. Click Add → Visualization

3. Select Table as the visualization type

Step 2: Select the ENLYZE API Data Source

1. In the query editor, click the data source dropdown

2. Select ENLYZE API (not ENLYZE)

   [SCREENSHOT: Data source dropdown showing ENLYZE API selection]

Step 3: Configure the Query

Configure these settings:

Setting	Value
Type	JSON
Parser	Backend
Source	URL
Format	Table
Method	GET
URL	machines

[SCREENSHOT: ENLYZE API query configuration for machines endpoint]

Note: You only need to enter machines, not the full URL. The base URL is already configured.

Step 4: Add Root Selector

The API returns data wrapped in a data array. To extract it:

1. Find the Root selector field

2. Enter: $.data

This JSONPath expression tells Grafana to use the data array as the source.

[SCREENSHOT: Root selector configuration]

Step 5: View Results

Click Refresh or wait for the panel to update. You should see a table with:

uuid	name	site	genesis_date
141e...	Kiefel	a5ea...	2020-08-26
cc0d...	Macchi	a5ea...	2021-03-15
...	...	...	...

[SCREENSHOT: Table showing machines list]

---

JSONPath Basics

JSONPath is how you navigate JSON data. Here are the essentials:

Common Selectors

JSONPath	Description	Example Result
$	Root element	Entire response
$.data	Property named "data"	The data array
$.data[0]	First item in array	First machine
$.data[*].name	All name values	["Kiefel", "Macchi", ...]

Why $.data?

The ENLYZE API wraps results in a data array for pagination. Without the root selector, Grafana would try to display the entire response including next_cursor.

Without root selector:

{
  "data": [...],
  "next_cursor": null
}

With $.data root selector:

[
  { "uuid": "...", "name": "Kiefel", ... },
  { "uuid": "...", "name": "Macchi", ... }
]

---

Querying Sites

Let's add another panel to list all sites.

Query Configuration

Setting	Value
Type	JSON
Parser	Backend
Source	URL
Format	Table
Method	GET
URL	sites
Root selector	$.data

Expected Result

uuid	name
a5ea...	Koln
241a...	Stuttgart

---

Querying Variables for a Machine

You can filter API results using query parameters.

Get Variables for a Specific Machine

Setting	Value
URL	variables?machine=141e0927-62b3-4e76-8398-ad82d20f397f
Root selector	$.data

This returns only variables (sensors, metrics) for the Kiefel machine.

Expected Result

uuid	machine	display_name	data_type	unit
50b8...	141e...	Extruder A Durchsatz	FLOAT	kg/h
1cfd...	141e...	Extruder B Durchsatz	FLOAT	kg/h
...	...	...	...	...

---

Organizing Your Query Results

Selecting Columns

By default, Infinity shows all fields. To select specific columns:

1. Scroll down to the Columns section

2. Click Add column

3. Enter the field selector (e.g., name) and a display title

Selector	Title
name	Machine Name
uuid	ID

[SCREENSHOT: Column configuration]

Using Transformations

You can also use Grafana's transformations (like you learned in Part 3):

1. Go to the Transform tab

2. Add Organize fields by name

3. Rename or hide columns as needed

---

POST Requests

Some API endpoints require POST requests with a request body. We'll cover this in detail in the next tutorial, but here's a preview:

Example: Productivity Metrics

Setting	Value
Method	POST
URL	machines/141e0927-62b3-4e76-8398-ad82d20f397f/productivity-metrics
Body	(see below)

Request Body:

{
  "datetime_ranges": [
    {
      "start": "2024-01-01T00:00:00.000Z",
      "end": "2024-01-01T23:59:59.999Z"
    }
  ]
}

We'll explore POST requests and dynamic time ranges in Tutorial 4.2.

---

Practical Exercise

Build a dashboard with three panels:

1. Machines Table – List all machines with name and site UUID

2. Sites Table – List all sites with name

3. Variables Table – List variables for the Kiefel machine

Use what you've learned:

• ENLYZE API data source

• JSON type, Backend parser

• Root selector $.data

• Table visualization

---

Common Mistakes

"No data" or Empty Results

Problem: Panel shows "No data"

Solutions:

1. Check the URL is correct (just machines, not full URL)

2. Verify root selector is $.data

3. Make sure Parser is set to "Backend"

Seeing Raw JSON Instead of Table

Problem: Panel shows raw JSON text

Solutions:

1. Set Format to "Table" (not "Data frame")

2. Add root selector $.data

3. Verify Type is "JSON"

Authentication Errors

Problem: 401 or 403 errors

Solution: Contact your ENLYZE administrator – the API token may need to be refreshed.

---

Tips and Best Practices

Use Backend Parser

Always set Parser to Backend for ENLYZE API queries. This processes data on the Grafana server, which is more reliable and secure.

Start Simple

When building complex queries:

1. First, get the basic query working with $.data

2. Then add column selections

3. Finally, add transformations

Test URLs in Browser

You can test API URLs directly (if you have an API token):

https://app.enlyze.com/api/v2/machines

This helps debug issues before configuring Grafana.

---

Summary

You've learned the fundamentals of the ENLYZE API data source:

• When to use the ENLYZE API data source vs. the ENLYZE data source

• Making GET requests to API endpoints

• Using JSONPath root selectors ($.data)

• Displaying API results in tables

---

What's Next?

Continue with:

• Querying the ENLYZE API – POST requests, productivity metrics, advanced queries

---

Quick Reference

ENLYZE API Query Settings

Setting	Typical Value
Type	JSON
Parser	Backend
Source	URL
Format	Table
Method	GET (or POST)
Root selector	$.data

Common Endpoints

Endpoint	Method	Description
machines	GET	List all machines
sites	GET	List all sites
variables	GET	List all variables
variables?machine={uuid}	GET	Variables for one machine
machines/{uuid}/productivity-metrics	POST	OEE metrics
production-runs	GET	Production runs
downtimes	GET	Downtime records

JSONPath Cheat Sheet

Expression	Description
$	Root element
$.data	Property "data"
$.data[0]	First array element
$.data[*].name	All "name" values
$.data[?(@.site=="abc")]	Filter by condition