Skip to main content

This is documentation for Caché & Ensemble. See the InterSystems IRIS version of this content.Opens in a new tab

For information on migrating to InterSystems IRISOpens in a new tab, see Why Migrate to InterSystems IRIS?

This version of the product is no longer supported, and this documentation is no longer updated regularly. See the latest version of this content.Opens in a new tab

Security.Domains

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

SQL Table Name: Security.Domains

This class defines the security domains for a system.
Domain names have the following properties:
1) Domain names are case insensitive.
2) Maximum length of a domain name is 64 characters.
The %Admin Secure:USE permission is required to operate on a domain

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 = 128);
Domain description.
Property methods: DescriptionDisplayToLogical(), DescriptionGet(), DescriptionGetStored(), DescriptionIsValid(), DescriptionLogicalToDisplay(), DescriptionLogicalToOdbc(), DescriptionNormalize(), DescriptionSet()
property Name as %String (MAXLEN = 64, MINLEN = 1) [ Required ];
Name of the domain.
Property methods: NameDisplayToLogical(), NameGet(), NameGetStored(), NameIsValid(), NameLogicalToDisplay(), NameLogicalToOdbc(), NameNormalize(), NameSet()

Methods

classmethod Change(OldDomainName As %String, NewDomainName As %String) as %Status
Change the domain of users.
This method will change the domain to a new domain for users which match the old domain. Its primary use is if we change the default system domain, we would call this method to change all the users which referenced the old default domain.
Note that if a username@domain already exists in the new domain we are changing to, then the old username@domain is just deleted, and the new one is used. If there is any error during the operation, the entire transaction is rolled back.
Parameters:
OldName - Domain name to change
NewDomain - Domain name to change to
If OldName="", then we are changing from using no domains to using domains i.e. the multiple domains parameter is turned on. NewDomain must be a valid domain set up in the domain file. If NewDomain="", then we are changing from using multiple Domains to using no domains. In order for this to succeed, all the users must have the same domain name as the OldDomainName parameter passed in. Note that if we are going from no domains to Multiple domains, or Multiple domains to no domains, the system parameter governing this must be set before this method is called.
classmethod Create(Name As %String, Description As %String) as %Status
Create a Domain.
Create a Domain in the Security database.
Parameters:
Name - Name of the domain to create
Description - Description of the domain
classmethod Delete(Name As %String) as %Status
Delete a domain.
This method will delete a domain from the security database. If the domain is in use by a user, the domain will not be deleted.
Parameters:
Name - Name of domain to delete
classmethod Exists(Name As %String, ByRef Domain As %ObjectHandle, ByRef Status As %Status) as %Boolean
Domain exists.
This method checks for the existence of a domain in the security database.
Parameters:
Name - Name of the domain to check existence of
Return values:
If Value of the method = 0 (Domain does not exist, or some error occured)
Domain = Null
Status = Domain "x" does not exist, or other error message

If Value of the method = 1 (Domain exists)
Domain = Object handle to domain
Status = $$$OK
classmethod Export(FileName As %String = "DomainsExport.xml", ByRef NumExported As %Integer, Domains As %String = "*") as %Status
This method exports Domain records to a file in xml format.
Parameters:
Filename - Output file name
NumExported (byref) - Returns number of records exported.
Domains - Comma separated list of Domains to export, "*" = All
classmethod Get(Name As %String, ByRef Properties As %String) as %Status
Get a domain's properties.
Gets a domain's properties from the security database.
Parameters:
Name - Name of the domain to get
Return values:
Properties - Array of properties
Properties("Description") - Description of the domain
classmethod GetProperties(Domain As %ObjectHandle, ByRef Properties As %String) as %Status
Get a domain's properties.
Gets a domain's properties from the security database.
Parameters:
Domain - Object handle to a Domain record
Return values:
Properties - See the Get method for more information on properties returned
classmethod Import(FileName As %String = "DomainsExport.xml", ByRef NumImported As %Integer, Flags As %Integer = 0) as %Status
Import Domain records from an xml file.
Parameters:
FileName - Filename to import Domain 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 InUse(Name As %String, ByRef InUse As %Boolean = 0, ByRef Users As %List, ByRef MoreUsers As %Boolean = 0) as %Status
Checks if the domain is in use.
Checks if the domain specified is used by any user.
Parameters:
Name - Name of the domain to check.
Return values:
InUse = 0 Not used
InUse = 1 Used
Users = $list of users the domain is used by or null if none
MoreUsers = 0 - Entire list of users using the domain returned
MoreUsers = 1 - Entire list of users using the role Not returned
If MoreUsers=1, and you wish to get the entire list of users using the domain, use the following code:
s x=##Class(Security.Domains).InUse("Domain1",.InUse,.Users,.MoreUsers) While (MoreUsers) {
s SaveUsers($i(i))=Users
s x=##Class(Security.Domains).InUse("Domain1",.InUse,.Users,.MoreUsers)
classmethod Modify(Name As %String, ByRef Properties As %String) as %Status
Modify a domain.
Modify an existing domain's properties in the security database.
Parameters:
Name - Name of the domain to modify
Properties - Array of properties to modify.
See the Get() method for a description of the Properties parameter.
If a specific property is not passed in the properties array, the value is not modified.

Queries

query List(Names As %String = "*", Flags As %Integer = 0)
Selects Name As %String, Description
List of Domains.
Names - Comma separated list of Domain names, "*" = All
Flags - 0 - Use "Startswith" as the selection on the name.
Flags - 1 - Use "Contains" as the selection on the name.
Note: This query may change in future versions

Indexes

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

Inherited Members

Inherited Methods

Storage

Storage Model: CacheStorage (Security.Domains)

^|$$$SecurityMapDomains|SYS("Security","DomainsD")(ID)
 =
%%CLASSNAME
Description
Name
FeedbackOpens in a new tab