Key-Value Data Response Message Specification
Key-Value Data Response Message Specification (Field Mapping Table)#
This document is self-contained: the full field mapping table of instrument types and template files is in Appendix A.
1. Overview#
The Key-Value Data message returns the dictionary data of an inspection record. Its data organization originates from ACal's Excel export mechanism: JSON nodes correspond one-to-one with Excel cells:| JSON (message) | Excel (template / export file) | Description |
|---|
Key (e.g. "B6", "H3") | Cell address | Column letter + row number |
| Value | Cell content | Actual value of the inspection data |
Nodes under Data (BaseInfo, CalData1) | Worksheet (Sheet) | Nodes correspond to worksheets one-to-one |
In short: the API moves Excel cells into JSON as-is — the Key is the cell address, the Value is the cell content.2. Data Source: Excel Export and Hidden Worksheets#
ACal supports exporting inspection records to Excel (certificate/record). In the exported Excel, all inspection data is written to one or more hidden worksheets (Sheets) — the visible layout on the certificate is just a shell; the real data source is these hidden Sheets.To view a hidden Sheet: right-click a worksheet tab at the bottom of Excel → "Unhide(U)", and select the worksheet to display.The two most important hidden worksheets:| Worksheet | Contents | Corresponding message node | Example |
|---|
| Info worksheet | DUT, submitting organization, calibration environment parameters, calibration organization, calibration specifications, standard instruments, calibration conclusion and other basic info | Data.BaseInfo | The DUT name is stored in cell B6 of the BaseInfo worksheet |
| Raw record worksheet | Conclusions of each calibration item, raw data during calibration | Data.CalData1 | The appearance inspection conclusion is stored in cell H3 of the CalData1 worksheet |
2.1 Cell Address Rules#
Each data item in a template occupies a fixed cell. Cell addresses follow the Excel default reference style: column letter + row number (e.g. B6 is column B, row 6). After selecting any cell in Excel, the Name Box on the left of the formula bar shows its address — the most direct way to confirm which cell a Key refers to.Taking the BaseInfo worksheet of the pressure instrument template ISO17025-DialPressureGauge.xls as an example, the layout is illustrated below: | Column A | Column B | ... | Column G |
|---|
| Row 4 | | | | Record No. ← G4 |
| Row 6 | | DUT Name ← B6 | | |
| Row 28 | | | | Cal-Result ← G28 |
The CalData1 worksheet is similar: cell H3 stores the appearance inspection conclusion, and H60 / I60 store the up/down travel indications after tapping.Data.BaseInfo["B6"] in the message points to the same cell as BaseInfo!B6 in the template — locate that address in the template to determine the field's business meaning.3. Message Structure#
From outside in, the message has four layers: response outer → Reports[] → Content (escaped JSON string) → Data (cell key-value pairs):Response message
├── StatusCode
└── Reports[] ← record array, one object per record
├── ID / RecordNo / CertNo ... ← business fields (use directly)
└── Content ← escaped JSON string ★
└── after unescaping
├── ID ← record identifier
├── DUTClassID ← instrument class ID
├── DUTTypeID ← DUT type ID ★ the key to the mapping table
└── Data
├── BaseInfo ← basic info (Key = cell address)
└── CalData1 ← calibration data (Key = cell address)
3.1 Outer Layer: Reports[] Business Fields#
| Field | Type | Description |
|---|
ID | string | Unique record identifier |
RecordNo | string | Record No. |
CertNo | string | Certificate No. |
FactoryNo | string | Factory No. |
SampleNo | string | Sample No. |
OrderNo | string | Order No. |
ReserveNoOne / ReserveNoTwo | string | Reserved fields, may be null |
Content | string | Main inspection data, an escaped JSON string |
3.2 Content: Escaping and Unescaping#
The inspection data is returned as a whole escaped JSON string, with the key Content. The main structure is shown below:{
"StatusCode": 0,
"Reports": [
{
"ID": "0EC295E5BC324A978B079FB534BA6745",
"RecordNo": "D26090094",
"CertNo": "R26090094",
"FactoryNo": "WK-2208-3125",
"SampleNo": "SMP-0100",
"OrderNo": "CN-0100",
"ReserveNoOne": null,
"ReserveNoTwo": null,
"Content": "{\"ID\":\"0EC295E5BC324A978B079FB534BA6745\",\"DUTClassID\":100,\"DUTTypeID\":100100,\"DataTypeID\":100,\"Data\":{\"BaseInfo\":{\"B4\":..."
}
]
}
The form of Content across the three stages:| Stage | Form | Example |
|---|
| Internal system | JSON object | {"ID":"...","Data":{...}} |
| Over the wire | Escaped string (value of Content) | "{\"ID\":\"...\",\"Data\":{..." |
| After client processing | JSON object (unescaped / second parse) | same as internal system |
Processing: after parsing the outer JSON, deserialize the value of Content once more. Taking JavaScript as an example:3.3 Inner Layer: Content After Unescaping#
The structure after unescaping is as follows (values are illustrative; actual values are the cell contents):{
"ID": "0EC295E5BC324A978B079FB534BA6745",
"DUTClassID": 100,
"DUTTypeID": 100100,
"Data": {
/* Basic info */
"BaseInfo": {
"B6": "DUT Name",
"B8": "Model",
"B10": "S/N",
"G4": "Record No.",
"G6": "Cert No.",
"G28": "Cal-Result"
},
/* Calibration data */
"CalData1": {
"H3": "Cal Result",
"C25": "SetPoint",
"H60": "Indication After Tapping ASC.",
"I60": "Indication After Tapping DESC."
}
}
}
Top-level field descriptions:| Field | Description |
|---|
DUTClassID | Instrument class ID (100 Pressure / 200 Temperature), used to look up Appendix A |
DUTTypeID | DUT type ID, the primary key for looking up the template file |
Data.BaseInfo | Basic info key-value pairs, corresponding to the template "info worksheet" |
Data.CalData1 | Calibration data key-value pairs, corresponding to the template "raw record worksheet" |
3.4 Correspondence Between Data Nodes and Template Worksheets#
Nodes under Data whose Keys are cell addresses correspond to worksheets in the template. Taking pressure instruments as an example:Data node | Contents | Corresponding template worksheet (Pressure) |
|---|
BaseInfo | Basic info | BaseInfo |
CalData1 | Calibration item data | Certificate / Certificate(E-Contact) (varies by DUT type) |
Worksheet names differ across instrument classes (e.g. the info worksheet for temperature instruments is Info). See Appendix A for the full mapping.4. Lookup Rules (Four Steps)#
After receiving a Key-Value message, follow the four steps below to determine the meaning of each JSON node.Step 1: Unescape Content#
After parsing the outer message, unescape the Content string and parse it into a JSON object (see 3.2).Step 2: Parse Content and Enter the Data Node#
Read DUTClassID / DUTTypeID, and locate the BaseInfo and CalData1 nodes under Data (see 3.3).Step 3: Treat the Key as a Cell Address#
Each Key under Data.BaseInfo / Data.CalData1 (e.g. B6, H3) is an Excel cell address. Locate it in Excel by worksheet name + cell address:Data.BaseInfo["B6"] → open the BaseInfo worksheet of the corresponding template Excel, check cell B6 → DUT Name;
Data.CalData1["H3"] → open the CalData1 worksheet, check cell H3 → appearance inspection conclusion.
Step 4: Look Up the Mapping Table by DUTTypeID to Determine the Template File#
Different DUT types use different certificate template Excels, and cell layouts vary by template. First use DUTTypeID from the message to look up the template file and worksheet names in Appendix A, then use the cell address from Step 3 to find the meaning in that template.4.1 End-to-End Example#
Taking DUTTypeID = 100100 (Dial Pressure Gauge) as an example:| Step | Operation | Result |
|---|
| 1 | Unescape Content | JSON object obtained |
| 2 | Read DUTTypeID | 100100 |
| 3 | Look up Appendix A mapping table | Template ISO17025-DialPressureGauge.xls; info worksheet BaseInfo; raw record worksheet Certificate |
| 4 | Locate Data.BaseInfo["B6"] | Template BaseInfo!B6 → DUT Name |
| 4 | Locate Data.CalData1["H3"] | Template Certificate!H3 → appearance inspection conclusion |
4.2 Processing Sequence#
Template file retrieval path: [Configuration Center] → [User Template Center] → [Export] → [System Templates]. Template directories are listed in the mapping table (e.g. Templates\Certificate\Calibration\Pressure).
5. Instrument Type Numbering System#
DataTypeID / DUTClassID: instrument class ID (100 Pressure / 200 Temperature);
DUTTypeID: DUT type ID, corresponding to the DUTClassID prefix (Pressure 100xxx, Temperature 2xxxxx), one-to-one with the template file; the full mapping is in Appendix A.| Instrument class | DataTypeID / DUTClassID | DUTTypeID range | Template directory |
|---|
| Pressure Instruments | 100 | 100100 ~ 100400 | Templates\Certificate\Calibration\Pressure |
| Temperature Instruments | 200 | 200000 ~ 220020 | Templates\Certificate\Calibration\Temperature |
6. Notes#
Q1: Why is the inspection data a string instead of a JSON object?The value of Content is an escaped JSON string. After parsing the outer message, the client must deserialize Content once more (see 3.2).Q2: Can I use the JSON node name directly as the worksheet name?No. Nodes under Data correspond to worksheets in the template, but worksheet names vary by instrument class and DUT type (e.g. the info worksheet for temperature instruments is Info, and the raw record worksheet for pressure instruments is Certificate / Certificate(E-Contact)). The mapping between nodes and template worksheet names is governed by Appendix A; do not use node names directly as worksheet names when locating cells.Q3: For different DUT types, does the same Key have the same meaning?Not necessarily. Cell layouts vary by template file; a different DUTTypeID may imply a different template. Always look up the template file via DUTTypeID first, then locate the meaning by cell address in that template.Q4: Where do I get the template files?[Configuration Center] → [User Template Center] → [Export] → [System Templates]. Template directories are listed in Appendix A (e.g. Templates\Certificate\Calibration\Pressure).7. Lookup Rules Summary#
In short: Key = cell address, worksheet = the node name under Data, and the template file is determined by looking up DUTTypeID in the mapping table.Appendix A: Full Correspondence Between Instrument Type and Field Mapping Template#
Lookup rules: see Section 4; numbering system: see Section 5.| Instrument class | DUT type | DataTypeID | DUTClassID | DUTTypeID | Template file | Template directory | Info worksheet | Raw record worksheet |
|---|
| Pressure Instruments | Dial Pressure Gauge | 100 | 100 | 100100 | ISO17025-DialPressureGauge.xls | Templates\Certificate\Calibration\Pressure | BaseInfo | Certificate |
| Electric-Contact Dial Pressure Gauge | 100 | 100 | 100105 | ISO17025-DialPressureGauge.xls | same as above | BaseInfo | Certificate(E-Contact) |
| Precision Pressure Gauge | 100 | 100 | 100110 | | | | |
| Digital Pressure Gauge | 100 | 100 | 100200 | ISO17025-DigitalPressureGauge.xls | same as above | BaseInfo | Certificate |
| Pressure Transmitter | 100 | 100 | 100300 | ISO17025-PressureTransmitter.xls | same as above | BaseInfo | Certificate |
| Pressure Switch | 100 | 100 | 100400 | ISO17025-PressureSwitch.xls | same as above | BaseInfo | Certificate |
| Temperature Instruments | Noble-Metal Thermocouples | 200 | 200 | 200000 | NobleMetalTC.xls | Templates\Certificate\Calibration\Temperature | Info | Certificate |
| Base-Metal Thermocouples | 200 | 200 | 200100 | CheapMetalTC.xls | same as above | Info | Certificate |
| Resistance Thermometers | 200 | 200 | 200200 | RTD.xls | same as above | Info | Certificate |
| Temperature Transmitter | 200 | 200 | 220010 | TemperatureTransmitter.xls | same as above | Info | Certificate |
| Temperature Switch | 200 | 200 | 220020 | TemperatureSwitch.xls | same as above | Info | Certificate |
| Liquid-in-Glass Thermometers | 200 | 200 | 210000 | GlassLiquidThermometer.xls | same as above | Info | Certificate |
| Bimetallic Thermometers | 200 | 200 | 210020 | BimetalThermometer.xls | same as above | Info | Certificate |
Template directory export steps: [Configuration Center] → [User Template Center] → [Export] → [System Templates].
Modified at 2026-09-24 09:44:36