XNAT 1.8 introduces the /xapi/dicom_mappings set of endpoints, which offers a way to add support for the extraction of custom DICOM fields to your session or scan attributes in XNAT without having to customize the dicom-xnat-mx session builder code. Support for these custom fields can be added on a site-wide or per-project basis.

Usage of these API endpoints is restricted to XNAT admin users. See Custom DICOM Mapping API

Defining a DICOM Mapping

A custom DICOM mapping is written as a JSON object with these attributes:


XNAT automatically assigns an integer ID to each newly created DICOM mapping. This can be specified in your JSON object if you want to edit an existing mapping.

Determines whether this DICOM mapping should apply to all projects in this XNAT, or be limited to individual projects. Possible values:

  • "site"
  • "project"

If scope has been set to "project", this field asks for a specific project ID.

To enable a DICOM mapping rule on multiple projects, you need to define multiple instances of the mapping rule with one project ID specified in each

Define the custom variable or scan parameter field name. Always use lower-case characters, without spaces

Define the SQL field type. This should be one of five values: 

  • string
  • integer
  • float
  • boolean
  • date
Define the DICOM tag to extract from, using hexadecimal encoding – i.e. "0x00100020" equates to (0010,0020)

Define the XNAT xsiType to apply to, aka "xnat:mrSessionData"

XNAT XSD inheritance is not respected here. In other words, applying a custom mapping to "xnat:imageSessionData" will not cascade down to all datatypes that extend that xsiType.

Adding Custom Attributes to an Image Session Datatype

Extracting values from DICOM fields and including them at the image session level is a two step process:

  1. Define a site-wide or project-specific custom variable for the attribute that you want to include (i.e. "weight")
  2. PUT a JSON-formatted DICOM mapping definition to /xapi/dicom_mappings/update

A custom variable is required because this set of APIs does not actually modify the XSD for a given session datatype. Custom variables are indexed and searchable, and can be added to data tables on your report pages in XNAT. See Adding Custom Variables to XNAT Projects

Here is an example JSON-formatted DICOM mapping definition for an MR Session, for a specific project with ID "ProjectA":

    "scope": "Project",
    "scopeObjectId": "ProjectA",
    "fieldName": "weight",
    "fieldType": "float",
    "dicomTag": "0x00101030",
    "schemaElement": "xnat:mrSessionData"

PUT this definition to /xapi/dicom_mappings/update, then you will see DICOM data populated in the "weight" custom variable field on your session report page.

Adding Custom Parameters to an Image Scan Datatype

Extracting values from DICOM fields and including them at the MR scan level does not require a custom variable.

    "scope": "Project",
    "scopeObjectId": "ProjectA",
    "fieldName": "pixel-spacing",
    "fieldType": "string",
    "dicomTag": "0x00280030",
    "schemaElement": "xnat:mrScanData"

PUT this definition to /xapi/dicom_mappings/update. Then you'll see a "pixel-spacing" row on your scan details page.

  • No labels