Features API

Defining Feature Permissions

Features are registered in XNAT via properties files which are loaded by XNAT on server startup (or first access). The server will look for any files which end with *-feature-definition.properties. All features which are automatically a part of XNAT should be defined in the xnat-feature-definition.properties file. Features developed for specific modules should be defined using a unique string in the properties file name.

Within any feature definition file, any number of features can be defined using the following format:

CODE

org.nrg.Feature=[key]
org.nrg.Feature.[key].key=[key: used to identify this feature throughout the application]
org.nrg.Feature.[key].name=[Human readable name that will be used to identify this feature within the UI]
org.nrg.Feature.[key].OnByDefault=[true: this feature will automatically be on for all users, unless disabled by the admin, false: this feature will need to be enabled by an admin or project owner for it to be usable on the site]
org.nrg.Feature.[key].description=[sentence or two describing this feature ]

If feature access is restricted for a given user in a given project (or site-wide), that portion of the UI will simply not appear. Developers can code against these feature definitions to toggle the visibility of a feature based on these restrictions like so:

CODE

#if($user.checkFeature($om, "feature_key")
   <div>some content of varying complexity</div>
#end

Get All Defined Features In A Site

CODE

GET - /data/services/features?type=admin

Parameters: None

Response:
Returns a listing of generally-available user groups (aka "Owners" but not "Project_ID_Owners") and user roles in your XNAT, and lists any features that are blocked for that class of users.

CODE

[
  {
    "groups": [
      {
        "features": [],
        "blocked": [],
        "display": "Owners",
        "id": "Owners"
      },
      ...,
      {
        "features": [],
        "blocked": [
          
        ],
        "display": "Role: Site Manager",
        "isRole": true,
        "id": "role:Administrator"
      },
      ...
    ],
    "id": "_SITE_WIDE",
    "banned": [],
    "onByDefault": [
      "manage_files"
    ]
  }
]

Get All Defined Features In A Project

CODE

GET - /data/services/features?tag={project_id}

Parameters

{project_id}	Required querystring parameter. Specifies the project context to query for features.

Response:

Returns a list of feature restrictions per user group and project-wide. Features and restrictions that are defined at the site-wide level are referred to as "inherited."

CODE

[
  {
    "groups": [
      {
        "features": [],
        "inherited_features": [],
        "inherited_banned": [],
        "blocked": [],
        "display": "Owners",
        "id": "Project_ID_owner"
      },
      ...
    ],
    "id": "Project_ID",
    "banned": [],
    "onByDefault": [
      "manage_files"
    ]
  }
]

Block Access To A Feature That Is On By Default

If a feature is defined with "OnByDefault" set to "true", then it can be disabled for specific projects or user groups.

CODE

POST - /data/services/features?group={project_group_id}

Parameters

{project_group_id}

Required querystring parameter. Specifies the project access group to restrict from using this feature

key

Required body parameter. Specifies the key associated with the defined feature.

banned

Required body parameter.

true: Restrict access to this feature for the specified group
false: Remove restriction to this feature for the specified group

Enable Access To A Feature That Is Off By Default

If a feature is defined with "OnByDefault" set to "false" or null, then it can be enabled for specific projects or user groups.

CODE

POST - /data/services/features?group={project_group_id}

Parameters

{project_group_id}

Required querystring parameter. Specifies the project access group to restrict from using this feature

key

Required body parameter. Specifies the key associated with the defined feature.

enabled

Required body parameter.

true: Enable access to this feature for the specified group
false: Disable access to this feature for the specified group