Import Custom DICOM Fields to Session or Scan Data via the XNAT API

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:

Parameter	Default	Description
id		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.
scope	"Site"	Determines whether this DICOM mapping should apply to all projects in this XNAT, or be limited to individual projects. Possible values: "site" "project"
scopeObjectId	null	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
fieldName		Define the custom variable or scan parameter field name. Always use lower-case characters, without spaces
fieldType		Define the SQL field type. This should be one of five values: string integer float boolean date
dicomTag		Define the DICOM tag to extract from, using hexadecimal encoding – i.e. "0x00100020" equates to (0010,0020)
schemaElement		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:

Define a site-wide or project-specific custom variable for the attribute that you want to include (i.e. "weight")
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":

CODE

  {
    "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.

CODE

{
    "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.