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

%EM.Session

class %EM.Session extends %SOAP.WebClient

This class implements a remote API that may be used to control several basic functions of an Enterprise Manager server. This allows the user to write systems management scripts, by invoking Enterprise Manager methods.

The %EM.Session object starts and maintains the API session with the EM server, and serves as the web client to make the remote calls. The Remote API must first be enabled on Enterprise Manager and the Security Policy defined (Username, WS-Security, or SSL/TLS Security). This Security Policy corresponds to the %EM.Session.Type property ("Username", "X509", "SSL"), which must be defined in the session object. The programmer first instantiates and sets all the necessary properties of an %EM.Session object (see StartSession). All error reporting by this API will be done by Throwing a %Exception.EMAPI. So all calls should be made within a Try/Catch block. The session is connected by calling StartSession: 
  set session=##class(%EM.Session).%New()
  set session.Type="Username"
  set session.Username="Manager"
  set session.Password="password"
  set session.Host="localhost"
  set session.Port=57780
  set session.Prefix=""
  try {
  	write !,"Call StartSession"
  	do session.StartSession()
  } catch ex {
  	write !,"Error: ",ex.DisplayString()
  }

The %EM.Sesssion object may then be used for further API calls: 
  set status=1
  set group="GRP1",service="Namespace"
  #; do Submit/Approve/Activate for an edited Service
  try {
  	do session.EditComplete(group,service)
  	do session.EditApprove(group,service)
  	do session.EditActivate(group,service)
  	do session.EndSession()
  } catch ex {
  	write !,"Error: ",ex.DisplayString()
  	set status=0
  }
  q status


Note that several APIs require a serviceName or a list of Services as a serviceList. These parameters require specific strings to identify the Service, which may be different from those displayed by Enterprise Manager (which are localized). The Service identifiers currently recognized by Enterprise Manager are:

"Config", "Namespace", "Security", "Users", "License", "Monitor", "Mirror", and "SQLSecurityUpdate".

Property Inventory

Method Inventory

Parameters

parameter SECURITYIN = ALLOW;
Allow WS-Security header
parameter SOAPACTIONQUOTED = 0;
If the web client has the parameter SOAPACTIONQUOTED=1, then the web client will quote the SOAPAction value for SOAP 1.1.

Properties

property Config as %String;
Name of Security.SSLConfig object if SSL to be used
Property methods: ConfigDisplayToLogical(), ConfigGet(), ConfigIsValid(), ConfigLogicalToDisplay(), ConfigLogicalToOdbc(), ConfigNormalize(), ConfigSet()
property Host as %String;
Host IP address or DNS name of EM server.
Property methods: HostDisplayToLogical(), HostGet(), HostIsValid(), HostLogicalToDisplay(), HostLogicalToOdbc(), HostNormalize(), HostSet()
property IsStarted as %Boolean [ InitialExpression = 0 ];
True (1) if the session has been started
Property methods: IsStartedDisplayToLogical(), IsStartedGet(), IsStartedIsValid(), IsStartedLogicalToDisplay(), IsStartedNormalize(), IsStartedSet()
property Password as %String;
Password for session authentication. Note that the password is cleared after StartSession is called.
Property methods: PasswordDisplayToLogical(), PasswordGet(), PasswordIsValid(), PasswordLogicalToDisplay(), PasswordLogicalToOdbc(), PasswordNormalize(), PasswordSet()
property Port as %String;
Port at host address of EM server.
Property methods: PortDisplayToLogical(), PortGet(), PortIsValid(), PortLogicalToDisplay(), PortLogicalToOdbc(), PortNormalize(), PortSet()
property Prefix as %String;
CSP prefix to be used for CSP host address of EM server.
Property methods: PrefixDisplayToLogical(), PrefixGet(), PrefixIsValid(), PrefixLogicalToDisplay(), PrefixLogicalToOdbc(), PrefixNormalize(), PrefixSet()
property Type as %String;
Type of security to be used for the session: "SSL" for SSL/TLS, "X509" for WS-Security or "Username" for only username security.
Property methods: TypeDisplayToLogical(), TypeGet(), TypeIsValid(), TypeLogicalToDisplay(), TypeLogicalToOdbc(), TypeNormalize(), TypeSet()
property Username as %String;
Username for session authentication
Property methods: UsernameDisplayToLogical(), UsernameGet(), UsernameIsValid(), UsernameLogicalToDisplay(), UsernameLogicalToOdbc(), UsernameNormalize(), UsernameSet()

Methods

method AcceptManagement(instanceName As %String) [ WebMethod ]
Accept a Management Request for an Instance.
method ApprovedChanges(groupName As %String, serviceName As %String) as %EM.ChangeList [ WebMethod ]
Return the list of changes which will be applied to an Instance when the Service is Activated.
method AssignToGroup(guid As %String, groupName As %String, override As %Boolean = 0) [ WebMethod ]
Assign an instance to a group. The assign will be done without returning Diffs for approval.
If override is true, add subgroup overrides for any diffs from the Master group.
method AssignToGroupChanges(guid As %String, groupName As %String, override As %Boolean = 0) as %EM.ChangeList [ WebMethod ]
AssignToGroupChange returns the list of changes which will be applied to an Instance when Assigned to a Group. This could be called prior to AssignToGroup().
If override is true, add subgroup overrides for any diffs from the Master group.
method CopyGroup(oldGroup As %String, newGroup As %String, newDescription As %String) [ WebMethod ]
CopyGroup creates a copy of an existing group, copying all Services and their data. The new group must not exist.
method CreateGroup(name As %String, description As %String = "", serviceList As %String = "") [ WebMethod ]
CreateGroup creates a new group.
method CreateMirrorGroup(groupName As %String, guid As %String) [ WebMethod ]
Assume management of an existing Mirror by Assigning all Instances to a new Mirror Group. The mirror is found based on the specified GUID of one of the mirror memebers
method CreateObject(groupName As %String, serviceName As %String, className As %String, objectName As %String, properties As %EM.ServiceData) [ WebMethod ]
Create a new Class object for Service settings in a Group.

The 'className' corresponds to the short name of a Cache class for the Service, e.g. 'Databases' in the Namespace Service has the same properties as the Config.Databases class in Cache.
The 'objectName' is the IdKey of the specific object, normally a simple string identified as the Name of the class. Multi-part keys will use the '||' double bar delimiter, e.g. for MapGlobal Namespace_||_GloRef. For 'singleton' objects, this must be ''.

An error is thrown if the named object already exists.
method CreateUser(user As %EM.User) [ WebMethod ]
CreateUser will create a new EM user.
method DeleteGroup(name As %String) [ WebMethod ]
DeleteGroup deletes an existing group.
method DeleteObject(groupName As %String, serviceName As %String, className As %String, objectName As %String) [ WebMethod ]
Delete an existing Class object for Service settings in a Group. See CreateObject for more details.

An error is thrown if the named object does not exist.
method DeleteUser(username As %String) [ WebMethod ]
DeleteUser deletes the specified user.
method DeleteVariable(variable As %EM.Variable) [ WebMethod ]
Delete the variable
method EditAbort(groupName As %String, serviceName As %String) [ WebMethod ]
Abort editing a service that is managed by a specified group. This method checks that the current user has edit or awaiting approval state for this service.
method EditActivate(groupName As %String, serviceName As %String) [ WebMethod ]
Activate changes and update instances with approved data for a service that is managed by a specified group. This method checks that the service is in edit mode and approved. First the versions are updated, then this method creates a message for each instance. The message is sent to the instance and results in update of the instance. Note that most services are Activated immediately and any errors are returned here. But some services (primarily Namespace) may use background JOBs to update the instances, and in that case you must check GetActivateStatus to determine the status of the Activation.
method EditApprove(groupName As %String, serviceName As %String) [ WebMethod ]
Approve editing a service that is managed by a specified group. This method checks that the service is awaiting approval for this service. If OK, then the service is put in the edit state of Approved. No one else may edit, add or resume instances. The service data is validity checked for each instance. The error for each instance is returned as part of the overall error message.
method EditChangeUser(groupName As %String, serviceName As %String, username As %String) [ WebMethod ]
This method changes which user may edit a service. This method checks that the current user either has edit mode for this service or edit is completed and the current user has approval privilege. It also checks that the new user has edit privilege for the service. If OK, then edit user is changed and service is put/left in edit mode.
method EditComplete(groupName As %String, serviceName As %String) [ WebMethod ]
Complete editing a service that is managed by a specified group. This method checks that the current user has edit mode for this service. If OK, then the service is put in the edit state of AwaitingApproval. No one else may edit, add or resume instances. The service data is validity checked for each instance. The error for each instance is returned as part of the overall error message.
method EditService(groupName As %String, serviceName As %String, timeout As %Integer = 0) [ WebMethod ]
Start editing a service that is managed by a specified group. If timeout argument is specified, then wait for this number of seconds for in process activation to finish. This method checks that this service is editable now. i.e. not in edit mode for a different user and not in update mode for approval or add instance. If editable, then puts the service into edit mode for this user.
method EndSession() [ WebMethod ]
EndSession ends the session associated with this %EM.Session object.
method ExportVersion(version As %EM.Version, filename As %String) as %FileBinaryStream [ WebMethod ]
Export the specified version of the service data as an XML file in the current format used by EM for exports.
filename is the path of the file to create which contains the exported version
method ExportVersionDifferences(version As %EM.Version, versionNumber As %String, filename As %String) as %FileBinaryStream [ WebMethod ]
Export the differences between the specified target version and the specified base version of the service data as an XML file in the current format used by EM for exports. This export may be used by ImportToService to update a service with the changes that were made to the base to become the target.
version is the version object for the target version.
versionNumber is the version number of the base version filename is the path of the file to create which contains the exported version
method GetActivateStatus(groupName As %String, serviceName As %String) as %EM.Update [ WebMethod ]
For a background Activation, return %EM.Update for the current status of the Activation.
method GetAllGroups() as %EM.GroupList [ WebMethod ]
GetAllGroups returns a list of %EM.Group objects which describe all defined groups.
method GetAllGroupsForService(serviceName As %String) as %EM.GroupList [ WebMethod ]
GetAllGroupsForService returns a list of %EM.Group objects which describe all groups which manage the specified service.
method GetAllInstances() as %EM.InstanceList [ WebMethod ]
GetAllInstances returns a list of %EM.Instance objects which describe all instances managed by this EM server.
method GetEMCertificate() as %Binary
The GetEMCertificate method is used to query the EM for its certificate. The Host, Port and Prefix properties must be set before calling GetEMCertificate.
method GetGroup(name As %String) as %EM.Group [ WebMethod ]
GetGroup returns %EM.Group object which describes the named group.
method GetGroupPrivileges(username As %String, groupName As %String) as %Integer [ WebMethod ]
GetGroupPrivileges returns the user's privileges as a bit string for the specified group: a combination of $$$EMSUserEdit, $$$EMSUserApprove and $$$EMSUserActivate, or $$$EMSUserNone.
method GetHighestVersion(groupName As %String, serviceName As %String) as %EM.Version [ WebMethod ]
The GetHighestVersion method will return the version object for the highest (i.e. most recent) previous version for a service that is managed by a specified group.
method GetInstanceByGUID(guid As %String) as %EM.Instance [ WebMethod ]
GetInstanceByGUID returns %EM.Instance object which describes the identified instance.
method GetInstanceByLocation(host As %String, port As %String, prefix As %String) as %EM.Instance [ WebMethod ]
GetInstanceByLocation returns %EM.Instance object which describes the identified instance. The host, port and prefix must exactly match those specified when registering the instance (i.e. those that display in the on the EM server).
method GetInstanceByName(instanceName As %String) as %EM.Instance [ WebMethod ]
GetInstanceByName returns %EM.Instance object which describes the identified instance.
method GetInstancePrivileges(username As %String, guid As %String) as %Integer [ WebMethod ]
GetInstancePrivileges returns the user's privileges as a bit string: a combination of $$$EMSUserEdit, $$$EMSUserApprove and $$$EMSUserActivate, or $$$EMSUserNone. The privilege is set if the user has this privilege for any group containing this instance.
method GetLowestVersion(groupName As %String, serviceName As %String) as %EM.Version [ WebMethod ]
The GetLowestVersion method will return the version object for the lowest (i.e. earliest) previous version number that is still stored for a service that is managed by a specified group.
method GetMasterGroupList(groupName As %String) as %EM.GroupList [ WebMethod ]
GetMasterGroupList returns a list of %EM.Group objects which describe all master groups for the specified group.
method GetObject(groupName As %String, serviceName As %String, className As %String, objectName As %String) as %EM.ServiceData [ WebMethod ]
Get the current properties for a Class of Service settings in a Group. See CreateObject for more details.

%EM.ServiceData = '' if the object does not exist.
method GetServiceGroup(guid As %String, serviceName As %String) as %EM.Group [ WebMethod ]
GetServiceGroup takes an instance GUID and service name as input and returns the group which manages this service for the specified instance or "" if service not managed for this instance.
method GetSubscribingGroupList(masterGroupName As %String) as %EM.GroupList [ WebMethod ]
GetSubscribingGroupList returns a list of %EM.Group objects which describe all subscribing groups for the specified master group.
method GetUser(username As %String) as %EM.User [ WebMethod ]
GetUser will get the description of the specified user.
method GetVariable(variable As %EM.Variable) as %EM.Variable [ WebMethod ]
Return the variable with the current value set. All properties of the %EM.Variable object except Value must be set must be before calling GetVariable.
method ImportToService(groupName As %String, serviceName As %String, filename As %String, copy As %Boolean = 0) [ WebMethod ]
When a service is in edit mode, it may be modified before the service data is approved and updated to the managed instances. In the initial version of this API, the service data may be modified only by importing data in XML format using the ImportToService or ImportToServiceFromStream method. The XML is in the current format used by EM for exports including exports by this API.
Import an XML export to the Workspace for a Group/Service. The caller must make sure the Service is in "edit" mode. We will check the serviceName argument against the root.ServiceName in the XML export. Note that trying to 'Add' an object that already exists is an error, as is 'Change' or 'Delete' for an object that doesn't exist. For a full Version we can use 'copy'=1, which will remove all Service data objects (except Overrides and Variables), and create an exact copy of the Import Service data.
method ImportToServiceFromStream(groupName As %String, serviceName As %String, stream As %FileBinaryStream, copy As %Boolean = 0) [ WebMethod ]
When a service is in edit mode, it may be modified before the service data is approved and updated to the managed instances. In the initial version of this API, the service data may be modified only by importing data in XML format using the ImportToService or ImportToServiceFromStream method. The XML is in the current format used by EM for exports including exports by this API.
Import an XML export to the Workspace for a Group/Service. The caller must make sure the Service is in "edit" mode. We will check the serviceName argument against the root.ServiceName in the XML export. Note that trying to 'Add' an object that already exists is an error, as is 'Change' or 'Delete' for an object that doesn't exist. For a full Version we can use 'copy'=1, which will remove all Service data objects (except Overrides and Variables), and create an exact copy of the Import Service data.
method IsApprovable(groupName As %String, serviceName As %String) as %Boolean [ WebMethod ]
Return information about whether service may be approved for a group. Return is true if may be approved.
method IsApproved(groupName As %String, serviceName As %String) as %Boolean [ WebMethod ]
Return information about whether service has already been approved for a group. Return is true if it is in approved state.
method IsEditable(groupName As %String, serviceName As %String) as %String [ WebMethod ]
Return a comma-delimited string indicating if the service may be edited (i.e. IsEditable) and if it is currently being edited, e.g. "1,1" if both true. Note that 'IsEditable' includes services that are Submitted or Approved, as they may be returned to Edit.
method IsPrepareComplete(groupName As %String, serviceName As %String) as %Boolean [ WebMethod ]
Return is true if the Prepare step for the service is complete and it's ready for update.
method IsPrepareRequired(groupName As %String, serviceName As %String) as %Boolean [ WebMethod ]
Return information about whether a Prepare step (e.g. DataMove) is required for an edit. Return is true if it is necessary for this group and service.
method ListGroupInstances(groupName As %String) as %EM.InstanceList [ WebMethod ]
Return a list of all instances which are already assigned to the specified group.
method ListGroupsForAssign(guid As %String) as %EM.GroupList [ WebMethod ]
Return a list of all groups to which the specified instance may be assigned. This method filter groups to those which may be validly have this instance assigned. For example, groups which have a service that is not already managed for one of this instance.
method ListUsers() as %EM.UserList [ WebMethod ]
Get a list of all defined EM users.
method ListVariables(variable As %EM.Variable) as %EM.VariableList [ WebMethod ]
List all variables which match the GroupName and ServiceName. Also restrict the list by GUID, if GUID is specified '= "".
method ListVersions(groupName As %String, serviceName As %String) as %EM.VersionList [ WebMethod ]
ListVersions returns a list of all versions for the specified group and service.
method ModifyObject(groupName As %String, serviceName As %String, className As %String, objectName As %String, properties As %EM.ServiceData) [ WebMethod ]
Modify an exisiting Class of Service settings in a Group. See CreateObject for more details.

An error is thrown if the named object does not exist.
method ModifyUser(user As %EM.User) [ WebMethod ]
ModifyUser will modify an existing EM user. Any properties which are not specified will remain unchanged.
method MoveVersionDifferences(version As %EM.Version, versionNumber As %Integer, targetGroupName As %String) [ WebMethod ]
Move the differences between the specified target version and the specified base version of the service data to a new version in the group named by targetGroupName (which must be in Edit mode). This move updates the service in the target group with the changes that were made to the base to become the target.
version is the version object for the target version.
versionNumber is the version number of the base version targetGroupName is the name of the group to bemodified with the changes
method PrepareForUpdate(groupName As %String, serviceName As %String) [ WebMethod ]
Start the Prepare step prior to update.
method PurgeVersions(version As %EM.Version) [ WebMethod ]
PurgeVersions deletes all versions with specified version's versionNumber or lower.
method RemoveFromGroup(guid As %String, groupName As %String) [ WebMethod ]
Remove an instance from management by a group
method RemoveFromManagement(guid As %String) [ WebMethod ]
No longer manage specified instance.
method ResumeManagement(guid As %String) [ WebMethod ]
Resume management of the specified instance. The resume will be done without returning Diffs for approval.
method RevertVersion(version As %EM.Version) [ WebMethod ]
RevertVersion will revert the active version to the specified version. The service must be put in edit mode using EditService before revert and then must be finished by EditAborted or EditCompleted/UpdateInstances. This version will become a new version.
method ReviewManagementRequest(instanceName As %String) as %EM.DataList [ WebMethod ]
Review Managent Request for an Instance. Returns a list of %String with the Issuer, SerialNumber, and Subject in that order.
method SetVariable(variable As %EM.Variable) [ WebMethod ]
Set the value of a variable
method SetVersionDescription(version As %EM.Version) [ WebMethod ]
Set Description property of a service's version.
method StartSession(type As %String = "") [ WebMethod ]
The programmer needs to first instantiate and fill in the descriptive arguments of an %EM.Session object. The session is then started by calling StartSession. The Type, Config, Username, Password, Host, Port and Prefix properties must be set before calling StartSession.
The Config property of %EM.Session must be set according to the type of the session security.
The Security.SSLConfig object must be created using the SMP or the usual Security.SSLConfig API with the client side certificate being optional. Authentication and Authorization are done by the username and password. The Security.SSLConfig is only used for Encryption.
The %SYS.X509Credentials object must contain the private key which will be used to identify the client computer. Authentication and Authorization is done by the username and password. The %SYS.X509Credentials is only used for Encryption.
method SubscribeToMasterGroup(groupName As %String, masterGroupName As %String) [ WebMethod ]
Subscribe the named group to the named master group.
method SuspendManagement(guid As %String) [ WebMethod ]
Suspend management of the specified instance.
method UnmanageMirror(groupName As %String) [ WebMethod ]
UnmanageMirror removes all Instances from the Mirror Group, but does not change the Mirror configuration on the Instances. It assumes the Group is already validated as a Mirror.
method UnsubscribeFromMasterGroup(groupName As %String, masterGroupName As %String) [ WebMethod ]
Unsubscribe the named group to the named master group.

Inherited Members

Inherited Properties

Inherited Methods

FeedbackOpens in a new tab