Naming + Labelling
Naming and labelling is optional. You can always run a workbook by giving xplo cell references such as Forecast!B7. Add labels when clear, reusable names would make those inputs and outputs easier for people and code to understand.
You do not have to complete a labelling step. Start with cell references, add names later if they become useful, or mix named and unnamed cells in the same run.
What a label changes
A label adds a semantic layer on top of the workbook. It gives a cell a human-readable name, a code-friendly key, optional units, and a direction: Input or Output. Together, the saved labels form the workbook's cell interface.
Forecast!B7Annual customer churn rateannual_customer_churn_rateUse names or cell references
A processed workbook is ready to call without a cell interface. The two forms below select the same cells; naming only adds an alias and presentation metadata on top of the canonical address.
Cell references
Pass sheet-qualified addresses directly. This is the simplest option for a one-off run or an integration tied to the workbook layout.
Forecast!B7Programmatic names
Map important cells to stable, descriptive keys when callers should not need to know the workbook coordinates.
annual_customer_churn_rateIf you want names, open the labeler
Once a workbook has finished processing, open its overview and choose Labels. The labeler is currently a desktop workspace; phone and tablet layouts are not supported.
Use the workbook hints
xplo shades cells according to the role they appear to play. The shading is a suggestion, not a restriction; you make the final choice when you label a cell.
Likely input
An assumption, estimate, control, or other value callers may set or vary.
Likely output
A result you care about: a total, margin, KPI, or other calculated value.
Likely intermediate
A calculation step in the model's wiring. Label it only when it is useful to vary or measure directly.
Select and classify cells
Click a cell, or drag across several cells, and use the floating chip beside the selection. Choose Input for a value you want to set or vary, or Output for a value you want to read or measure. A cell that already has a direction shows an Edit action instead.
- 1Select one cell or a range.
- 2Choose Input or Output.
- 3The name editor opens over the sheet.
Multi-cell selections are walked one cell at a time. The editor caps a selection at 25 cells so an accidental whole-column selection does not create an unmanageable queue.
Complete the name
Start with the full label. xplo generates a short label and programmatic key from it and keeps them linked until you edit either field. Add units when the value has a meaningful scale.
| Field | What it is for | Example |
|---|---|---|
| Full labelRequired | The descriptive name people see throughout xplo. | Annual customer churn rate |
| Short labelRequired · generated | A compact version for chart axes, tables, and tight layouts. | Churn rate |
| UnitsOptional | The scale displayed with values and used to improve distribution suggestions. | % |
| Programmatic keyRequired · generated | The stable name used in JSON, the API, CLI flags, and generated clients. | annual_customer_churn_rate |
Use suggestions. When xplo finds nearby context, it pre-fills the full label and any inferred allowed values or range. Review those constraints before adding the name.
Pick from the sheet. Use the crosshair beside a field, then click a cell containing the text you want. Drag across several cells to join their text.
Save and keep moving
Choose Add Name for a new label or Save Changes when editing one. In a multi-cell queue, saving advances to the next cell while the previous save finishes in the background. When you are done, choose Exit label editor.
Find named cells
Search the Cell interface list by label, key, units, or address. You can also enter B7 or Forecast!B7 in Go to cell.
Name a series quickly
Reuse the previous name as a starting point when a run of cells only differs by a year, month, or scenario, then edit the changing token.
Import prior names
Use Import from prior action to preview exact cell matches from an earlier version. Changed cells are omitted.
Share labels as JSON
Choose Download labels to save confirmed current labels whose programmatic keys still resolve as a portable JSON file. The action owner can use Upload labels to apply that file to another xplo action built from the exact same workbook file.
Keep keys stable
Leave the generated key linked to the full label, or edit it once when integrations already depend on a particular key.
Review, edit, or remove labels
Click any saved name in the Cell interface list to return to its cell. You can change its direction or fields at any time, or choose Clear Cell Label to remove it from the interface. Only the action owner can make changes; everyone else sees the same names in read-only mode.
A Review badge means a name came from an older interface. Saving it confirms the name. Unambiguous names can be accepted together; older labels marked Both must be classified as Input or Output individually.
Choose names that age well
Do
- Name the business meaning, not the spreadsheet position.
- Add scope or time when two values could otherwise be confused.
- Record units such as USD, %, years, or users.
- Keep programmatic keys stable once callers depend on them.
Avoid
- Generic labels such as “Input 1” or “Final result”.
- Putting the cell address into the label.
- Using the same full label or key for two cells.
- Marking every intermediate as an externally useful output.
What happens next
If you add labels, confirmed names appear wherever the workbook is used. Inputs become readable controls and simulation candidates; outputs become readable results, chart labels, and export columns; programmatic keys become address-free names for callers. If you do not add labels—or a particular cell is unnamed—use its raw cell reference instead.