Step 4 of 5: Container Service Actions

Goal

In this step, you will configure Actions to bind an XNAT property to a Command variable.

Actions allow you to execute commands from an XNAT context (like a session or a subject). They let you automatically fill in Command variables from properties of XNAT objects, and to stage files from XNAT resources to be used by the docker container created using the Command.

Define an Action

Time to make an Action. This is how we can run commands with values filled in by XNAT.

1. Return to the XNAT Swagger page.
2. Expand action-rest-api, and POST /xapi/actions

3. Paste the following JSON into the actionDto field:

   CODE

    {
       "name": "echo-session",
       "description": "echo the label of an XNAT session",
       "command-id": 2,
       "root-xsi-type": "xnat:imageSessionData",
       "inputs": [
           {
               "name":"the label",
               "command-variable-name":"message",
               "root-property": "label"
           }
       ]
   }

   

   Tip: Command ID

    We are using the "echo with variable" Command, which is the second Command we created in Part 2 - Step 3: Commands. If you went along with the steps, your Command will have id=2, and we use that for command-id here. But if you did something different, and your Command has a different id, you'll need to enter that value for command-id.

   
   

   

4. Press the "Try it out!" button.
   

   

Note the Response Body. It is the id of an Action that we will use later.

Now that we've created this Action, let's examine the JSON and see what we just made. The root-xsi-type defines what kind of XNAT object this Action can be Executed on. In this case, it can run on xnat:imageSessionData, i.e. Sessions. You can see that this action will run the "echo with variable" command, because we used that Command's id for the command-id field.

The Action also has an input. Inputs are how Actions can take input values (hence the name), but they can also do two interesting things. First, they can set the command-variable-name property, which tells XNAT to use the value for this input as the value for a Command's variable. Second, the Action inputs can set the root-property, which will pull that value from whatever XNAT object the Action is running on. In this case, our Action will be running on an image session, and this input says to fill in our Command's message variable with the session's label.

Resolve the Action/Context Execution (ACE)

We will be running an action on a session that has been pre-installed in the VM dedicated for today's practical session. You should be able to see it at http://xnat-31.xnat.org/data/experiments/XNAT_E00001?format=html. If you do not, please ask an XNAT developer for help.

In order to use XNAT-hosted data with this Action, we must "resolve the Action/Context Execution" or "resolve the ACEs". We send our "Context"—i.e. the ID of whatever XNAT object we want to run an Action on—to XNAT and ask "What Actions can be run from this Context?" In the following example, our Context will contain the ID and XSI type of an MR Session. XNAT will "resolve" all of the ACEs we can run from that context and send them back down. In the processing of resolving, any Action input with a "root-property" will be given a value set to that property's value on the root object.

1. Return to the XNAT Swagger page.
2. Expand ace-rest-api, and GET /xapi/aces.
3. Enter XNAT_E00001 as the id. 
4. Enter xnat:imageSessionData as the xsiType. This should match the root-xsi-type of the Action you just made.
   

   

   
   
   
5. Press the "Try it out!" button.
   

   

The Response Body gives all of the ACEs resolved from Actions that will work with the requested xsiType and id. In this example, there should be only one.

Submit an ACE for execution

Now we want to execute the ACE we just received from XNAT. You can simply copy the ACE that you got back from XNAT in the Response Body in the last step, and POST it back up.

Submitting an ACE

Be careful how you copy the Response Body. XNAT returns a list of objects [{...}, {...}, ...], but we only want to submit one of those objects back up in our POST. If you are having trouble, you can just copy the sample ACE below and it will work if your Command and Action ids are 2 and 1, respectively.

Tip: ACE Inputs

 In general, your Action may have had other inputs that could not be resolved from whatever XNAT object, things like string or number input values that you want a user to be able to set at runtime. At this stage, after your ACE has been resolved but before you have submitted it for execution, is when you can set those values.

1. Return to the XNAT Swagger page.
2. Expand ace-rest-api, and POST /xapi/aces.

3. Enter into the aceDto field either the ACE you just got from XNAT in the last step, or paste in the following JSON (which should be the same)

   CODE

   {
       "name":"echo-session",
       "description":"echo the label of an XNAT session",
       "inputs":[
           {
               "type":null,
               "required":false,
               "value":"5Yp0E",
               "name":"the label",
               "command-variable-name":"message",
               "root-property":"label"
           }
       ],
       "action-id":1,
       "command-id":2,
       "project":"Day3Data",
       "root-id":"XNAT_E00001",
       "resources-staged":[],
       "resources-created":[]
   }
    

   

   
   

4. Press the "Try it out!" button.
   

   

   
   
   
   

The response we get back contains all the details about the ACE that was executed. Example:

{
    "name": "echo-session",
    "description": "echo the label of an XNAT session",
    "inputs": [
        {
            "type": null,
            "required": false,
            "value": "5Yp0E",
            "name": "the label",
            "command-variable-name": "message",
            "root-property": "label"
        }
    ],
    "timestamp": 1465174723755,
    "enabled": true,
    "created": 1465174723532,
    "id": 1,
    "disabled": 0,
    "action-id": 1,
    "project": "Day3Data",
    "root-id": "XNAT_E00001",
    "resources-staged": [],
    "resources-created": [],
    "resolved-command": {
        "command-id": 2,
        "run": [
            "/bin/sh",
            "-c",
            "echo 5Yp0E"
        ],
        "docker-image-id": "sha256:2fa927b5cdd31cdec0027ff4f45ef4343795c7a2d19a9af4f32425132a222330",
        "env": {},
        "mounts-in": [],
        "mounts-out": []
    },
    "container-id": "a097caccbd028d75a37c310348ca99071a3f393be9a6bb57047486efda76aa48"
}

Copy out the container-id property. Return to your VM terminal, and we can ask docker for the logs.

xnat@xnat-31:~$ docker logs <container-id>

5Yp0E

We can see that the session label has been retrieved from our XNAT session and passed to a Docker container where it was echoed to stdout.  Of course, printing a session label isn't very useful, but we can pass these containers any of our XNAT object's data. Including resource files.

 In this step, you've learned how to create Action objects and bind those objects to XNAT data via ACE. Next up, we'll build Command, Action, ACE sets that act on session image data.

Next step: ACE Practice