Excel Naming Conventions¶

XLSX API uses Excel named ranges to map data between the API and your spreadsheet. This guide explains how to structure your Excel files so the platform can discover inputs, outputs, and process calculations correctly.

Named Range Prefixes¶

The platform recognizes three categories of named ranges based on their prefix:

Prefix	Category	Purpose
`Xinput_`	Input	Cells where API input values are written
`Xoutput_`	Output	Cells where calculated results are read from
(no prefix)	Other	Lookup tables, constants, or internal ranges (ignored by the API)

How It Works¶

1. API receives:     {"customerAge": 35, "propertyValue": 500000}
2. Writes to:        Xinput_customerAge = 35
                     Xinput_propertyValue = 500000
3. Excel recalculates
4. Reads from:       Xoutput_premium → 1250.50
                     Xoutput_deductible → 1000
5. API returns:      {"premium": 1250.50, "deductible": 1000}

The prefix is stripped in the API. Consumers send customerAge, not Xinput_customerAge.

Creating Named Ranges¶

Step 1: Define Input Cells¶

For each input your engine needs:

Select the cell that should receive the input value
In the Name Box (left of the formula bar), type Xinput_fieldName
Press Enter

For example, if cell B2 should receive the customer's age:

Select B2
Type Xinput_customerAge in the Name Box
Press Enter

Step 2: Define Output Cells¶

For each output your engine produces:

Select the cell that contains the calculated result
Name it Xoutput_fieldName

For example, if cell D10 contains the premium calculation:

Select D10
Type Xoutput_premium in the Name Box
Press Enter

Step 3: Verify¶

Go to Formulas > Name Manager to see all defined names. You should see your Xinput_ and Xoutput_ ranges listed.

Naming Rules¶

Rule	Example
Prefixes are case-sensitive	`Xinput_` and `Xoutput_` (capital X)
Field names should be camelCase	`Xinput_customerAge`, `Xoutput_monthlyPremium`
No spaces in names	`Xinput_property_value` or `Xinput_propertyValue`
Single cell per range	Each named range should point to exactly one cell
Names must be unique	No duplicate named ranges in the workbook

Example Layout¶

A typical insurance calculator Excel file:

     A                    B              C              D
1    ── Inputs ──                        ── Outputs ──
2    Customer Age:        [35]           Premium:       [=formula...]
3    Property Value:      [500000]       Deductible:    [=formula...]
4    Zip Code:            [12345]        Coverage:      [=formula...]
5
6    ── Lookup Tables ──
7    Zone   Rate
8    10000  0.0025
9    20000  0.0020

Named ranges:

Name	Cell	Category
`Xinput_customerAge`	B2	Input
`Xinput_propertyValue`	B3	Input
`Xinput_zipCode`	B4	Input
`Xoutput_premium`	D2	Output
`Xoutput_deductible`	D3	Output
`Xoutput_coverage`	D4	Output
`RateTable`	A8:B9	Other (ignored by API)

What Gets Uploaded¶

When you create a new engine version:

The Excel file is uploaded to SharePoint
The platform reads all named ranges via Microsoft Graph API
Ranges are automatically categorized by prefix
Input and output field names are extracted (prefix stripped)
You can then define JSON Schemas to validate the inputs and describe the outputs

JSON Schema Mapping¶

After upload, your tenant admin can define a JSON Schema for validation. The schema properties should match the field names (without prefix):

{
  "type": "object",
  "properties": {
    "customerAge": { "type": "integer", "minimum": 18, "maximum": 100 },
    "propertyValue": { "type": "number", "minimum": 0 },
    "zipCode": { "type": "string", "pattern": "^[0-9]{5}$" }
  },
  "required": ["customerAge", "propertyValue"]
}

Tip

You don't have to define a schema — it's optional. Without one, the engine accepts any JSON object as input. But schemas give consumers clear expectations and catch errors before the Excel file is processed.

Common Mistakes¶

Wrong prefix case

xinput_age — the X must be uppercase: Xinput_age

Spaces in names

Xinput_customer age — use camelCase or underscores: Xinput_customerAge

Range points to multiple cells

Xinput_data → A1:A10 — each named range should be a single cell

Missing prefix

premium — output ranges must start with Xoutput_: Xoutput_premium

Excel Error Handling¶

If a formula returns an Excel error (#DIV/0!, #REF!, #VALUE!, #N/A, #NAME?, #NUM!, #NULL!), the job will fail. The error is logged with the specific range that caused it.

Consumers see a generic error message. Tenant admins see the detailed error in the engine's job history dashboard.