Page tree
Skip to end of metadata
Go to start of metadata

The ability to define UI features in properties files was introduced in XNAT 1.6, but support for this was removed in XNAT 1.7. However, these URIs still function, if on a limited basis.


Contents:


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:
 

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:

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

This velocity method of checking user permissions is not supported in XNAT 1.7. See Changes in XNAT that affect Customizations.



Get All Defined Features In A Site

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. 

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

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

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

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
keyRequired 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.

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
keyRequired 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
  • No labels