Anatomy of a KPI

A KPI in Pulsaria is a small definition: a name, a number you are aiming at, and the rules Pulsaria uses to decide whether today’s value is good enough. This page walks through every field the form shows, in the order it shows them, and says what happens when you change one afterwards.

Where the form lives

Pulsaria has no central KPI list. KPIs are created from the dashboard and managed from an individual KPI’s detail page.

You can start a new KPI from four places:

1. Dashboard → the + KPI button in a group header. The group decides the pre-selected scope.
2. Dashboard empty state → Create KPI.
3. Projects → the + KPI button on a project card.
4. A project’s detail page → New KPI.

When you create a KPI, the dialog opens on a source picker headed “Where does this KPI’s data come from? You can change this later.” with four cards: Manual, Connector, Bash, HTTP. Pick one and the configuration form opens with two sections — Data source first, then Goal.

When you edit an existing KPI, the picker is skipped. The dialog opens straight on the configuration form, and the source becomes a four-way switch you can flip in place.

Only Name and Target are required. Every other field has a default.

Name

Free text, required, placeholder e.g. Revenue Growth. Leave it empty and you get “Name is required” and the save is blocked.

Renaming later is safe. It changes the label everywhere the KPI is shown from that moment on. Alerts that were already raised and rows already written to the fetch log keep the old name, because both store the name as it was at the time.

Unit

Free text, entirely up to you. New KPIs start with % pre-filled. There is no dropdown, no currency picker and no validation — a KPI with an empty unit saves fine.

The unit is printed verbatim next to the number, and it also decides how many decimals Pulsaria shows:

Unit (exact match)	Decimals shown
%, stars, k, GB/h	up to 1
ms, hours, $/day, /week, /day, count, points	0
EUR, USD, GBP, CHF, €, $	0 from 1000 upwards, otherwise exactly 2
anything else	up to 2

The match is exact and case-sensitive: EUR gets the currency rule, eur and Eur fall through to the last row. Grouping and the decimal separator follow the app language — 50,000 in English, 50.000 in German. Pulsaria never renders a currency symbol of its own and never converts between currencies.

Changing the unit later changes the label and possibly the number of decimals on screen. Stored values are not touched.

Target

Required. It is a plain number field with step="any", and it must hold a finite number greater than 0 — otherwise you get “Target is required” or “Target must be a number greater than 0”. When there is no error, a small Required hint sits under the field.

The Target field does not accept both 1.234,56 and 1,234.56 the way the value fields on the Daily Entry page do. Type the target the way your system’s number input expects it.

The target is the anchor for everything Pulsaria calculates: the ideal line, the traffic-light status, the gap badge, the status timeline and the Ideal column of the history table. Changing it later re-grades your entire recorded history against the new number. Pulsaria keeps no record of the previous target and never rewrites the values you recorded.

Direction

Higher is better (the default) or Lower is better. It decides which side of the ideal line counts as good.

• Higher is better: on track when the value is at or above the ideal.
• Lower is better: on track when the value is at or below the ideal.

The amber “at risk” band is 10 % on the bad side in both cases. Direction also flips the sign convention of the gap badge: for a lower-is-better KPI, a value below the ideal is shown with a +, because it is ahead. The full grading rules are on Ideal line & status.

KPI type: cumulative goal or recurring value

Two selectable cards under KPI type. This is the field that most often decides whether a KPI reads sensibly or not.

Cumulative goal — “Value accumulates toward target (e.g. revenue)”. The ideal line grows in a straight line from 0 on the first day of the period to the target at the end. Pick it when the number starts over at the beginning of each period and adds up over it: revenue this month, new signups this quarter, orders, billable hours, kilometres run.

Recurring value — “Fresh reading each period against a benchmark (e.g. MAU)”. The ideal is flat: it equals the target on every single day of the period. Pick it when the number is a level you want to hold rather than a total you want to reach: monthly active users, conversion rate, churn rate, average order value, support response time, error rate.

A quick test: if you recorded the same number two days running, would that mean “no progress”? Then it is cumulative. Would it mean “still on target”? Then it is recurring.

Pulsaria never adds your entries together. For a cumulative KPI, record the running total for the period so far — not the amount you added today. Several values on the same day do not sum either: the latest one wins.

The default is Cumulative goal, and any KPI created before this field existed is read as cumulative.

Switching the type later re-grades the whole history against the new ideal line — same values, different verdicts. It also changes the wording around the KPI: the card footer says ideal: for a cumulative KPI and target: for a recurring one, the gap badge switches between vs ideal and vs target, and the chart legend between Ideal Trend and Target.

Scope

Company-wide or exactly one project. Internally a KPI stores a project reference, and company-wide simply means “no project”.

The dropdown is pre-selected from wherever you opened the dialog: from a project group, a project card or a project detail page it pre-selects that project, from anywhere else Company-wide.

Scope decides which dashboard group the card appears in and which project’s on-track / at-risk / off-track counters it feeds. Company-wide KPIs belong to no project’s counters. More on that in Projects.

Changing scope moves the card and the counters. Your recorded values are untouched and are not re-scoped in any way — the same series simply appears under a different heading. You do not need the edit dialog for this; see Moving between projects below.

Period

Year (the default), Month, Quarter or Custom range. The period is the window the ideal line spans.

Period	Starts	Ends
Year	1 January of the current year	31 December
Month	the 1st of the current month	the last day of that month
Quarter	the first day of the current quarter	the last day of that quarter
Custom range	your Start date	your End date

Year, Month and Quarter always track the current calendar period, computed from your Mac’s local date, so they roll over by themselves. There is no week or day period, no rolling “last N days” window and no fiscal-year offset — Custom range is the only way to point a KPI at a window of your own choosing.

Choosing Custom range reveals Start date and End date. Both are required (“Pick both a start and an end date”) and the end must be on or after the start. The two fields constrain each other, so you cannot pick an impossible pair. They are native date fields, so their calendar popup comes from the system, not from Pulsaria.

Switching the period away from Custom range clears the stored start and end dates when you save.

The period is printed straight after the unit on the KPI card and in the detail header: /yr, /mo, /qtr. A custom range prints its two dates instead, for example Mar 1 – Jun 30. Details and the day-count math are on Periods & targets.

Data source

Four cards, and the choice is not final — you can switch a KPI to another source at any time.

Source	Where the number comes from	Notes
Manual	You type it in — on the Daily Entry page or via Add value on the KPI’s detail page	Works everywhere, no approval
Connector	A ready-made metric from a built-in service: Google Search Console, Google Analytics 4, Plausible, Polar, Stripe, Awin	Needs a connection with your credentials; no approval step
Bash	A shell command that prints a single number to stdout	Runs on your Mac, needs your explicit approval
HTTP	A GET request whose JSON response holds the number, addressed by a dot/bracket path	Needs your explicit approval

Picking a connector metric pre-fills the KPI for you: unit, direction and KPI type are always overwritten, the name only if you have not typed one, and period and cron only if the metric defines them.

All three automated sources also offer an optional Cron schedule. An automated KPI saved with an empty cron is never picked up by the scheduler — it only updates when you press Run now on the KPI or Refresh on the dashboard. Scheduled fetching runs only while the app is open, and only on macOS.

Changing the source later has consequences worth knowing:

• Switching to Manual clears the command, cron schedule, URL, headers, JSONPath and the approval.
• Switching between Bash and HTTP clears the other one’s fields.
• Editing the command, URL, headers or JSONPath of an already approved KPI drops the approval, and the scheduler skips the KPI until you approve it again. Editing only the name, target, cron or scope keeps the approval.
• A connector KPI with no metric or no connection still saves. It simply never fetches, and the section shows “No metric selected yet…” instead.

Values you have already recorded survive every source change. Read more in Data sources at a glance, Connectors, Shell commands, Custom HTTP sources and Schedules & refresh.

Field reference

Field	Required	What it does	If you change it later
Name	yes	The label on the card, the detail page and in reports	Cosmetic. Existing alerts and fetch-log rows keep the old name
Unit	no	Printed next to every number; also picks the decimal count	Label and decimals change on screen; stored values are not converted
Target	yes	The number the ideal line aims at; must be > 0	Re-grades the whole history — ideal, status, gap, timeline. No target history is kept
Direction	no (default: higher)	Which side of the ideal counts as good	Re-grades the whole history and flips the sign of the gap badge
KPI type	no (default: cumulative)	Ramp from 0 to target, or a flat line at the target	Re-grades the whole history and changes the ideal/target wording
Scope	no (default: company-wide)	Dashboard group and project roll-up counters	Card and counters move; values stay untouched
Period	no (default: year)	The window the ideal line spans	Every ideal, status and gap is recomputed. Leaving Custom range clears the two dates
Start / End date	only for Custom range	The explicit window	Both required, end on or after start
Data source	picked on step 1	Where the number comes from	Clears the fields of the source you left; may drop the approval
Cron schedule	no	When the scheduler fetches an automated KPI	Empty means “only on demand”. Editing it never affects the approval

Recorded values are never rewritten by any of these edits. Only the calculations around them change.

Starting from a template

Instead of typing your first KPIs one at a time, you can apply a starter pack. Three ship with the app:

Pack	KPIs	Contents
SaaS Founder	6	MRR, Churn rate, Trial-to-paid conversion, Active users, New signups, Support response time
Freelancer	5	Monthly revenue, Billable hours, Active projects, Average invoice age, New leads
E-Commerce	6	Revenue, Orders, Conversion rate, Average order value, Cart abandonment, Return rate

Every pack KPI is manual, company-wide and uses the Month period. Direction, unit and KPI type are set per KPI — most are Recurring value, the accumulating ones (revenue, orders, signups, leads, billable hours) are Cumulative goal. The names arrive in your current UI language. The targets are placeholders: the picker says so plainly — “Create a ready-made set of KPIs with sensible defaults. Edit the targets afterwards — no demo data is added.”

There are exactly two entry points, both labelled Use a template: step 3 of the welcome wizard, and a completely empty dashboard. Once you have a single KPI or a single project, the button is gone — App Settings has no template card, and you cannot create, edit or import packs of your own. The picker is headed “Start from a template”; each pack shows its KPI count and a Use pack button.

Applying a pack from inside the welcome wizard closes the wizard and marks the onboarding as done. Anything you typed into the first-KPI form on that step is discarded, and no KPI is created from it.

After the KPI exists

All four actions sit in the header of a KPI’s detail page, which you reach by clicking its card on the dashboard. Each is disabled without a licence or an active trial, with the tooltip “Requires a license or active trial” — see Trial & licence.

Editing

Press Edit. The dialog opens on the configuration form with everything pre-filled and the source switchable. Two other ways in: the deep link /kpi/<id>?edit=1, and a card that failed to load — it renders red with “KPI could not be loaded” and “Click to edit” and jumps straight into the dialog.

There is no “unsaved changes” warning. Cancel, the X, Escape or a click outside the dialog discard the form silently.

Duplicating

Press Duplicate. The copy takes the unit, target, direction, scope, period, KPI type, source and the source’s whole configuration. It is named <name> (Copy); if that name is taken, (Copy 2), then (Copy 3).

Not copied: the history, the fetch-log entries and the approval. A duplicated Bash or HTTP KPI therefore lands unapproved and is skipped by the scheduler until you approve it — the toast tells you so. Pulsaria then navigates you to the copy so you can adjust it.

Moving between projects

Press Move to…. The menu lists Company-wide first, then every project; the current scope carries a checkmark and cannot be picked again. One click, no dialog, and the dashboard refreshes immediately.

Moving is a re-labelling, not a migration: your values stay exactly as they are and are not re-scoped. One KPI at a time — there is no multi-select, no bulk move and no drag and drop, and the menu exists only on the detail page.

Deleting

Press Delete and confirm. The dialog is titled “Delete KPI” and reads “Delete <name> and all its historical data? This cannot be undone.”

That is literal. Deleting a KPI removes its definition and every value ever recorded for it from disk, then returns you to the dashboard. There is no undo, no trash and no archive.

Deleting a project takes its KPIs with it. The confirmation says “Delete <name> and all its KPIs? This cannot be undone.” — and that includes all of their recorded values. There is no way to delete a project while keeping its KPIs.

Where to go next

• Your first KPI — the guided path from install to a first number
• Entering values — how values are recorded, corrected and deleted
• KPI detail — the page all of the above actions live on