Custom KPIs

What it is and what it's for

A Custom KPI is an indicator card you define yourself with a SQL query. That query must return a single row with a column named Value: that's the number shown on the card. Optionally, the same query can also return the Min, Max, HighSectorValue and LowSectorValue columns so the indicator's range and colors are calculated dynamically instead of using the fixed values you entered on the form.

It's useful for bringing any business number you want to keep a constant eye on to the Dashboard, when it doesn't already exist as a native AdmCloud report or chart: for example, "customers more than 30 days past due", "gross margin this month" or "items with negative stock".

To help you build the query without being a SQL expert, the creation screen includes three AI-powered tools and a data dictionary:

• Generate SQL with AtIna (beta): describe in plain language what you need (for example, "total sales this month grouped by customer") and an AI agent writes and validates the SQL for you; you can watch the progress in real time and accept or discard the result before saving.
• Explain SQL: if you already have a query (your own or inherited) that you don't fully understand, this button gives you a plain-language explanation of what it does.
• Speed improvement suggestions: analyzes your query and proposes changes to make it run faster.
• Data Dictionary: lists every table available in your company with its technical name and description; from there you can browse each table's fields and preview its data, without leaving the creation screen.

Screens in this area

How to create a KPI, step by step

1. Open the KPI list and click New. You can choose Create blank KPI or start from one of the ready-made samples shown in the same menu (for example, monthly revenue or profit margin); picking a sample preloads its SQL so you can adjust it.
2. Fill in the title and subtitle you'll see on the Dashboard card, and choose the module the indicator belongs to.
3. Define the SQL query in the corresponding tab. It must return a single row with the Value column. Use the Data Dictionary to find the tables and fields you need, or use Generate SQL with AtIna to have the AI write it for you from a plain-language description. Use the Preview button to check that the query runs and returns the expected result.
4. Set up the indicator's range and colors with the Minimum, Maximum, Lower Limit and Upper Limit fields (values below the lower limit show in red and values above the upper limit show in green), or let your own SQL query calculate these columns. If a low value is the desired goal for this KPI, check Reverse Goals to flip that color logic.
5. Check Available in Dashboard if you want the card to show up on your Dashboard, and decide whether the KPI will be Public (visible to the whole company) or restricted to specific user groups.
6. If only you should be able to edit its structure, check the option that restricts editing to the owner.
7. If the KPI isn't public, go to the Permissions tab and add the user groups that will be able to see it.
8. Save. The system validates the data and the KPI becomes available in the list and, if you checked it, on your Dashboard.

Key fields

Validations on save

• Name required and unique: it can't repeat the name of another KPI or custom report in your company.
• SQL required and free of forbidden commands (such as instructions that modify or delete data); only read queries are allowed.
• Owner required and must be an active, non-void user.
• Module required.
• Minimum can't be greater than Maximum.
• A public KPI can't have user groups assigned: if you mark it public, first remove the groups from the Permissions tab.
• If the KPI is protected (owner-only), only the owner can save changes to it; another user will get an error trying to edit or delete it.

Managing the KPI

From an already saved KPI's detail screen, depending on your permissions, you can:

• Edit it, to adjust its SQL, its range, its colors or its permissions.
• Duplicate it to create a variant based on its current setup.
• Delete it, as long as it isn't being used as a data source by one of your company's Plugins; if it is, you must unlink it from the Plugin first.
• Review its change log, showing who created, edited or deleted it and when.

Availability and permissions

• Access is controlled by the "Customization" permission on the user group, with separate levels for view, add and edit.
• Available on the Enterprise plan. If your company doesn't have the Enterprise plan but needs this feature, you can ask AdmCloud support to enable it specifically for your account.
• A KPI marked Only the owner can edit can only be modified or deleted by whoever created it, even though other users with permission can still view it if it's public or belongs to their group.

Tips and common mistakes