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.
Constructor Attributes | Constructor Name and Description |
---|---|
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 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.getReadableContainers(config)
Returns information about the container paths visible to the current user
|
<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.
|
Field Detail
<static>
LABKEY.Security.currentContainer
Exposes limited information about the current container. This property returns a JavaScript object
with the following properties:
- id: the container's unique id (entityid)
- name: the name of the container
- path: the path of the current container
- type: the type of container, either project, folder or workbook
<static>
LABKEY.Security.currentUser
Exposes limited information about the current user. This property returns a JavaScript object
with the following properties:
- id: the user's unique id number
- displayName: the user's display name
- email: the user's email address
- canInsert: set to true if this user can insert data in the current folder
- canUpdate: set to true if this user can update data in the current folder
- canUpdateOwn: set to true if this user can update data this user created in the current folder
- canDelete: set to true if this user can delete data in the current folder
- canDeleteOwn: set to true if this user can delete data this user created in the current folder
- isAdmin: set to true if this user has admin permissions in the current folder
- isGuest: set to true if this user is the guest (anonymous) user
- isSystemAdmin: set to true if this user is a system administrator
- isDeveloper: set to true if this user is a developer
- isSignedIn: set to true if this user is signed in
<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:
- read
- insert
- update
- del
- readOwn
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:
- read
- insert
- update
- del
- readOwn
- updateOwn
- deleteOwn
- all
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:
- admin
- editor
- author
- reader
- restrictedReader
- noPerms
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:
- administrators
- users
- guests
- developers
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
- containersInfo: an object with the following properties:
- {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, or a semicolon separated list of email addresses.
- {Boolean} config.sendEmail
- Set to false to stop the server from sending a welcome email to the user.
- {String} config.optionalMessage
- An optional message to include in the new user registration email.
- {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, or array of objects, 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:
- currentUser: a reference to the current user. See LABKEY.Security.currentUser for more details.
- results: an object with the following properties:
- {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 propertycontainers
and value Array of 'container info' is returned. Ifconfig.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
- containersInfo:
If
- {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
- folderTypes: Map from folder type name to folder type object, which consists of the following properties:
- {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.
- container
- response: The XMLHttpResponse object
- groupPermsInfo: an object containing properties about the container and group permissions.
This object will have the following shape:
- {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.
- groups: An array of group information objects, each of which has the following properties:
- results: an object with the following properties:
- {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.getReadableContainers(config)
Returns information about the container paths visible to the current user
- Parameters:
- config
- A configuration object containing the following properties
- {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).
- {int} config.depth Optional
- May be used to control the depth of recursion if includeSubfolders is set to true.
- {Mixed} config.container Optional
- A container id or full-path String or an Array of container id/full-path Strings (only the first will be used). If not present, the current container is used.
- {Function} config.success
- A reference to a function to call with the API results. This function will be passed an array of container paths as strings
<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
- roles: An array of role objects, each of which has the following properties:
- {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
- data: an object with a property named "resources" which contains the root resource.
Each resource has the following properties:
- {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
- container: information about the container and the groups the user belongs to in that container
- response: The XMLHttpResponse object
- userPermsInfo: an object containing properties about the user's permissions.
This object will have the following shape:
- {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
- users: an array of user objects in the following form:
- response: The XMLHttpResponse object
- usersInfo: an object with the following shape:
- {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.)