Actions in the Event Service

Logging Action

The default Logging Action is currently the only built-in XNAT Action and can be subscribed to by any Event. The Logging Action is most useful either for recording an event in the history table or as the first step in creating a more complex subscription.

This example will show the usage of the Logging Action, linked via Subscription to a Session Created Event, for the purpose of discovering event details. These details can be used to refine the Event Subscription settings, including the development of a payload filter.

Add a new Event Subscription using default project, attribute, filter, and user values.

Add a new imaging session to your XNAT via upload, XML modification, or through the UI. Here, the Actions menu is used on a Project page.

Minimal details are needed to create the new session.

After the new session has been created, browse to the Event Service History page.

There should be an entry for your new Event, listed by event time and Subscription Name.

Click on the history item of interest to see its details.

Event Payload

Note especially the payload section of Event Details. This JSON string is the serialized representation of the Event payload object and serves as input for Event Payload Filters.

CODE

{
    "id": "XNAT_E00042",
    "label": "12345",
    "xsiType": "xnat:mrSessionData",
    "uri": "/archive/experiments/XNAT_E00042",
    "scans": [
        {
            "type": "Scan",
            "id": "1",
            "label": "1 - Unknown",
            "xsiType": "xnat:mrScanData",
            "uri": "/archive/experiments/XNAT_E00042/scans/1",
            "resources": [],
            "quality": "usable",
            "integer-id": 277,
            "scan-type": "Unknown",
            "session-id": "XNAT_E00042"
        }
    ],
    "assessors": [],
    "resources": [],
    "directory": "/data/xnat/archive/Fruit_Struct/arc001/12345/",
    "project-id": "Fruit_Struct",
    "subject-id": "XNAT_S00017",
    "modalities-in-study": [null]
}

After triggering the Session Event, resulting in the Logging Action, the original subscription can be refined to target particular sessions.

From the main Event Service page, select either the Subscription title or edit icon.

In the Edit Event Subscription dialog, subscription properties can be refined, such as project specification, attributes, payload filter, and event user.

Configuring Email Actions

In XNAT 1.8.7, the ability to send outgoing emails in response to event triggers was added.

See: Configuring an Email Action

Container Service Actions

The Container Service 3.x plugin exposes enabled container commands as Event Service Actions. In order to launch a container on a specified project, the container command must first be enabled (site-wide and at the project level). It is recommended to use container commands that have been tested and can reliably be launched from the default Container Service context launcher.

Container Service commands are designed to have one external input. This external input can be any of the base XNAT datatypes or derivatives. The command input is further specified by a set of "contexts", including XNAT xsiType strings (e.g. xnat:imageScanType, xnat:imageSessionData, etc.). An Event Service Subscription, with Container Service Action, links the Event payload to the external input of a container command.

In the Quick-Start example, the dcm2niix-scan Container Service command is subscribed to Scan Created events. In the abridged JSON command for dcm2niix-scan below, notice that the external-input is of type Scan and the contexts property contains xnat:imageScanData. The Container Service plugin provides these properties to Event Service, exposing the command as an available scan-level Action.

CODE

{
    "name": "dcm2niix",
    "description": "Runs dcm2niix",
 ...
    "xnat": [
        {
            "name": "dcm2niix-scan",
            "description": "Run dcm2niix on a Scan",
            "label": "dcm2niix",
            "contexts": ["xnat:imageScanData"],
            "external-inputs": [
                {
                    "name": "scan",
                    "description": "Input scan",
                    "type": "Scan",
                    "required": true,
                    "matcher": "'DICOM' in @.resources[*].label"
...
}

Because this command is enabled at the site-level and project-level, it will be available as an option in the Select Action drop-down selector for Subscription creation on our project.