1. Query Key-Value Data
ACal API(en-US)
  • Get Started
    • Quickstart
    • Integration Solutions
  • API Functions
    • Accounts
      • README
      • Login (Auth)
      • Logout
    • DUT
      • Others
        • Query DUT count by condition
        • Query DUT information by condition
        • Get DUT information by ID
        • Batch save DUT info that shares the same template but differs only by ID
      • Batch save or update DUT information
      • Delete DUT
    • Test Records
      • README
      • Query Key-Value Data
        • Key-Value Data Response Message Specification
        • Query Record Dictionary Data by Condition
          POST
        • Get Record Dictionary Data by ID
          POST
        • Query Unsynced Record Dictionary Data
          POST
      • Export Certificate Excel File
        • Export Certificate as Excel by Condition
        • Export Certificate as Excel by ID
        • Export Certificate as Excel by Template
      • Export Certificate PDF File
        • Export Certificate as PDF by Condition
        • Export Certificate as PDF by ID
        • Export Certificate as PDF by Template
      • Query Structured Data
        • Query Record Structured Data by Condition
        • Get Record Structured Data by ID
        • Query Unsynced Record Structured Data
      • Others
        • Data Sync Status
          • Query Unsynced Record Count
          • Update Record Sync Status
        • Query Record Header Structured Data by Condition
        • Query Same Calibration-Task Record Dictionary Data by Condition
        • Delete Record
      • Query Record Count by Condition
        POST
    • Others
      • References
        • Query DUTs that meet the condition
        • Get DUT by ID
        • Query count of DUTs that meet the condition
        • Query device types of standard instruments
        • Save or update DUT information
        • Delete DUT information
      • Templates
        • Get user template list for the specified DUT type
      • Reports
        • Query record report data by condition
        • Export record report CSV by condition
        • Query count of record report data by condition
  • Releases
    • Changelog
  1. Query Key-Value Data

Key-Value Data Response Message Specification

Key-Value Data Response Message Specification (Field Mapping Table)#

Related APIs#

API nameMethod & path
Query Record Dictionary Data by ConditionPOST /ACal/TestRecordService/QueryMessageByCondition
Get Record Dictionary Data by IDPOST /ACal/TestRecordService/QueryMessageByID
Query Unsynced Record Dictionary DataPOST /ACal/TestRecordService/GetUnsyncRecordMessage
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 addressColumn letter + row number
ValueCell contentActual 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:
WorksheetContentsCorresponding message nodeExample
Info worksheetDUT, submitting organization, calibration environment parameters, calibration organization, calibration specifications, standard instruments, calibration conclusion and other basic infoData.BaseInfoThe DUT name is stored in cell B6 of the BaseInfo worksheet
Raw record worksheetConclusions of each calibration item, raw data during calibrationData.CalData1The 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 AColumn B...Column G
Row 4Record No. ← G4
Row 6DUT Name ← B6
Row 28Cal-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#

FieldTypeDescription
IDstringUnique record identifier
RecordNostringRecord No.
CertNostringCertificate No.
FactoryNostringFactory No.
SampleNostringSample No.
OrderNostringOrder No.
ReserveNoOne / ReserveNoTwostringReserved fields, may be null
ContentstringMain 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:
StageFormExample
Internal systemJSON object{"ID":"...","Data":{...}}
Over the wireEscaped string (value of Content)"{\"ID\":\"...\",\"Data\":{..."
After client processingJSON 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:
FieldDescription
DUTClassIDInstrument class ID (100 Pressure / 200 Temperature), used to look up Appendix A
DUTTypeIDDUT type ID, the primary key for looking up the template file
Data.BaseInfoBasic info key-value pairs, corresponding to the template "info worksheet"
Data.CalData1Calibration 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 nodeContentsCorresponding template worksheet (Pressure)
BaseInfoBasic infoBaseInfo
CalData1Calibration item dataCertificate / 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:
StepOperationResult
1Unescape ContentJSON object obtained
2Read DUTTypeID100100
3Look up Appendix A mapping tableTemplate ISO17025-DialPressureGauge.xls; info worksheet BaseInfo; raw record worksheet Certificate
4Locate Data.BaseInfo["B6"]Template BaseInfo!B6 → DUT Name
4Locate 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#

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 classDataTypeID / DUTClassIDDUTTypeID rangeTemplate directory
Pressure Instruments100100100 ~ 100400Templates\Certificate\Calibration\Pressure
Temperature Instruments200200000 ~ 220020Templates\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 classDUT typeDataTypeIDDUTClassIDDUTTypeIDTemplate fileTemplate directoryInfo worksheetRaw record worksheet
Pressure InstrumentsDial Pressure Gauge100100100100ISO17025-DialPressureGauge.xlsTemplates\Certificate\Calibration\PressureBaseInfoCertificate
Electric-Contact Dial Pressure Gauge100100100105ISO17025-DialPressureGauge.xlssame as aboveBaseInfoCertificate(E-Contact)
Precision Pressure Gauge100100100110
Digital Pressure Gauge100100100200ISO17025-DigitalPressureGauge.xlssame as aboveBaseInfoCertificate
Pressure Transmitter100100100300ISO17025-PressureTransmitter.xlssame as aboveBaseInfoCertificate
Pressure Switch100100100400ISO17025-PressureSwitch.xlssame as aboveBaseInfoCertificate
Temperature InstrumentsNoble-Metal Thermocouples200200200000NobleMetalTC.xlsTemplates\Certificate\Calibration\TemperatureInfoCertificate
Base-Metal Thermocouples200200200100CheapMetalTC.xlssame as aboveInfoCertificate
Resistance Thermometers200200200200RTD.xlssame as aboveInfoCertificate
Temperature Transmitter200200220010TemperatureTransmitter.xlssame as aboveInfoCertificate
Temperature Switch200200220020TemperatureSwitch.xlssame as aboveInfoCertificate
Liquid-in-Glass Thermometers200200210000GlassLiquidThermometer.xlssame as aboveInfoCertificate
Bimetallic Thermometers200200210020BimetalThermometer.xlssame as aboveInfoCertificate
Template directory export steps: [Configuration Center] → [User Template Center] → [Export] → [System Templates].
Modified at 2026-09-24 09:44:36
Previous
README
Next
Query Record Dictionary Data by Condition
Built with