What does publishing do?
A KPI collection only holds definitions. Insights make them usable: They connect the collection to the source connection that delivers the data. Then they offer the metrics to widgets, to Resi and to AI assistants. Every custom collection needs Insights before anyone sees a number.
You find your Insights under Data sources → KPI declaration → Insights. Insights that came with an integration have the badge Managed, the ones you published have the badge Custom. See Insights for the page itself.
When do I need this?
You built a KPI collection in KPI Studio and want its metrics in dashboards and widgets.
You want Resi or an AI assistant to read metrics on your own data.
You want the same collection on two connections, for example two shops. You create Insights once per connection.
Before you start
The metrics of the collection are published in KPI Studio. A metric that is still a draft cannot be used. See Build a custom KPI in KPI Studio.
You need the role User or higher.
How do I create Insights from a KPI collection?
Open
Data sources→KPI declaration→Insights.Click Create Insights at the top right. The page Create Insights opens.
Under Name, enter a name, for example Commerce core. The Insights have this name everywhere in the space.
Under Metrics, pick the KPI collection. It decides which metrics and dimensions the Insights offer. If you have no collection yet, the page shows Go to KPI collections.
Under Source, pick the Source connection whose data feeds the metrics. Leave it empty when the metrics do not read from a connection, for example when they use an imported table.
Under Advanced, click Add argument only if a metric definition asks for one. An argument is a variable with a Key and a Value that the definition refers to by name. Use arguments for values that should not be visible in the definition, or to keep the data of each connection apart.
Click Create Insights.
The Insights open on the tab Insights and appear in the list with the badge Custom.
How do I check that the Insights work?
On the tab Insights, click a metric on the left. The panel shows its figures for the period (Sum, Mean, Median, Min, Max, Count, First and Last) and a chart.
Change Time range, Group by time, Group by and Search in time by to see how the metric behaves. Under Filters, click Add condition to narrow the data down. Nothing you change here is saved.
If the figures load, the Insights are ready for widgets and AI. See Insights for the tab Sharing.
How do I change the connection or add an image later?
Open the Insights and click the tab Overview. It holds Name and image, the KPI collection, the Source connection and the arguments under Advanced.
Change what you need. To add an image, click Upload image and pick a PNG, JPEG, GIF or WebP file of up to 2 MB.
Click Save. To drop your changes, click Discard.
Troubleshooting
Why doesn't a metric load?
The panel shows Could not load this metric. In most cases no source connection is set. Open the tab Overview, pick the connection under Source connection and click Save.
The definition fails. Open the collection in
Data sources→KPI declaration→KPI Studio, click Edit in studio on the metric, click Dry run and fix the error. See Build a custom KPI in KPI Studio.
Why is my KPI collection not in the list?
- Only collections of your space and collections shared with your space appear. Check in
KPI Studiothat the collection exists.
Why don't the Insights show any metrics?
- The collection has no metrics yet, or they are still drafts. Open the collection in
KPI Studio, add a metric and publish it.
Why does Create Insights not do anything?
- An argument row without Key or Value stops the page from creating the Insights. Fill in both, or remove the row with Remove argument.
Why can't I click Create Insights?
- Creating Insights needs the role User or higher. The role Reader cannot create them.
How can another space use these metrics?
Share the Insights with that space, see Share Insights.
Or share the collection itself on its tab Sharing, so the other space can publish its own Insights on its own connection. See Build a custom KPI in KPI Studio.