Add custom Widgets

Custom widgets allow you to build tailored data visualizations directly on your instellix dashboard. Instead of using pre-built widgets, you define exactly which data you want to see, how it should be grouped, and over which time period — all without writing a single line of code.

This guide walks you through every field in the "Add widget" dialog, step by step. By the end, you will be able to answer questions like:

📘

Example Question (Base for configuration a Widget)

"How high is the sum of my invoices in Business Segment 1 this month compared to last month?"

"How many settlements were booked per merchant payment account last week?"

"How many contracts were created per month this year?"

Opening the "Add Widget" Dialog

Navigate to your dashboard and click Add Widget. A dialog will open with several configuration sections. All fields marked with an asterisk (*) are required before you can save.

Steps to customize a Widget

1. Set Basic Settings
2. Filter Criteria (Documents only)
3. Set Time Span
4. Save the Widget

See examples below.

Detailed Description of the Steps

Step 1 – Basic Settings

The top row of the dialog contains the fundamental settings that define what your widget is and how it looks.

Available Attributes by Entity

Note: Numerical attributes (Net Total, Gross Total, Base Amount, etc.) can be aggregated as a sum. The ID field counts the number of matching records.

Grouping Options by Entity

The options available in the Grouping field depend on the entity you selected.

Step 2 – Filter Criteria (Documents only)

When the selected entity is Documents, an additional Filter criteria section appears below the basic settings. Use these filters to narrow down which records are included in your widget. All filter fields are optional — leave them empty to include all records.

Combining multiple filters applies all of them at once (AND logic). For example, setting Document type = Invoice and Business Segment = Segment 1 shows only invoices from Business Segment 1.

Step 3 – Time Span

The Time span section defines the date range for your widget data.

Available Time Span Attributes by Entity

Step 4 – Saving Your Widget

Once all required fields are filled in, the Save button in the bottom-right corner becomes active. Click it to add the widget to your dashboard.

If any required field is missing, the form shows a red "Is a required field" message below the affected field, and an error count badge appears in the bottom-right corner (e.g. "2 errors"). Fix all highlighted fields before saving.

To discard your changes without saving, click Discard or the ✕ icon in the top-right corner of the dialog.

Worked Example: Invoices by Business Segment – This Month vs. Last Month

Question: What is the net total of my invoices per business segment this month, and how does it compare to last month?

Configuration

Why each setting was chosen

Entity → Documents. Invoices are a type of document in instellix, so the Documents entity contains the relevant data.

Attribute → Net Total. The goal is to sum the net invoice amount. Net Total is a numerical field and can therefore be aggregated as a sum. Non-numerical fields like ID can only be counted.

Grouping → Business Segment. Each bar in the chart represents one business segment, making it easy to compare revenue across segments at a glance.

Document type filter → Invoice. Without this filter, the widget would also include credit notes and deposit invoices. Selecting Invoice ensures only invoice documents are included.

Time span Attribute → Document date (UTC). This is the date on the invoice document itself. Using Document date (UTC) means the period filter is applied to when the invoice was issued, not when it was created in the system.

Period → Current month. Shows data for the month you are currently in.

Reference Period → Previous month. Adds a second bar per group showing the same metric for last month. The result is a side-by-side bar chart where the current month appears in teal and the previous month in grey.

Tips and Common Scenarios

Counting records instead of summing values

If you want to count how many documents, contracts, or customers exist (rather than summing a monetary value), select ID as the Attribute. Since ID is not a numerical field, the widget will automatically count the number of matching records.

Comparing two time periods

Use the Reference Period field to add a comparison bar. The chart will show both the current period (teal bars) and the reference period (grey bars) side by side for each group. You can compare any two time windows, such as current week vs. previous week, or current month vs. same month last year.

Choosing the right date field for Documents

For Documents, three date fields are available as the Time span Attribute:

• Document date (UTC) – the date printed on the document (e.g. the invoice date)
• Due date – the payment due date
• Creation Date – the date the record was created in the system

Choose the field that matches the question you are trying to answer. To analyze when invoices were issued, use Document date (UTC). To analyze when records entered the system, use Creation Date.

Filtering to a subset of documents

Use the Filter criteria section to restrict your widget to specific document types, business segments, statuses, currencies, or countries. All active filters are applied together — only records matching all selected criteria are included.

Learn more about how to add pre-configured Widgets.