Skip to main content

Security.Roles

persistent class Security.Roles extends %Library.Persistent, %XML.Adaptor, %SYSTEM.Help

SQL Table Name: Security.Roles

Define the security Role database, and methods which manipulate them.
The system includes a set of pre-defined System roles. System roles cannot be deleted. Legacy system roles may be deleted.

Role names have the following properties:
1) Role names are case insensitive.
2) Maximum length of a role name is 64 characters.
3) Role name cannot contain a "," or ":"
4) Role name cannot start with a "%" unless it is a pre-defined system role
A role may exist which has no resources.
%DB_* implicit roles cannot be modified
The %Admin Secure:USE permission is required to operate on a resource

The table for this class should be manipulated only through object access, the published API's or through the System Management Portal. It should not be updated through direct SQL access.

Property Inventory

Method Inventory

Properties

property Description as %String (MAXLEN = 256);
Description of the role.
Property methods: DescriptionDisplayToLogical(), DescriptionGet(), DescriptionGetStored(), DescriptionIsValid(), DescriptionLogicalToDisplay(), DescriptionLogicalToOdbc(), DescriptionNormalize(), DescriptionSet()
property GrantedRoles as list of %String (MAXLEN = 64);
Roles assigned to the Role.
Property methods: GrantedRolesBuildValueArray(), GrantedRolesCollectionToDisplay(), GrantedRolesCollectionToOdbc(), GrantedRolesDisplayToCollection(), GrantedRolesDisplayToLogical(), GrantedRolesGet(), GrantedRolesGetObject(), GrantedRolesGetObjectId(), GrantedRolesGetStored(), GrantedRolesGetSwizzled(), GrantedRolesIsValid(), GrantedRolesLogicalToDisplay(), GrantedRolesLogicalToOdbc(), GrantedRolesNormalize(), GrantedRolesOdbcToCollection(), GrantedRolesSet(), GrantedRolesSetObject(), GrantedRolesSetObjectId()
property Name as %String (MAXLEN = 64, MINLEN = 1) [ Required ];
Role Name
Property methods: NameDisplayToLogical(), NameGet(), NameGetStored(), NameIsValid(), NameLogicalToDisplay(), NameLogicalToOdbc(), NameNormalize(), NameSet()
relationship Resources as array of Resource [ InitialExpression = $listbuild("Security.Resource","TheRole",+$this,"children",1,1) , Transient , Inverse = TheRole , Cardinality = children ];
Resource/Permission pairs the role holds
Property methods: ResourcesGet(), ResourcesGetObject(), ResourcesGetObjectId(), ResourcesGetSwizzled(), ResourcesIsEmpty(), ResourcesIsValid(), ResourcesNewObject(), ResourcesRClose(), ResourcesRExec(), ResourcesRFetch(), ResourcesRelate(), ResourcesSQLCompute(), ResourcesSet(), ResourcesUnRelate()

Methods

classmethod Copy(Name As %String, NewName As %String, NewDescription As %String) as %Status
Copy a Role.
Copy an existing role in the Security database to a new one.
Parameters:
Name - Name of the role to be copied
NewName - Name of the role to be created
Description - Description of the new role
classmethod CopySQLPrivileges(pFromRole As %String, pToRole As %String, pNamespaceList As %List = "") as %Status
CopySQLPrivileges will copy SQL Admin Privileges and SQL Object Privileges from pFromRole to pToRole. Parameters:
pFromRole - Name of the role to copy SQL privileges from
pToRole - Name of the role to copy SQL privileges to
pNamespaceList - is a $Lb(namespace names). If pNamespaceList is not specified or is "", the copy will be performed for ALL namespaces. Otherwise supply a specific list of namespace you want to copy the privileges for.
The privilege will be copied with the SAME grantor and grantee. This means if UsersA granted a privilege to UserB, and UserC calls CopySQLPrivileges to copy privs from UserB to UserD, the privileges UserD gets will have been granted by UserA. You must have the %Admin_Secure resource in order to call this API. CopySQLPrivileges returns a %Status code
classmethod Create(Name As %String, Description As %String, Resources As %String, GrantedRoles As %String) as %Status
Create a Role.
Create a Role in the Security database.
Parameters:
Name - Name of the role to create
Description - Description of the role
Resources - Resource/permission pairs to assign to the role
Resources are in the format:
ResourceName:Permission,ResourceName:Permission
For example:
s Resources="MyResource:RW,MyResource1:RWU"
s Resources="" would create a role with no resources.
Permision values are as follows:
"R"
"W"
"U"
GrantedRoles - Additional roles granted when this role is granted to a user
GrantedRoles are in the format:
"GrantedRole1,GrantedRole2"
classmethod Delete(Name As %String) as %Status
Delete a role.
This method will delete a role from the security database and remove the role from all the users which hold this role. It will then update the in memory security database to mark this role as "No access" for all resources this role holds. Pre-defined system roles cannot be deleted.
Parameters:
Name - Name of role to delete
classmethod DeleteSQLRoleInfo(Name As %String) as %Status
classmethod Exists(Name As %String, ByRef Role As %ObjectHandle, ByRef Status As %Status) as %Boolean
Role exists.
This method checks for the existence of a role in the security database.
Parameters:
Name - Name of the role to check existence of
Return values:
If Value of the method = 0 (Role does not exist, or some error occured)
Role = Null
Status = Role "x" does not exist, or other error message

If Value of the method = 1 (Role exists)
Role = Object handle to role
Status = $$$OK
classmethod Export(FileName As %String = "RolesExport.xml", ByRef NumExported As %Integer, Roles As %String = "*", Resources As %String = "*", SQLPrivileges As %Boolean = 0, ByRef NumSQLPrivilegesExported As %Integer) as %Status
This method exports Role records to a file in xml format.
Parameters:
Filename - Output file name
NumExported (byref) - Returns number of records exported.
Roles - Comma separated list of Roles to export, "*" = All
Resources - Comma separated list of Resource names, "*" = All. Export Roles containing only these resources
SQLPrivileges - 1/0 flag. If 1, export all SQL Privileges from all namespace on this system that have been directly granted to this Role
NumSQLPrivilegesExported *byref) - Returns number of SQL Privileges and SQL Admin Privilege Set records exported
Note: Database roles starting with %DB_ will not be exported.
classmethod Get(Name As %String, ByRef Properties As %String, ByRef Role As %ObjectHandle) as %Status
Get a role's properties.
Gets a role's properties from the security database.
Parameters:
Name - Name of the role to get
Return values:
Properties - Array of properties
Properties("Description") - Description of the role
Properties("Resources") - Resource names/permission pairs Resources are in the format:
ResourceName:Permission,ResourceName:Permission
For example:
Properties("Resources")="MyResource:RW,MyResource1:RWU"
Properties("GrantedRoles")=List of granted roles
For example:
Properties("GrantedRoles")="GrantedRole,GrantedRole1"
classmethod GetProperties(Role As %ObjectHandle, ByRef Properties As %String) as %Status
Get a role's properties.
Gets a role's properties from the security database.
Parameters:
Role - Object handle to a role record
Return values:
Properties - See the Get method for more information on properties returned
classmethod Import(FileName As %String = "RolesExport.xml", ByRef NumImported As %Integer, Flags As %Integer = 0, ByRef NumSQLPrivsImported As %Integer) as %Status
Import Role records from an xml file.
Parameters:
FileName - Filename to import Role records from
NumImported (byref) - Returns number of records imported
Flags - Control import
Bit 0 - Do not import records, just return count
Note: On failure, no records will be imported
classmethod Modify(Name As %String, ByRef Properties As %String) as %Status
Modify a role.
Modify an existing role's properties in the security database.
Parameters:
Name - Name of the role to modify
Properties - Array of properties to modify.
See the Get() method for a description of the Properties parameter.
Properties("Resources")="" removes all resources from a role.
If a specific property is not passed in the properties array, the value is not modified.
classmethod Rename(NewRole As %String, OldRole As %String) as %Status
Rename a role, and update all associated tables.

Queries

query Detail(Names As %String, Flags As %Integer)
Selects Name As %String, Description As %String, GrantedRoles As %String, Resources As %String, CreatedBy As %String
Return detailed information about a role.
Names - Comma separated list of Role names, "*" = All
Flags - Flags passed to query
Bit 0 - Do not include read only system roles (%DB_*, %All) Note: This query may change in future versions
query List(Names As %String, Resources As %String, Flags As %Integer)
Selects Name As %String, Description As %String, GrantedRoles As %String, CanBeEdited As %Boolean
List all user records, brief display.
Names - Comma separated list of Role names, "*" = All
Resources - Comma separated list of resources names, "*"=ALL. Resource names may be in the format "Resource1:RW,Resource2,Resource3:R". In this example, the criteria for selection is passed if any role has one of the following:
1) RW on Resource1
2) Any access on Resource2
3) Read access on Resource3
Flags - Flags passed to query
Bit 0 - Do not include read only system roles (%DB_*, %All)
query ListAll(Names As %String)
Selects Name As %String, Description As %String, GrantedRoles As %String, Resources As %String
List all user records, brief display.
Names - Comma separated list of Role names, "*" = All
Resources - Comma separated list of resources names, "*"=ALL. Resource names may be in the format "Resource1:RW,Resource2,Resource3:R". In this example, the criteria for selection is passed if any role has one of the following:
1) RW on Resource1
2) Any access on Resource2
3) Read access on Resource3
Flags - Flags passed to query
Bit 0 - Do not include read only system roles (%DB_*, %All)
query ListAll1()
SQL Query:
SELECT * FROM Roles ORDER BY Name
query ListResources(Names As %String, Resources As %String, Flag As %Integer)
Selects Name As %String, Resource As %String, Permission As %String
List all roles and their Resources and Permissions.
Names - Comma separated list of Role names, "*" = All
Resources - Comma separated list of resources names, "*"=ALL. Resource names may be in the format "Resource1:RW,Resource2,Resource3:R". In this example, the criteria for selection is passed if any role has one of the following:
1) RW on Resource1
2) Any access on Resource2
3) Read access on Resource3
Flags - Flags passed to query
Bit 0 - Do not include read only system roles (%DB_*, %All)

Indexes

index (NameIndex on NameLowerCase) [IdKey, Type = key];
Index methods: NameIndexCheck(), NameIndexDelete(), NameIndexExists(), NameIndexOpen(), NameIndexSQLCheckUnique(), NameIndexSQLExists(), NameIndexSQLFindPKeyByConstraint(), NameIndexSQLFindRowIDByConstraint()

Triggers

trigger NoSQL (BEFORE event INSERT/UPDATE/DELETE);

Inherited Members

Inherited Methods

Storage

Storage Model: Storage (Security.Roles)

^|$$$SecurityMapRolesResources|SYS("Security","RolesD")(ID)
=
%%CLASSNAME
Description
GrantedRoles
Name
NameLowerCase
Version
FeedbackOpens in a new tab