Class Index | File Index

Classes


Namespace LABKEY.Security

LabKey Security Reporting and Helper class. This class provides several static methods and data members for calling the security-related APIs, and interpreting the results.

Additional Documentation:


Defined in: Security.js.

Namespace Summary
Constructor Attributes Constructor Name and Description
 
Field Summary
Field Attributes Field Name and Description
<static>  
LABKEY.Security.currentContainer
Exposes limited information about the current container.
<static>  
LABKEY.Security.currentUser
Exposes limited information about the current user.
<static>  
LABKEY.Security.effectivePermissions
A map of commonly used effective permissions supported in the LabKey Server.
<static>  
LABKEY.Security.permissions
A map of the various permission bits supported in the LabKey Server.
<static>  
LABKEY.Security.roles
A map of the various permission roles exposed in the user interface.
<static>  
LABKEY.Security.systemGroups
A map of the special system group ids.
Method Summary
Method Attributes Method Name and Description
<static>  
LABKEY.Security.addGroupMembers(config)
Adds a new member to an existing group.
<static>  
LABKEY.Security.createContainer(config)
Creates a new container, which may be a project, folder, or workbook.
<static>  
LABKEY.Security.createGroup(config)
Creates a new group.
<static>  
LABKEY.Security.createNewUser(config)
Creates a new user account
<static>  
LABKEY.Security.deleteContainer(config)
Deletes an existing container, which may be a project, folder, or workbook.
<static>  
LABKEY.Security.deleteGroup(config)
Deletes a group.
<static>  
LABKEY.Security.deletePolicy(config)
Deletes the security policy for the requested resource id.
<static>  
LABKEY.Security.ensureLogin(config)
Ensures that the current user is logged in.
<static>  
LABKEY.Security.getContainers(config)
Returns information about the specified container, including the user's current permissions within that container.
<static>  
LABKEY.Security.getFolderTypes(config)
Retrieves the full set of folder types that are available on the server.
<static>  
LABKEY.Security.getGroupPermissions(config)
Get the effective permissions for all groups within the container, optionally recursing down the container hierarchy.
<static>  
LABKEY.Security.getGroupsForCurrentUser(config)
Returns the set of groups the current user belongs to in the current container or specified containerPath.
<static>  
LABKEY.Security.getHomeContainer()
Returns the name of the home container, which is automatically created when your server is set up.
<static>  
LABKEY.Security.getModules(config)
Retrieves the full set of modules that are installed on the server.
<static>  
LABKEY.Security.getPolicy(config)
Retrieves the security policy for the requested resource id.
<static>  
LABKEY.Security.getRole(perms)
Returns the name of the security role represented by the permissions passed as 'perms'.
<static>  
LABKEY.Security.getRoles(config)
Returns the complete set of roles defined on the server, along with the permissions each role grants.
<static>  
LABKEY.Security.getSecurableResources(config)
Returns the tree of securable resources from the current container downward
<static>  
LABKEY.Security.getSharedContainer()
Returns the name of the shared container, which is automatically created when your server is setup.
<static>  
LABKEY.Security.getUserPermissions(config)
Returns information about a user's permissions within a container.
<static>  
LABKEY.Security.getUsers(config)
Returns a list of users given selection criteria.
<static>  
LABKEY.Security.hasEffectivePermission(effectivePermissions, desiredPermission)
Returns true if the permission passed in 'desiredPermission' is in the permissions array passed as 'effectivePermissions'.
<static>  
LABKEY.Security.hasPermission(perms, perm)
Returns true if the permission passed in 'perm' is on in the permissions set passed as 'perms'.
<static>  
LABKEY.Security.moveContainer(config)
Moves an existing container, which may be a folder or workbook to be the subfolder of another folder and/or project.
<static>  
LABKEY.Security.removeGroupMembers(config)
Removes a member from an existing group.
<static>  
LABKEY.Security.renameGroup(config)
Renames a group.
<static>  
LABKEY.Security.savePolicy(config)
Saves the supplied security policy.
Namespace Detail
LABKEY.Security
Field Detail
<static> LABKEY.Security.currentContainer
Exposes limited information about the current container. This property returns a JavaScript object with the following properties:

<static> LABKEY.Security.currentUser
Exposes limited information about the current user. This property returns a JavaScript object with the following properties:

<static> LABKEY.Security.effectivePermissions
A map of commonly used effective permissions supported in the LabKey Server. You can use these values with the hasEffectivePermission() method to test if a user or group has a particular permission. The values in this map are as follows: For example, to refer to the update permission, the syntax would be:
LABKEY.Security.effectivePermissions.update

<static> LABKEY.Security.permissions
A map of the various permission bits supported in the LabKey Server. You can use these values with the hasPermission() method to test if a user or group has a particular permission. The values in this map are as follows: For example, to refer to the update permission, the syntax would be:
LABKEY.Security.permissions.update

<static> LABKEY.Security.roles
A map of the various permission roles exposed in the user interface. The members are as follows: For example, to refer to the author role, the syntax would be:
LABKEY.Security.roles.author

<static> LABKEY.Security.systemGroups
A map of the special system group ids. These ids are assigned by the system at initial startup and are constant across installations. The values in this map are as follows: For example, to refer to the administrators group, the syntax would be:
LABKEY.Security.systemGroups.administrators
Method Detail
<static> {Mixed} LABKEY.Security.addGroupMembers(config)
Adds a new member to an existing group.
Parameters:
config
A configuration object with the following properties:
{int} config.groupId
The id of the group to which you want to add the member.
{int|int[]} config.principalIds
An integer id or array of ids of the users or groups you want to add as members.
{Function} config.success
A reference to a function to call with the API results. This function will be passed the following parameters:
  • data: a simple object with a property named "added" that contains the added principal id.
  • response: The XMLHttpResponse object
{Function} config.failure Optional
A reference to a function to call when an error occurs. This function will be passed the following parameters:
  • errorInfo: an object containing detailed error information (may be null)
  • response: The XMLHttpResponse object
{Object} config.scope Optional
A scoping object for the success and error callback functions (default to this).
{string} config.containerPath Optional
An alternate container path to get permissions from. If not specified, the current container path will be used.
Returns:
{Mixed} In client-side scripts, this method will return a transaction id for the async request that can be used to cancel the request (see Ext.data.Connection.abort). In server-side scripts, this method will return the JSON response object (first parameter of the success or failure callbacks.)

<static> {Mixed} LABKEY.Security.createContainer(config)
Creates a new container, which may be a project, folder, or workbook.
Parameters:
config
A configuration object with the following properties
{String} config.name Optional
Required for projects or folders. The name of the container.
{String} config.title Optional
The title of the container, used primarily for workbooks.
{String} config.description Optional
The description of the container, used primarily for workbooks.
{boolean} config.isWorkbook Optional
Whether this a workbook should be created. Defaults to false.
{String} config.folderType Optional
The name of the folder type to be applied.
{function} config.success Optional
A reference to a function to call with the API results. This function will be passed the following parameters:
  • containersInfo: an object with the following properties:
    • id: the id of the requested container
    • name: the name of the requested container
    • path: the path of the requested container
    • sortOrder: the relative sort order of the requested container
    • description: an optional description for the container (may be null or missing)
    • title: an optional non-unique title for the container (may be null or missing)
    • isWorkbook: true if this container is a workbook. Workbooks do not appear in the left-hand project tree.
    • effectivePermissions: An array of effective permission unique names the group has.
  • response: The XMLHttpResponse object
{function} config.failure Optional
A reference to a function to call when an error occurs. This function will be passed the following parameters:
  • errorInfo: an object containing detailed error information (may be null)
  • response: The XMLHttpResponse object
{string} config.containerPath Optional
An alternate container in which to create a new container. If not specified, the current container path will be used.
{object} config.scope Optional
A scoping object for the success and error callback functions (default to this).
Returns:
{Mixed} In client-side scripts, this method will return a transaction id for the async request that can be used to cancel the request (see Ext.data.Connection.abort). In server-side scripts, this method will return the JSON response object (first parameter of the success or failure callbacks.)

<static> {Mixed} LABKEY.Security.createGroup(config)
Creates a new group. The new group will be created at the project level when the current container is a folder or project, or will be created at the system level if the current container is the root.
Parameters:
config
A configuration object with the following properties:
{String} config.groupName
The name of the group to create
{Function} config.success
A reference to a function to call with the API results. This function will be passed the following parameters:
  • data: a simple object with two properties: id and name (the new group id and name respectively)
  • response: The XMLHttpResponse object
{Function} config.failure Optional
A reference to a function to call when an error occurs. This function will be passed the following parameters:
  • errorInfo: an object containing detailed error information (may be null)
  • response: The XMLHttpResponse object
{Object} config.scope Optional
A scoping object for the success and error callback functions (default to this).
{string} config.containerPath Optional
An alternate container path to get permissions from. If not specified, the current container path will be used.
Returns:
{Mixed} In client-side scripts, this method will return a transaction id for the async request that can be used to cancel the request (see Ext.data.Connection.abort). In server-side scripts, this method will return the JSON response object (first parameter of the success or failure callbacks.)

<static> {Mixed} LABKEY.Security.createNewUser(config)
Creates a new user account
Parameters:
config
A configuration object with the following properties:
{String} config.email
The new user's email address.
{Boolean} config.sendEmail
Set to false to stop the server from sending a welcome email to the user.
{Function} config.success
A reference to a function to call with the API results. This function will be passed the following parameters:
  • data: a simple object with three properties: userId, email, and message.
  • response: The XMLHttpResponse object
{Function} config.failure Optional
A reference to a function to call when an error occurs. This function will be passed the following parameters:
  • errorInfo: an object containing detailed error information (may be null)
  • response: The XMLHttpResponse object
{Object} config.scope Optional
A scoping object for the success and error callback functions (default to this).
{string} config.containerPath Optional
An alternate container path to get permissions from. If not specified, the current container path will be used.
Returns:
{Mixed} In client-side scripts, this method will return a transaction id for the async request that can be used to cancel the request (see Ext.data.Connection.abort). In server-side scripts, this method will return the JSON response object (first parameter of the success or failure callbacks.)

<static> {Mixed} LABKEY.Security.deleteContainer(config)
Deletes an existing container, which may be a project, folder, or workbook.
Parameters:
config
A configuration object with the following properties
{function} config.success Optional
A reference to a function to call with the API results. This function will be passed the following parameter:
  • object: Empty JavaScript object
  • response: The XMLHttpResponse object
{function} config.failure Optional
A reference to a function to call when an error occurs. This function will be passed the following parameters:
  • errorInfo: an object containing detailed error information (may be null)
  • response: The XMLHttpResponse object
{string} config.containerPath Optional
The container which should be deleted. If not specified, the current container path will be deleted.
{object} config.scope Optional
A scoping object for the success and error callback functions (default to this).
Returns:
{Mixed} In client-side scripts, this method will return a transaction id for the async request that can be used to cancel the request (see Ext.data.Connection.abort). In server-side scripts, this method will return the JSON response object (first parameter of the success or failure callbacks.)

<static> {Mixed} LABKEY.Security.deleteGroup(config)
Deletes a group.
Parameters:
config
A configuration object with the following properties:
{int} config.groupId
The id of the group to delete
{Function} config.success
A reference to a function to call with the API results. This function will be passed the following parameters:
  • data: a simple object with a property named "deleted" that contains the deleted group id.
  • response: The XMLHttpResponse object
{Function} config.failure Optional
A reference to a function to call when an error occurs. This function will be passed the following parameters:
  • errorInfo: an object containing detailed error information (may be null)
  • response: The XMLHttpResponse object
{Object} config.scope Optional
A scoping object for the success and error callback functions (default to this).
{string} config.containerPath Optional
An alternate container path to get permissions from. If not specified, the current container path will be used.
Returns:
{Mixed} In client-side scripts, this method will return a transaction id for the async request that can be used to cancel the request (see Ext.data.Connection.abort). In server-side scripts, this method will return the JSON response object (first parameter of the success or failure callbacks.)

<static> {Mixed} LABKEY.Security.deletePolicy(config)
Deletes the security policy for the requested resource id. This will cause resource to inherit its security policy from its parent resource.
Parameters:
config
A configuration object with the following properties
{String} config.resourceId
The unique id of the securable resource.
{Function} config.success
A reference to a function to call with the API results. This function will be passed the following parameters:
  • data: a simple object with one property called 'success' which will be set to true.
  • response: The XMLHttpResponse object
{Function} config.failure Optional
A reference to a function to call when an error occurs. This function will be passed the following parameters:
  • errorInfo: an object containing detailed error information (may be null)
  • response: The XMLHttpResponse object
{Object} config.scope Optional
A scoping object for the success and error callback functions (default to this).
{string} config.containerPath Optional
An alternate container path to get permissions from. If not specified, the current container path will be used.
Returns:
{Mixed} In client-side scripts, this method will return a transaction id for the async request that can be used to cancel the request (see Ext.data.Connection.abort). In server-side scripts, this method will return the JSON response object (first parameter of the success or failure callbacks.)

<static> {Mixed} LABKEY.Security.ensureLogin(config)
Ensures that the current user is logged in.
Parameters:
{object} config
A configuration object with the following properties:
{boolean} config.useSiteLoginPage Optional
Set to true to redirect the browser to the normal site login page. After the user logs in, the browser will be redirected back to the current page, and the current user information will be available via LABKEY.Security.currentUser. If omitted or set to false, this function will attempt to login via an AJAX request, which will cause the browser to display the basic authentication dialog. After the user logs in successfully, the config.success function will be called.
{function} config.success
A reference to a function that will be called after a successful login. It is passed the following parameters:
  • results: an object with the following properties:
Note that if the current user is already logged in, the successCallback function will be called immediately, passing the current user information from LABKEY.Security.currentUser.
{function} config.failure Optional
A reference to a function to call when an error occurs. This function will be passed the following parameters:
  • errorInfo: an object containing detailed error information (may be null)
  • response: The XMLHttpResponse object
{object} config.scope Optional
A scoping object for the success and error callback functions (default to this).
{boolean} config.force Optional
Set to true to force a login even if the user is already logged in. This is useful for keeping a session alive during a long-lived page. To do so, call this function with config.force set to true, and config.useSiteLoginPage to false (or omit).
Returns:
{Mixed} In client-side scripts, this method will return a transaction id for the async request that can be used to cancel the request (see Ext.data.Connection.abort). In server-side scripts, this method will return the JSON response object (first parameter of the success or failure callbacks.)

<static> {Mixed} LABKEY.Security.getContainers(config)
Returns information about the specified container, including the user's current permissions within that container. If the includeSubfolders config option is set to true, it will also return information about all descendants the user is allowed to see.
Parameters:
config
A configuration object with the following properties
{Mixed} config.container Optional
A container id or full-path String or an Array of container id/full-path Strings. If not present, the current container is used.
{boolean} config.includeSubfolders Optional
If set to true, the entire branch of containers will be returned. If false, only the immediate children of the starting container will be returned (defaults to false).
{boolean} config.includeEffectivePermissions Optional
If set to false, the effective permissions for this container resource will not be included. (defaults to true)
{int} config.depth Optional
May be used to control the depth of recursion if includeSubfolders is set to true.
{Array} config.moduleProperties Optional
The names (Strings) of modules whose Module Property values should be included for each container. Use "*" to get the value of all Module Properties for all modules.
{function} config.success
A reference to a function to call with the API results. This function will be passed the following parameters:
  • containersInfo: If config.container is an Array, an object with property containers and value Array of 'container info' is returned. If config.container is a String, a object of 'container info' is returned.
    The 'container info' properties are as follows:
    • id: the id of the requested container
    • name: the name of the requested container
    • path: the path of the requested container
    • sortOrder: the relative sort order of the requested container
    • activeModules: an assay of the names (strings) of active modules in the container
    • folderType: the name (string) of the folder type, matched with getFolderTypes()
    • description: an optional description for the container (may be null or missing)
    • title: an optional non-unique title for the container (may be null or missing)
    • isWorkbook: true if this container is a workbook. Workbooks do not appear in the left-hand project tree.
    • isContainerTab: true if this container is a Container Tab. Container Tabs do not appear in the left-hand project tree.
    • userPermissions: (DEPRECATED) the permissions the current user has in the requested container. Use this value with the hasPermission() method to test for specific permissions.
    • effectivePermissions: An array of effective permission unique names the group has.
    • children: if the includeSubfolders parameter was true, this will contain an array of child container objects with the same shape as the parent object.
    • moduleProperties: if requested in the config object, an array of module properties for each included module:
      • name: the name of the Module Property.
      • moduleName: the name of the module specifying this property.
      • effectiveValue: the value of the property, including a value potentially inherited from parent containers.
      • value: the value of the property as set for this specific container
  • response: The XMLHttpResponse object
{function} config.failure Optional
A reference to a function to call when an error occurs. This function will be passed the following parameters:
  • errorInfo: an object containing detailed error information (may be null)
  • response: The XMLHttpResponse object
{string} config.containerPath Optional
An alternate container path to get permissions from. If not specified, the current container path will be used.
{object} config.scope Optional
A scoping object for the success and error callback functions (default to this).
Returns:
{Mixed} In client-side scripts, this method will return a transaction id for the async request that can be used to cancel the request (see Ext.data.Connection.abort). In server-side scripts, this method will return the JSON response object (first parameter of the success or failure callbacks.)

<static> {Mixed} LABKEY.Security.getFolderTypes(config)
Retrieves the full set of folder types that are available on the server.
Parameters:
config
A configuration object with the following properties
{function} config.success
A reference to a function to call with the API results. This function will be passed the following parameter:
  • folderTypes: Map from folder type name to folder type object, which consists of the following properties:
    • name: the cross-version stable name of the folder type
    • description: a short description of the folder type
    • label: the name that's shown to the user for this folder type
    • defaultModule: name of the module that provides the home screen for this folder type
    • activeModules: an array of module names that are automatically active for this folder type
    • workbookType: boolean that indicates if this is specifically intended to use as a workbook type
    • requiredWebParts: an array of web parts that are part of this folder type and cannot be removed
      • name: the name of the web part
      • properties: a map of properties that are automatically set
    • preferredWebParts: an array of web parts that are part of this folder type but may be removed. Same structure as requiredWebParts
  • response: The XMLHttpResponse object
{function} config.failure Optional
A reference to a function to call when an error occurs. This function will be passed the following parameters:
  • errorInfo: an object containing detailed error information (may be null)
  • response: The XMLHttpResponse object
{object} config.scope Optional
A scoping object for the success and error callback functions (default to this).
Returns:
{Mixed} In client-side scripts, this method will return a transaction id for the async request that can be used to cancel the request (see Ext.data.Connection.abort). In server-side scripts, this method will return the JSON response object (first parameter of the success or failure callbacks.)

<static> {Mixed} LABKEY.Security.getGroupPermissions(config)
Get the effective permissions for all groups within the container, optionally recursing down the container hierarchy.
Parameters:
config
A configuration object with the following properties:
{function} config.success
A reference to a function to call with the API results. This function will be passed the following parameters:
  • groupPermsInfo: an object containing properties about the container and group permissions. This object will have the following shape:
    • container
      • id: the container id
      • name: the container name
      • path: the container path
      • isInheritingPerms: true if the container is inheriting permissions from its parent
      • groups: an array of group objects, each of which will have the following properties:
        • id: the group id
        • name: the group's name
        • type: the group's type ('g' for group, 'r' for role, 'm' for module-specific)
        • roleLabel: (DEPRECATED) a description of the group's permission role. This will correspond to the visible labels shown on the permissions page (e.g., 'Admin (all permissions)'.
        • role: (DEPRECATED) the group's role value (e.g., 'ADMIN'). Use this property for programmatic checks.
        • permissions: (DEPRECATED) The group's effective permissions as a bit mask. Use this with the hasPermission() method to test for specific permissions.
        • roles: An array of role unique names that this group is playing in the container. This replaces the existing roleLabel, role and permissions properties. Groups may now play multiple roles in a container and each role grants the user a set of permissions. Use the getRoles() method to retrieve information about the roles, including which permissions are granted by each role.
        • effectivePermissions: An array of effective permission unique names the group has.
      • children: if includeSubfolders was true, this will contain an array of objects, each of which will have the same shape as the parent container object.
  • response: The XMLHttpResponse object
{function} config.failure Optional
A reference to a function to call when an error occurs. This function will be passed the following parameters:
  • errorInfo: an object containing detailed error information (may be null)
  • response: The XMLHttpResponse object
{boolean} config.includeSubfolders Optional
Set to true to recurse down the subfolders (defaults to false)
{string} config.containerPath Optional
An alternate container path to get permissions from. If not specified, the current container path will be used.
{object} config.scope Optional
A scoping object for the success and error callback functions (default to this).
Returns:
{Mixed} In client-side scripts, this method will return a transaction id for the async request that can be used to cancel the request (see Ext.data.Connection.abort). In server-side scripts, this method will return the JSON response object (first parameter of the success or failure callbacks.)

<static> {Mixed} LABKEY.Security.getGroupsForCurrentUser(config)
Returns the set of groups the current user belongs to in the current container or specified containerPath. This may be called by any user.
Parameters:
{object} config
A configuration object with the following properties:
{function} config.success
A reference to a function that will be called with the results. This function will receive the follwing parameters:
  • results: an object with the following properties:
    • groups: An array of group information objects, each of which has the following properties:
      • id: The unique id of the group.
      • name: The name of the group.
      • isProjectGroup: true if this group is defined at the project level.
      • isSystemGroup: true if this group is defined at the system level.
{function} config.failure Optional
A reference to a function to call when an error occurs. This function will be passed the following parameters:
  • errorInfo: an object containing detailed error information (may be null)
  • response: The XMLHttpResponse object
{string} config.containerPath Optional
An alternate container path to get permissions from. If not specified, the current container path will be used.
{object} config.scope Optional
A scoping object for the success and error callback functions (default to this).
Returns:
{Mixed} In client-side scripts, this method will return a transaction id for the async request that can be used to cancel the request (see Ext.data.Connection.abort). In server-side scripts, this method will return the JSON response object (first parameter of the success or failure callbacks.)

<static> {string} LABKEY.Security.getHomeContainer()
Returns the name of the home container, which is automatically created when your server is set up. It is usually 'home'
Returns:
{string} The name of the home container automatically created on this server.

<static> {Mixed} LABKEY.Security.getModules(config)
Retrieves the full set of modules that are installed on the server.
Parameters:
config
A configuration object with the following properties
{function} config.success
A reference to a function to call with the API results. This function will be passed the following parameter:
  • folderType: the folderType, based on the container used when calling this API
  • modules: Array of all modules present on this site, each of which consists of the following properties:
    • name: the name of the module
    • required: whether this module is required in the folder type specified above
    • tabName: name of the tab associated with this module
    • active: whether this module should be active for this container
    • enabled: whether this module should be enabled by default for this container
  • response: The XMLHttpResponse object
{function} config.failure Optional
A reference to a function to call when an error occurs. This function will be passed the following parameters:
  • errorInfo: an object containing detailed error information (may be null)
  • response: The XMLHttpResponse object
{object} config.scope Optional
A scoping object for the success and error callback functions (default to this).
Returns:
{Mixed} In client-side scripts, this method will return a transaction id for the async request that can be used to cancel the request (see Ext.data.Connection.abort). In server-side scripts, this method will return the JSON response object (first parameter of the success or failure callbacks.)

<static> {Mixed} LABKEY.Security.getPolicy(config)
Retrieves the security policy for the requested resource id. Note that this will return the policy in effect for this resource, which might be the policy from a parent resource if there is no explicit policy set on the requested resource. Use the isInherited method on the returned LABKEY.SecurityPolicy object to determine if the policy is inherited or not. Note that the securable resource must be within the current container, or one of its descendants.
Parameters:
config
A configuration object with the following properties
{String} config.resourceId
The unique id of the securable resource.
{Function} config.success
A reference to a function to call with the API results. This function will be passed the following parameters:
  • policy: an instance of a LABKEY.SecurityPolicy object.
  • relevantRoles: an array of role ids that are relevant for the given resource.
  • response: The XMLHttpResponse object
{Function} config.failure Optional
A reference to a function to call when an error occurs. This function will be passed the following parameters:
  • errorInfo: an object containing detailed error information (may be null)
  • response: The XMLHttpResponse object
{object} config.scope Optional
A scoping object for the success and error callback functions (default to this).
{string} config.containerPath Optional
An alternate container path to get permissions from. If not specified, the current container path will be used.
Returns:
{Mixed} In client-side scripts, this method will return a transaction id for the async request that can be used to cancel the request (see Ext.data.Connection.abort). In server-side scripts, this method will return the JSON response object (first parameter of the success or failure callbacks.)

<static> LABKEY.Security.getRole(perms)
Returns the name of the security role represented by the permissions passed as 'perms'. The return value will be the name of a property in the LABKEY.Security.roles map. This is a local function, and does not make a call to the server.
Parameters:
{int} perms
The permissions set
Deprecated:
Do not use this anymore. Use the roles array in the various responses and the getRoles() method to obtain extra information about each role.

<static> {Mixed} LABKEY.Security.getRoles(config)
Returns the complete set of roles defined on the server, along with the permissions each role grants.
Parameters:
config
A configuration object with the following properties:
{Function} config.success
A reference to a function to call with the API results. This function will be passed the following parameters:
  • roles: An array of role objects, each of which has the following properties:
    • uniqueName: The unique name of the resource (String, typically a fully-qualified class name).
    • name: The name of the role suitable for showing to a user.
    • description: The description of the role.
    • sourceModule: The name of the module in which the role is defined.
    • permissions: An array of permissions the role grants. Each permission has the following properties:
      • uniqueName: The unique name of the permission (String, typically a fully-qualified class name).
      • name: The name of the permission.
      • description: A description of the permission.
      • sourceModule: The module in which the permission is defined.
  • response: The XMLHttpResponse object
{Function} config.failure Optional
A reference to a function to call when an error occurs. This function will be passed the following parameters:
  • errorInfo: an object containing detailed error information (may be null)
  • response: The XMLHttpResponse object
{object} config.scope Optional
A scoping object for the success and error callback functions (default to this).
Returns:
{Mixed} In client-side scripts, this method will return a transaction id for the async request that can be used to cancel the request (see Ext.data.Connection.abort). In server-side scripts, this method will return the JSON response object (first parameter of the success or failure callbacks.)

<static> {Mixed} LABKEY.Security.getSecurableResources(config)
Returns the tree of securable resources from the current container downward
Parameters:
config
A configuration object with the following properties:
{Boolean} config.includeSubfolders
If set to true, the response will include subfolders and their contained securable resources (defaults to false).
{Boolean} config.includeEffectivePermissions
If set to true, the response will include the list of effective permissions (unique names) the current user has to each resource (defaults to false). These permissions are calcualted based on the current user's group memberships and role assignments, and represent the actual permissions the user has to these resources at the time of the API call.
{Function} config.success
A reference to a function to call with the API results. This function will be passed the following parameters:
  • data: an object with a property named "resources" which contains the root resource. Each resource has the following properties:
    • id: The unique id of the resource (String, typically a GUID).
    • name: The name of the resource suitable for showing to a user.
    • description: The description of the reosurce.
    • resourceClass: The fully-qualified Java class name of the resource.
    • sourceModule: The name of the module in which the resource is defined and managed
    • parentId: The parent resource's id (may be omitted if no parent)
    • parentContainerPath: The parent resource's container path (may be omitted if no parent)
    • children: An array of child resource objects.
    • effectivePermissions: An array of permission unique names the current user has on the resource. This will be present only if the includeEffectivePermissions property was set to true on the config object.
  • response: The XMLHttpResponse object
{Function} config.failure Optional
A reference to a function to call when an error occurs. This function will be passed the following parameters:
  • errorInfo: an object containing detailed error information (may be null)
  • response: The XMLHttpResponse object
{object} config.scope Optional
A scoping object for the success and error callback functions (default to this).
{string} config.containerPath Optional
An alternate container path to get permissions from. If not specified, the current container path will be used.
Returns:
{Mixed} In client-side scripts, this method will return a transaction id for the async request that can be used to cancel the request (see Ext.data.Connection.abort). In server-side scripts, this method will return the JSON response object (first parameter of the success or failure callbacks.)

<static> {string} LABKEY.Security.getSharedContainer()
Returns the name of the shared container, which is automatically created when your server is setup. It is usually 'Shared'
Returns:
{string} The name of the shared container automatically created on this server.

<static> {Mixed} LABKEY.Security.getUserPermissions(config)
Returns information about a user's permissions within a container. If you don't specify a user id, this will return information about the current user.
Parameters:
config
A configuration object containing the following properties
{int} config.userId
The id of the user. Omit to get the current user's information
{string} config.userEmail
The email address (user name) of the user (specify only userId or userEmail, not both)
{Function} config.success
A reference to a function to call with the API results. This function will be passed the following parameters:
  • userPermsInfo: an object containing properties about the user's permissions. This object will have the following shape:
    • container: information about the container and the groups the user belongs to in that container
      • id: the container id
      • name: the container name
      • path: the container path
      • roleLabel: (DEPRECATED) a description of the user's permission role in this container. This will correspond to the visible labels shown on the permissions page (e.g., 'Admin (all permissions)'.
      • role: (DEPRECATED) the user's role value (e.g., 'ADMIN'). Use this property for programmatic checks.
      • permissions: (DEPRECATED) The user's effective permissions in this container as a bit mask. Use this with the hasPermission() method to test for specific permissions.
      • roles: An array of role unique names that this user is playing in the container. This replaces the existing roleLabel, role and permissions properties. Users may now play multiple roles in a container and each role grants the user a set of permissions. Use the getRoles() method to retrieve information about the roles, including which permissions are granted by each role.
      • effectivePermissions: An array of effective permission unique names the user has.
      • groups: an array of group objects to which the user belongs, each of which will have the following properties:
        • id: the group id
        • name: the group's name
        • roleLabel: (DEPRECATED) a description of the group's permission role. This will correspond to the visible labels shown on the permissions page (e.g., 'Admin (all permissions)'.
        • role: (DEPRECATED) the group's role value (e.g., 'ADMIN'). Use this property for programmatic checks.
        • permissions: (DEPRECATED) The group's effective permissions as a bit mask. Use this with the hasPermission() method to test for specific permissions.
        • roles: An array of role unique names that this group is playing in the container. This replaces the existing roleLabel, role and permissions properties. Groups may now play multiple roles in a container and each role grants the user a set of permissions. Use the getRoles() method to retrieve information about the roles, including which permissions are granted by each role.
        • effectivePermissions: An array of effective permission unique names the group has.
      • children: if includeSubfolders was true, this will contain an array of objects, each of which will have the same shape as the parent container object.
    • user: information about the requested user
      • userId: the user's id
      • displayName: the user's display name
  • response: The XMLHttpResponse object
{function} config.failure Optional
A reference to a function to call when an error occurs. This function will be passed the following parameters:
  • errorInfo: an object containing detailed error information (may be null)
  • response: The XMLHttpResponse object
{boolean} config.includeSubfolders Optional
Set to true to recurse down the subfolders (defaults to false)
{string} config.containerPath Optional
An alternate container path to get permissions from. If not specified, the current container path will be used.
{Object} config.scope Optional
A scoping object for the success and error callback functions (default to this).
Returns:
{Mixed} In client-side scripts, this method will return a transaction id for the async request that can be used to cancel the request (see Ext.data.Connection.abort). In server-side scripts, this method will return the JSON response object (first parameter of the success or failure callbacks.)

<static> {Mixed} LABKEY.Security.getUsers(config)
Returns a list of users given selection criteria. This may be called by any logged-in user.
Parameters:
config
A configuration object containing the following properties
{int} config.groupId Optional
The id of a project group for which you want the members.
{string} config.group Optional
The name of a project group for which you want the members (specify groupId or group, not both).
{string} config.name Optional
The first part of the user name, useful for user name completion. If specified, only users whose email address or display name starts with the value supplied will be returned.
{boolean} config.allMembers Optional
This value is used to fetch all members in subgroups.
{boolean} config.active Optional
This value is used to filter members based on activity (defaults to false).
{Mixed} config.permissions Optional
A permissions string or an Array of permissions strings. If not present, no permission filtering occurs. If multiple permissions, all permissions are required.
{function} config.success
A reference to a function to call with the API results. This function will be passed the following parameters:
  • usersInfo: an object with the following shape:
    • users: an array of user objects in the following form:
      • userId: the user's id
      • displayName: the user's display name
      • email: the user's email address
    • container: the path of the requested container
  • response: The XMLHttpResponse object
{function} config.failure Optional
A reference to a function to call when an error occurs. This function will be passed the following parameters:
  • errorInfo: an object containing detailed error information (may be null)
  • response: The XMLHttpResponse object
{string} config.containerPath Optional
An alternate container path to get permissions from. If not specified, the current container path will be used.
{object} config.scope Optional
A scoping object for the success and error callback functions (default to this).
Returns:
{Mixed} In client-side scripts, this method will return a transaction id for the async request that can be used to cancel the request (see Ext.data.Connection.abort). In server-side scripts, this method will return the JSON response object (first parameter of the success or failure callbacks.)

<static> {boolean} LABKEY.Security.hasEffectivePermission(effectivePermissions, desiredPermission)
Returns true if the permission passed in 'desiredPermission' is in the permissions array passed as 'effectivePermissions'. This is a local function and does not make a call to the server.
Parameters:
{Array} effectivePermissions
The permission set, typically retrieved for a given user or group.
{String} desiredPermission
A specific permission bit to check for.
Returns:
{boolean}

<static> LABKEY.Security.hasPermission(perms, perm)
Returns true if the permission passed in 'perm' is on in the permissions set passed as 'perms'. This is a local function and does not make a call to the server.
Parameters:
{int} perms
The permission set, typically retrieved for a given user or group.
{int} perm
A specific permission bit to check for.

<static> LABKEY.Security.moveContainer(config)
Moves an existing container, which may be a folder or workbook to be the subfolder of another folder and/or project.
Parameters:
config
A configuration object with the following properties
{string} config.containerPath
The current container path of the container that is going to be moved. Additionally, the container entity id is also valid.
{string} config.destinationParent
The container path of destination parent. Additionally, the destination parent entity id is also valid.
{boolean} config.addAlias Optional
Add alias of current container path to container that is being moved (defaults to True).
{function} config.success Optional
A reference to a function to call with the API results. This function will be passed the following parameters:
  • object: Empty JavaScript object
  • response: The XMLHttpResponse object
{function} config.failure Optional
A reference to a function to call when an error occurs. This function will be passed the following parameters:
  • errorInfo: an object containing detailed error information (may be null)
  • response: The XMLHttpResponse object
{object} config.scope Optional
A scoping object for the success and error callback functions (default to this).

<static> {Mixed} LABKEY.Security.removeGroupMembers(config)
Removes a member from an existing group.
Parameters:
config
A configuration object with the following properties:
{int} config.groupId
The id of the group from which you want to remove the member.
{int|int[]} config.principalIds
An integer id or array of ids of the users or groups you want to remove.
{Function} config.success
A reference to a function to call with the API results. This function will be passed the following parameters:
  • data: a simple object with a property named "removed" that contains the removed principal id.
  • response: The XMLHttpResponse object
{Function} config.failure Optional
A reference to a function to call when an error occurs. This function will be passed the following parameters:
  • errorInfo: an object containing detailed error information (may be null)
  • response: The XMLHttpResponse object
{Object} config.scope Optional
A scoping object for the success and error callback functions (default to this).
{string} config.containerPath Optional
An alternate container path to get permissions from. If not specified, the current container path will be used.
Returns:
{Mixed} In client-side scripts, this method will return a transaction id for the async request that can be used to cancel the request (see Ext.data.Connection.abort). In server-side scripts, this method will return the JSON response object (first parameter of the success or failure callbacks.)

<static> {Mixed} LABKEY.Security.renameGroup(config)
Renames a group.
Parameters:
config
A configuration object with the following properties:
{int} config.groupId
The id of the group to delete
{String} config.newName
The new name for the group
{Function} config.success
A reference to a function to call with the API results. This function will be passed the following parameters:
  • data: a simple object with the following properties: 'renamed'=the group id; 'oldName'=the old name; 'newName'=the new name.
  • response: The XMLHttpResponse object
{Function} config.failure Optional
A reference to a function to call when an error occurs. This function will be passed the following parameters:
  • errorInfo: an object containing detailed error information (may be null)
  • response: The XMLHttpResponse object
{Object} config.scope Optional
A scoping object for the success and error callback functions (default to this).
{string} config.containerPath Optional
An alternate container path to get permissions from. If not specified, the current container path will be used.
Returns:
{Mixed} In client-side scripts, this method will return a transaction id for the async request that can be used to cancel the request (see Ext.data.Connection.abort). In server-side scripts, this method will return the JSON response object (first parameter of the success or failure callbacks.)

<static> {Mixed} LABKEY.Security.savePolicy(config)
Saves the supplied security policy. This object should be a LABKEY.SecurityPolicy object. This method will completely overwrite the existing policy for the resource. If another user has changed the policy in between the time it was selected and this method is called, the save will fail with an optimistic concurrency exception. To force your policy over the other, call the setModified() method on the policy passing null.
Parameters:
config
A configuration object with the following properties
{String} config.policy
The LABKEY.SecurityPolicy object
{Function} config.success
A reference to a function to call with the API results. This function will be passed the following parameters:
  • data: a simple object with one property called 'success' which will be set to true.
  • response: The XMLHttpResponse object
{Function} config.failure Optional
A reference to a function to call when an error occurs. This function will be passed the following parameters:
  • errorInfo: an object containing detailed error information (may be null)
  • response: The XMLHttpResponse object
{Object} config.scope Optional
A scoping object for the success and error callback functions (default to this).
{string} config.containerPath Optional
An alternate container path to get permissions from. If not specified, the current container path will be used.
Returns:
{Mixed} In client-side scripts, this method will return a transaction id for the async request that can be used to cancel the request (see Ext.data.Connection.abort). In server-side scripts, this method will return the JSON response object (first parameter of the success or failure callbacks.)

Documentation generated by JsDoc Toolkit 2.3.2 on Thu Mar 14 2019 22:39:27 GMT-0000 (UTC)