com.ibm.itim.apps.provisioning
Class AccountManager

java.lang.Object
  com.ibm.itim.apps.provisioning.AccountManager

public class AccountManager
extends java.lang.Object

Provides aggregate account management capabilities. These capabilities include the creation of accounts, the validation of accounts, and the resolution of what services are available for an individual within the provisioning platform. Before creating an account, there should be (1) a person (account owner) who will own the account, (2) a service that will host this account, and (3) a provisioning policy for the service entitiled to the account owner. Account creation and modification are tied to the system's provisioning policies in a number of ways. For example, an account is "compliant" if it conforms with a provisioning policy. If the account does not conform with a provisioning policy, then it is a "non-compliant account". If there is no provisioning policy defined for the account, then it is marked "disallowed". Depending on the compliance status of the account and the policy enforcement of an account's host service, some account operations are not allowed. For example, if the account being created is "non-compliant" and the enforcement setting for the host service is set to "Suspend" or "Correct", then the account can not be created. In such case, ApplicationException will be thrown by the createAccount method.

See Also:

AccountMO

Constructor Summary

AccountManager(PlatformContext platform, javax.security.auth.Subject subject)
Constructs the manager with a platform context and a subject.

Method Summary

void	adopt(DistinguishedName ownerDN, java.util.Collection accounts) Adopts multiple accounts, or assigns the same owner (given) to all the accounts submitted.
void	adopt(DistinguishedName ownerDN, java.lang.String ownershipType, java.util.Collection accounts) Adopts multiple accounts, or assigns the same owner (given) to all the accounts submitted.
Compliance	checkAccountCompliance(PersonMO owner, ServiceMO service, AttributeValues params) Checks the account compliance on the given service with the given parameters for the given owner.
Compliance	checkAccountCompliance(PersonMO owner, ServiceMO service, java.lang.String ownershipType, AttributeValues params) This method checks the account compliance on the service with the parameters for the owner.
Request	createAccount(PersonMO owner, ServiceMO service, Account subject, java.util.Date scheduledTime) Creates an account in the provisioning platform with the specified attributes for the given person.
Request	createAccount(PersonMO owner, ServiceMO service, java.lang.String ownershipType, Account subject, java.util.Date scheduledTime) This method creates an account in the provisioning platform with the specified attributes for the given person.
AccountMO	getAccountByURI(OrganizationalContainerMO container, java.lang.String uri) Returns the account for the given Uniform Resource Identifier (URI) within the specified parent container.
AttributeValues	getAccountParameters(PersonMO owner, ServiceMO service) Returns the auto-generated parameters used to define the potential owner's individual account on the given service.
AttributeValues	getAccountParameters(PersonMO owner, ServiceMO service, java.lang.String ownershipType) Returns the auto-generated parameters used to define the potential owner's account of the specified ownership type on the given service.
java.util.Collection	getAccounts(PersonMO person, java.util.Locale locale) Returns the account(s) for the given person.
java.util.Collection	getAccounts(PersonMO person, java.lang.String ownershipType, java.util.Locale locale) Returns the accounts for the person.
java.util.Collection	getAccounts(ServiceMO service, java.lang.String uid) Returns the account(s) with the uid hosted on the given service.
java.util.Collection	getAccounts(ServiceMO service, java.lang.String attributeName, java.lang.Object attributeValue) Returns the account(s) matching the given attribute hosted on the given service.
void	getAccounts(ServiceMO service, java.lang.String attributeName, java.lang.Object attributeValue, SearchResultsMO results) Returns the account(s) matching the given attribute hosted on the given service.
java.util.Collection	getAuthorizedOwnershipTypes(ServiceMO service, PersonMO person) Returns the authorized ownership types for the person on the given service
java.util.Collection	getAuthorizedServices(PersonMO subject, java.util.Locale locale) Returns the services the given person is authorized to have access to.
java.util.Collection	getAuthorizedServices(PersonMO subject, java.util.Locale locale, java.lang.String pattern, java.lang.String type) Returns the services the given person is authorized to have access to.
java.util.Map<Account,java.util.Collection<java.lang.String>>	getMandatoryGroupNames(java.util.Collection<Account> accounts) Provides the names of the mandatory groups for the given accounts.
void	getNonCompliantAccounts(SearchResultsMO results) Returns all accounts that are currently tracked as non-compliant by the provisioning system through the results parameter.
void	getNonCompliantAccounts(ServiceMO service, SearchResultsMO results) Returns all accounts on the given service that are currently tracked as non-compliant by the provisioning system through the results parameter.
java.util.Collection<Account>	getRequiredAccounts(PersonMO owner, java.util.Collection<Account> accounts) Determines which of the given accounts are required by provisioning policy for the specified account owner.
boolean	isAccountCompliant(AccountMO subject, java.util.Collection errors) Deprecated. Please use checkAccountCompliance method.
boolean	isAccountCompliant(PersonMO owner, ServiceMO service, AttributeValues params, java.util.Collection errors) Deprecated. Please use checkAccountCompliance method.
void	orphan(DistinguishedName userDN, java.util.Collection accounts) Orphans multiple accounts, or changes the account owner to unknown.
void	recertifyAccessOverride(java.util.Collection<com.ibm.itim.apps.provisioning.access.UserAccess> accesses, java.lang.String justification) Recertifies the given accesses by immediately overriding their recertification status.
void	recertifyOverride(java.util.Collection accounts, java.lang.String justification) Audits the collection of accounts passed in.
Request	remove(java.util.Collection accounts, java.util.Date scheduledTime) Removes multiple accounts from the provisioning platform.
Request	restore(java.util.Collection accounts, java.util.Date scheduledTime) Restores multiple accounts.
Request	restore(java.util.Collection accounts, java.lang.String password, java.util.Date scheduledTime) Restores multiple accounts with the password specified.
Request	submitAdoptionRequest(DistinguishedName ownerDN, java.lang.String ownershipType, java.util.Collection accounts) Adopts multiple accounts, or assigns the same owner (given) to all the accounts submitted.
Request	suspend(java.util.Collection accounts, java.util.Date scheduledTime) Suspends multiple accounts.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

AccountManager

public AccountManager(PlatformContext platform,
                      javax.security.auth.Subject subject)

Constructs the manager with a platform context and a subject.

Parameters:

platform - PlatformContext holding platform connection information.

subject - Subject representing the authenticated caller.

Method Detail

createAccount

public Request createAccount(PersonMO owner,
                             ServiceMO service,
                             Account subject,
                             java.util.Date scheduledTime)
                      throws java.rmi.RemoteException,
                             AuthorizationException,
                             SchemaViolationException,
                             ApplicationException

Creates an account in the provisioning platform with the specified attributes for the given person.

Parameters:

owner - PersonMO who will own the account. If owner is null than an IllegalArgumentException will be thrown.

service - ServiceMO the account will be provisioned on. If service is null than an IllegalArgumentException will be thrown.

subject - Account value object defining the attributes the account will have.

scheduledTime - The scheduled starting time of the process. If null, the process will start immediately. In case this method is invoked remotely, passing this parameter as the current date/time of the client machine is not a safe technique to use, since the date/time of the client machine may not be the same as the date/time of the ITIM server machine.

Returns:

Request object representing the operation's status. If the schedule time is set for the future, then the Request's getStatus() will return the current status at that point of time.

Throws:

java.rmi.RemoteException - Thrown if unable to communicate with platform.

AuthorizationException - Thrown if client is unauthorized to create an account for the given person or the client is unauthorized to write any of account attributes.

SchemaViolationException - Thrown if any of the attributes in the value object violates the managed object's schema. This may be caused by an invalid attribute or if a required attribute is missing entirely.

ApplicationException - Thrown if unable to submit the request. This may possibly be caused by 1. If the owner is removed by another client previous to this call. 2. If the password is not valid. (The actual exception will be the instance of InvalidPasswordException.) 3. If the account being created is non-compliant (or unauthorized) and the enforcement setting of the hosting service is set to "Suspend" or "Correct".

createAccount

public Request createAccount(PersonMO owner,
                             ServiceMO service,
                             java.lang.String ownershipType,
                             Account subject,
                             java.util.Date scheduledTime)
                      throws java.rmi.RemoteException,
                             AuthorizationException,
                             SchemaViolationException,
                             ApplicationException

This method creates an account in the provisioning platform with the specified attributes for the given person.

Parameters:

owner - PersonMO Specifies who owns the account. If the owner is null, an IllegalArgumentException is thrown.

service - ServiceMO Specifies the service that the account is provisioned on. If the service is null, an IllegalArgumentException is thrown.

ownershipType - Specifies the ownership type for the account. These following values are already defined:

• OwnershipType.DEVICE
• OwnershipType.INDIVIDUAL
• OwnershipType.SYSTEM
• OwnershipType.VENDOR

subject - Specifies the account value object that defines the attributes that the account has.

scheduledTime - Specifies the scheduled starting time of the process. If null, the process starts immediately. If this method is invoked remotely, do not pass this parameter as the current date/time or time of the client machine. The date or time of the client machine may not be the same as the date or time of the IBM Security Identity Server server machine.

Returns:

Request Specifies the object that represents the status of the operation. If the schedule time is set for the future, then the Request getStatus() returns the current status at that time.

Throws:

java.rmi.RemoteException - if call to a remote method cannot be executed.

AuthorizationException - Thrown if the client is unauthorized to create an account for the given person or if the client is unauthorized to write any of the account attributes.

SchemaViolationException - Thrown if any of the attributes in the value object violates the schema of the managed object. This exception might be caused by an incorrect attribute or a missing required attribute.

ApplicationException - Thrown the system is unable to submit the request. This error might be caused

• 1. If another client removes the owner before this call.
• 2. If the password is not valid. The actual exception is the instance of InvalidPasswordException.
• 3. If the account being created is non-compliant (or unauthorized), and the enforcement setting of the hosting service is set to "Suspend" or "Correct".

See Also:

RemoteException

getAuthorizedOwnershipTypes

public java.util.Collection getAuthorizedOwnershipTypes(ServiceMO service,
                                                        PersonMO person)
                                                 throws java.rmi.RemoteException,
                                                        ApplicationException

Returns the authorized ownership types for the person on the given service

Parameters:

service - ServiceMO representing the service.

person - PersonMO representing the person.

Returns:

Collection of ownership types authorized for the person on the given service.

Throws:

java.rmi.RemoteException - Thrown if unable to communicate with platform.

ApplicationException - Thrown if unable to obtain the authorized ownership types. This error might be caused by the service or the person being removed by another client previous to this call. This error might also be caused by a failure in processing policies to obtain the authorized ownership types.

java.lang.IllegalArgumentException - Thrown if the service or person parameter is null.

getAuthorizedServices

public java.util.Collection getAuthorizedServices(PersonMO subject,
                                                  java.util.Locale locale)
                                           throws java.rmi.RemoteException,
                                                  AuthorizationException,
                                                  ApplicationException

Returns the services the given person is authorized to have access to.

Parameters:

subject - PersonMO representing the person in question.

locale - optional Locale used to sort the results by Service name. If null, Locale.getDefault() (server JVM) is used.

Returns:

Collection of ServiceMO's representing the services the subject has access to. The empty collection will be returned if there is no service that is authorized for a subject person.

Throws:

java.rmi.RemoteException - Thrown if unable to communicate with platform.

AuthorizationException - Thrown if client is unauthorized to view (search) the subject person.

ApplicationException - Thrown if unable to obtain the authorized services. This may possibly be caused by the subject being removed by another client previous to this call. This may be also caused by a fault in processing policies in order to obtain the authorized services.

java.lang.IllegalArgumentException - Thrown if the subject is null.

getAuthorizedServices

public java.util.Collection getAuthorizedServices(PersonMO subject,
                                                  java.util.Locale locale,
                                                  java.lang.String pattern,
                                                  java.lang.String type)
                                           throws java.rmi.RemoteException,
                                                  AuthorizationException,
                                                  ApplicationException

Returns the services the given person is authorized to have access to.

Parameters:

subject - PersonMO representing the person in question.

locale - optional Locale used to sort the results by Service name. If null, Locale.getDefault() (server JVM) is used.

pattern - String pattern that must be present in the Service name or Service description for a match to occur, indicating possible matches for services. If pattern is "*", implies all authorized services based on Service Profile type will be returned.

type - Service Profile name of the authorized services to be searched. If null, all types of services, the person has access to, are returned.

Returns:

Collection of ServiceMO's representing the services the subject has access to. The empty collection will be returned if there is no service that is authorized for a subject person.

Throws:

java.rmi.RemoteException - Thrown if unable to communicate with platform.

AuthorizationException - Thrown if client is unauthorized to view (search) the subject person.

ApplicationException - Thrown if unable to obtain the authorized services. This may possibly be caused by the subject being removed by another client previous to this call. This may be also caused by a fault in processing policies in order to obtain the authorized services.

java.lang.IllegalArgumentException - Thrown if the subject is null.

getAccountParameters

public AttributeValues getAccountParameters(PersonMO owner,
                                            ServiceMO service)
                                     throws java.rmi.RemoteException,
                                            AuthorizationException,
                                            ApplicationException

Returns the auto-generated parameters used to define the potential owner's individual account on the given service. Note, the client may not be authorized to view all of the parameters. These parameters will be omitted from the returned list without the generation of an AuthorizationException.

Parameters:

owner - PersonMO representing the person in question. If owner is null an IllegalArgumentException will be thrown.

service - ServiceMO representing the service in question. If service is null an IllegalArgumentException will be thrown.

Returns:

AttributeValues holding the generated account parameters.

Throws:

java.rmi.RemoteException - Thrown if unable to communicate with platform.

AuthorizationException - Thrown if client is unauthorized to view (search) the subject person, accounts of this type, and/or service.

ApplicationException - Thrown if unable to generate the parameters. This may possibly be caused by the owner or service being removed by another client previous to this call. This may be also caused by a fault in processing policies in order to generate the parameters or there is no policy defined for the owner and service.

getAccountParameters

public AttributeValues getAccountParameters(PersonMO owner,
                                            ServiceMO service,
                                            java.lang.String ownershipType)
                                     throws java.rmi.RemoteException,
                                            AuthorizationException,
                                            ApplicationException

Returns the auto-generated parameters used to define the potential owner's account of the specified ownership type on the given service. Note, the client may not be authorized to view all of the parameters. These parameters will be omitted from the returned list without the generation of an AuthorizationException.

Parameters:

owner - PersonMO representing the person in question. If owner is null an IllegalArgumentException will be thrown.

service - ServiceMO representing the service in question. If service is null an IllegalArgumentException will be thrown.

ownershipType - Valid ownership type configured at system level

Returns:

AttributeValues holding the generated account parameters.

Throws:

java.rmi.RemoteException - Thrown if unable to communicate with platform.

AuthorizationException - Thrown if client is unauthorized to view (search) the subject person, accounts of this type, and/or service.

ApplicationException - Thrown if unable to generate the parameters. This may possibly be caused by the owner or service being removed by another client previous to this call. This may be also caused by a fault in processing policies in order to generate the parameters or there is no policy defined for the owner and service.

getNonCompliantAccounts

public void getNonCompliantAccounts(SearchResultsMO results)
                             throws java.rmi.RemoteException,
                                    ApplicationException

Returns all accounts that are currently tracked as non-compliant by the provisioning system through the results parameter. The non-compliance may be due to unauthorized access to a service completely, or just a constraint violation with the parameters of an account. Note, the client may not be authorized to view all of the accounts that are non-compliant. Those unauthorized accounts will be filtered out of the returned list and no AuthorizationException will be thrown.

Parameters:

results - SearchResultsMO to hold the results of the search. The SearchResultsMO is used to support the paging and sorting for the presentation layer. The object will be filled with Account value objects that represent non-compliant accounts. Note, if the SearchResultsMO object was constructed using a different user context, that context will be changed to match the context of this object.

Throws:

java.rmi.RemoteException - Thrown if unable to communicate with platform.

ApplicationException - Thrown if unable to retrieve the accounts. This may be also caused by a fault in data services area.

java.lang.IllegalArgumentException - Thrown if the results is null.

See Also:

SearchResultsMO

getNonCompliantAccounts

public void getNonCompliantAccounts(ServiceMO service,
                                    SearchResultsMO results)
                             throws java.rmi.RemoteException,
                                    ApplicationException

Returns all accounts on the given service that are currently tracked as non-compliant by the provisioning system through the results parameter. The non-compliance may be due to unauthorized access to a service completely, or just a constraint violation with the parameters of an account. Note, the client may not be authorized to view all of the accounts that are non-compliant. Those unauthorized accounts will be filtered out of the returned list and no AuthorizationException will be thrown.

Parameters:

service - ServiceMO constraining the search.

results - SearchResultsMO to hold the results of the search. The SearchResultsMO is used to support the paging and sorting for the presentation layer. The object will be filled with Account value objects that represent non-compliant accounts. Note, if the SearchResultsMO object was constructed using a different user context, that context will be changed to match the context of this object.

Throws:

java.rmi.RemoteException - Thrown if unable to communicate with platform.

ApplicationException - Thrown if unable to retrieve the accounts.

java.lang.IllegalArgumentException - Thrown if the service or the results is null.

See Also:

SearchResultsMO

isAccountCompliant

public boolean isAccountCompliant(AccountMO subject,
                                  java.util.Collection errors)
                           throws java.rmi.RemoteException,
                                  AuthorizationException,
                                  ApplicationException

Deprecated. Please use checkAccountCompliance method.

Returns whether the given account is compliant with all policies. Not only is a boolean result returned, but a list of errors (if any) are also available on request.

Parameters:

subject - AccountMO representing the account in question.

errors - If non-null, will be filled with detected errors. The errors are represented as Strings.

Throws:

java.rmi.RemoteException - Thrown if unable to communicate with platform.

AuthorizationException - Thrown if client is unauthorized to view (search) the subject account.

ApplicationException - Thrown if unable to generate the parameters. This may possibly be caused by the account being removed by another client previous to this call. This may be also caused by a fault in processing policies in order to evaluate compliance.

See Also:

checkAccountCompliance(PersonMO, ServiceMO, AttributeValues)

isAccountCompliant

public boolean isAccountCompliant(PersonMO owner,
                                  ServiceMO service,
                                  AttributeValues params,
                                  java.util.Collection errors)
                           throws java.rmi.RemoteException,
                                  AuthorizationException,
                                  ApplicationException

Deprecated. Please use checkAccountCompliance method.

Returns whether the an (potential) account on the given service with the given parameters for the given owner is compliant with all policies. Not only is a boolean result returned, but a list of errors (if any) are also available on request.

Parameters:

owner - PersonMO representing the person in question.

service - ServiceMO representing the service in question.

params - AttributeValues holding the parameters of the (potential) account.

errors - If non-null, will be filled with detected errors. The errors are represented as Strings.

Throws:

java.rmi.RemoteException - Thrown if unable to communicate with platform.

AuthorizationException - Thrown if client is unauthorized to view (search) the subject person and/or service.

ApplicationException - Thrown if unable to generate the parameters. This may possibly be caused by the owner and/or service being removed by another client previous to this call. This may be also caused by a fault in processing policies in order to evaluate compliance.

See Also:

checkAccountCompliance(PersonMO, ServiceMO, AttributeValues)

checkAccountCompliance

public Compliance checkAccountCompliance(PersonMO owner,
                                         ServiceMO service,
                                         AttributeValues params)
                                  throws java.rmi.RemoteException,
                                         AuthorizationException,
                                         ApplicationException

Checks the account compliance on the given service with the given parameters for the given owner. The account is compliant if it conforms to the provisioning policy. This method returns the Compliance object and it has the information about the compliance status, the required AttributeChanges if the account is not compliant, and the attribute properties for the non-compliant attributes.

Parameters:

owner - PersonMO representing the person in question. If owner is null an IllegalArgumentException will be thrown.

service - ServiceMO representing the service in question.If service is null an IllegalArgumentException will be thrown.

params - AttributeValues holding the parameters of the (potential) account.

Returns:

Compliance object that have the compliance status and the required AttributeChanges if the account is not compliant.

Throws:

java.rmi.RemoteException - Thrown if unable to communicate with platform.

AuthorizationException - Thrown if client is unauthorized to view (search) the subject person and/or service.

ApplicationException - Thrown if unable to check the account compliance. This may possibly be caused by (1) the owner and/or service being removed by another client previous to this call, or (2)an error in processing policies in order to evaluate compliance.

Since:

ITIM 4.6

See Also:

Compliance

checkAccountCompliance

public Compliance checkAccountCompliance(PersonMO owner,
                                         ServiceMO service,
                                         java.lang.String ownershipType,
                                         AttributeValues params)
                                  throws java.rmi.RemoteException,
                                         AuthorizationException,
                                         ApplicationException

This method checks the account compliance on the service with the parameters for the owner. The account is compliant if it conforms to the provisioning policy. This method returns the compliance object that contains information about the compliance status. If the account is not compliant, the compliance object also contains the required attribute changes and the attribute properties for the non-compliant attributes.

Parameters:

owner - PersonMO Specifies the person being evaluated. If the owner is null, an IllegalArgumentException is thrown.

service - ServiceMO Specifies the service being evaluated. If the service is null, an IllegalArgumentException is thrown.

ownershipType - Specifies the ownership type of the account. If the value is specified, the ownership type attribute in the attribute list is overwritten. These following values are already defined:

• OwnershipType.DEVICE
• OwnershipType.INDIVIDUAL
• OwnershipType.SYSTEM
• OwnershipType.VENDOR

params - Holds the attribute values of the (potential) account.

Returns:

Compliance object has the compliance status and the required AttributeChanges), if the account is not compliant.

Throws:

java.rmi.RemoteException - if call to a remote method cannot be executed.

AuthorizationException - Thrown if the client is unauthorized to view or search the subject person or service.

ApplicationException - Thrown the system is unable to check the account compliance. This error might be caused:

• If another client removes the owner or service before this call.
• If an error occurs in processing the policies used to evaluate compliance.

Since:

IBM Security Identity Manager 6.1

See Also:

Compliance, RemoteException

getAccounts

public java.util.Collection getAccounts(PersonMO person,
                                        java.util.Locale locale)
                                 throws java.rmi.RemoteException,
                                        ApplicationException

Returns the account(s) for the given person. Note, if the client is unauthorized to view (search) an account that matches this criteria, it will be filtered out of the return list and no AuthorizationException will be thrown.

Parameters:

person - PersonMO representing the person to scope the search.

locale - optional Locale used to do a locale-sensitive sort of the results by user id. If null, Locale.getDefault() is used (server JVM).

Returns:

Collection of AccountMO's representing the matching accounts.

Throws:

java.rmi.RemoteException - Thrown if unable to communicate with platform.

ApplicationException - Thrown if unable to obtain the accounts. This may possibly be caused by the service being removed by another client previous to this call.

java.lang.IllegalArgumentException - Thrown if the person is null.

getAccounts

public java.util.Collection getAccounts(PersonMO person,
                                        java.lang.String ownershipType,
                                        java.util.Locale locale)
                                 throws java.rmi.RemoteException,
                                        ApplicationException

Returns the accounts for the person. Note, if the client is unauthorized to view (search) an account that matches this criteria, the account is filtered out of the return list and no AuthorizationException is thrown.

Parameters:

person - PersonMO Specifies the person that is the scope of the search.

ownershipType - Specifies the ownership type of the account. These following values are already defined:

• OwnershipType.DEVICE
• OwnershipType.INDIVIDUAL
• OwnershipType.SYSTEM
• OwnershipType.VENDOR

locale - Specifies to perform a locale-sensitive sort of the results found for the specified person and ownership type. If null is specified, java.util.Locale.getDefault() is used (server JVM).

Returns:

Collection of AccountMO that contains the matching accounts.

Throws:

java.rmi.RemoteException - if call to a remote method cannot be executed.

ApplicationException - if a list of account cannot be obtained. This error might be caused if another client removes the person before this call.

java.lang.IllegalArgumentException - if the person is null.

See Also:

RemoteException

getAccounts

public java.util.Collection getAccounts(ServiceMO service,
                                        java.lang.String uid)
                                 throws java.rmi.RemoteException,
                                        ApplicationException

Returns the account(s) with the uid hosted on the given service. Note, if the client is unauthorized to view (search) an account that matches this criteria, it will be filtered out of the return list and no AuthorizationException will be thrown.

Parameters:

service - ServiceMO representing the service to scope the search.

uid - User id of the account to retrieve.

Returns:

Collection of AccountMO's representing the matching accounts.

Throws:

java.rmi.RemoteException - Thrown if unable to communicate with platform.

ApplicationException - Thrown if unable to obtain the accounts. This may possibly be caused by the service being removed by another client previous to this call.

java.lang.IllegalArgumentException - Thrown if the service is null.

getAccounts

public java.util.Collection getAccounts(ServiceMO service,
                                        java.lang.String attributeName,
                                        java.lang.Object attributeValue)
                                 throws java.rmi.RemoteException,
                                        ApplicationException

Returns the account(s) matching the given attribute hosted on the given service. Note, if the client is unauthorized to view (search) an account that matches this criteria, it will be filtered out of the return list and no AuthorizationException will be thrown.

Parameters:

service - ServiceMO representing the service to scope the search.

attributeName - Name of attribute to match with.

attributeValue - Value of the attribute to match with. A * can be used as the first and/or last character of a String value if a "contains" expression is wished.

Returns:

Collection of AccountMO's representing the matching accounts.

Throws:

java.rmi.RemoteException - Thrown if unable to communicate with platform.

ApplicationException - Thrown if unable to obtain the accounts. This may possibly be caused by the service being removed by another client previous to this call.

java.lang.IllegalArgumentException - Thrown if the service is null.

getAccounts

public void getAccounts(ServiceMO service,
                        java.lang.String attributeName,
                        java.lang.Object attributeValue,
                        SearchResultsMO results)
                 throws java.rmi.RemoteException,
                        ApplicationException

Returns the account(s) matching the given attribute hosted on the given service. Note, if the client is unauthorized to view (search) an account that matches this criteria, it will be filtered out of the return list and no AuthorizationException will be thrown.

Parameters:

service - ServiceMO representing the service to scope the search.

attributeName - Name of attribute to match with.

attributeValue - Value of the attribute to match with. A * can be used as the first and/or last character of a String value if a "contains" expression is wished.

results - SearchResultsMO to hold the results of the search. The object will be filled with Account value objects that match the given criteria. Note, if the SearchResultsMO object was constructed using a different user context, that context will be changed to match the context of this object.

Throws:

java.rmi.RemoteException - Thrown if unable to communicate with platform.

ApplicationException - Thrown if unable to obtain the accounts. This may possibly be caused by the service being removed by another client previous to this call.

java.lang.IllegalArgumentException - Thrown if the service is null.

getAccountByURI

public AccountMO getAccountByURI(OrganizationalContainerMO container,
                                 java.lang.String uri)
                          throws java.rmi.RemoteException,
                                 ApplicationException

Returns the account for the given Uniform Resource Identifier (URI) within the specified parent container.

Parameters:

container - OrganizationalContainerMO representing the parent container to scope the search.

uri - String representing the account URI.

Returns:

AccountMO representing the matching account

Throws:

java.rmi.RemoteException - Thrown if unable to communicate with platform.

ApplicationException - Thrown if unable to obtain the account. This might be caused by the container being removed by another client previous to this call. This exception might also be thrown if the container object is null or represents the tenant, no account is found for the given URI within the container, or more than one account is found for the given URI within the container.

adopt

public void adopt(DistinguishedName ownerDN,
                  java.util.Collection accounts)
           throws java.rmi.RemoteException,
                  AuthorizationException,
                  ApplicationException

Adopts multiple accounts, or assigns the same owner (given) to all the accounts submitted.

Parameters:

ownerDN - DistinguishedName of the new account owner.

accounts - Collection of Account DirectoryObject to assign an owner to.

Throws:

java.rmi.RemoteException - Thrown if unable to communicate with platform.

AuthorizationException - Thrown if client is unauthorized to modify any of the account or owner attribute of the account.

ApplicationException - Thrown if unable to adopt any of the accounts. This may possibly be caused by the account or owner being removed by another client previous to this call. Also thrown if the account is disallowed and the hosting service's enforcement action is set to "Correct".

java.lang.IllegalArgumentException - Thrown if the ownerDN is null. Also thrown if the accounts is null or the empty collection.

adopt

public void adopt(DistinguishedName ownerDN,
                  java.lang.String ownershipType,
                  java.util.Collection accounts)
           throws java.rmi.RemoteException,
                  AuthorizationException,
                  ApplicationException

Adopts multiple accounts, or assigns the same owner (given) to all the accounts submitted. All accounts are assigned with the specified ownership type.

Parameters:

ownerDN - Specifies the DistinguishedName of the new account owner.

ownershipType - The new ownership type for the adopted account. These following values are already defined:

• OwnershipType.DEVICE
• OwnershipType.INDIVIDUAL
• OwnershipType.SYSTEM
• OwnershipType.VENDOR

accounts - Collection of Account objects that an owner is assigned to.

Throws:

java.rmi.RemoteException - if call to a remote method cannot be executed.

AuthorizationException - if the client is unauthorized to modify any of the account or owner attribute of the account.

ApplicationException - if the account cannot be adopted. This error might be caused if another client removes the account or owner before this call.

This exception is also thrown if the account is disallowed and the hosting enforcement action of the service is set to "Correct".

java.lang.IllegalArgumentException - if the ownerDN parameter is null.

This exception is also thrown if the list of accounts is empty or null.

See Also:

RemoteException

orphan

public void orphan(DistinguishedName userDN,
                   java.util.Collection accounts)
            throws java.rmi.RemoteException,
                   AuthorizationException,
                   ApplicationException

Orphans multiple accounts, or changes the account owner to unknown.

Parameters:

userDN - DistinguishedName identifies an authenticated SystemUser.

accounts - Collection of Account DirectoryObjects to orphan.

Throws:

java.rmi.RemoteException - Thrown if unable to communicate with platform.

AuthorizationException - Thrown if client is unauthorized to orphan any of the accounts.

ApplicationException - Thrown if unable to orphan the accounts. This may possibly be caused by (1) the account being removed by another client previous to this call, (2) the one of account is an ITIM account.

suspend

public Request suspend(java.util.Collection accounts,
                       java.util.Date scheduledTime)
                throws java.rmi.RemoteException,
                       ApplicationException,
                       AuthorizationException

Suspends multiple accounts. After the account is suspended, the account becomes inactive account.

Parameters:

accounts - Collection of Account DirectoryObjects to suspend.

scheduledTime - The scheduled starting time of the process. If null, the process will start immediately. In case this method is invoked remotely, passing this parameter as the current date/time of the client machine is not a safe technique to use, since the date/time of the client machine may not be the same as the date/time of the ITIM server machine.

Returns:

Request object representing the operation's status. If the schedule time is set for the future, then the Request's getStatus() will return the current status at that point of time.

Throws:

java.rmi.RemoteException - Thrown if unable to communicate with platform.

AuthorizationException - Thrown if client is unauthorized to suspend any of the accounts.

ApplicationException - Thrown if unable to submit the request.

restore

public Request restore(java.util.Collection accounts,
                       java.util.Date scheduledTime)
                throws java.rmi.RemoteException,
                       ApplicationException,
                       AuthorizationException

Restores multiple accounts. If the account is disallowed or non-compliant and the enforcement action of hosting service is set to "Suspend" or "Correct", the account can not be restored. If one of accounts is in this category, then the ApplicationException will be thrown.

Parameters:

accounts - Collection of Account DirectoryObjects to restore.

scheduledTime - The scheduled starting time of the process. If null, the process will start immediately. In case this method is invoked remotely, passing this parameter as the current date/time of the client machine is not a safe technique to use, since the date/time of the client machine may not be the same as the date/time of the ITIM server machine.

Returns:

Request object representing the operation's status. If the schedule time is set for the future, then the Request's getStatus() will return the current status at that point of time.

Throws:

java.rmi.RemoteException - Thrown if unable to communicate with platform.

AuthorizationException - Thrown if client is unauthorized to restore any of the accounts.

ApplicationException - Thrown if unable to submit the request. Also thrown if one of accounts is disallowed or non-compliant and the enforcement action of hosting service is set to "Suspend" or "Correct".

restore

public Request restore(java.util.Collection accounts,
                       java.lang.String password,
                       java.util.Date scheduledTime)
                throws java.rmi.RemoteException,
                       ApplicationException,
                       AuthorizationException

Restores multiple accounts with the password specified.

Parameters:

accounts - Collection of Account objects to restore.

password - Password to be used to restore the accounts under the following conditions:

• If password synchronization is disabled, the password applies to any accounts that support password change. The password requirement can be determined by checking the service that hosts the account. Refer to function 'isPasswordRequired' of ServiceMO for details.
• If password synchronization is enabled, the password applies to any sponsored accounts that support password change, or to any individual accounts which support password change, but whose owner does not have a synchronized password. If the account owner has a synchronized password, the individual accounts use the owner's synchronized password instead; If the owner does not have a synchronized password, the new password is set as the synchronized password for the owner, and password synchronization is triggered for all the individual accounts of the owner.

scheduledTime - The scheduled starting time of the process. If null, the process will start immediately. In case this method is invoked remotely, passing this parameter as the current data/time of the client machine is not a safe technique to use, since the date/time of the client machine may not be the same as the date/time of the ITIM server machine.

Returns:

Request object representing the operation's status.

Throws:

java.rmi.RemoteException - Thrown if there is a communication failure.

AuthorizationException - Thrown if client is unauthorized to restore any of the accounts.

ApplicationException - Thrown if business rules are violated, while performing requested operation, for example when any one of the accounts in the collection is an orphan account. This exception may be thrown if any account in the collection is a non-compliant or disallowed account governed by a service with policy enforcement set to "Suspend" or "Correct".

remove

public Request remove(java.util.Collection accounts,
                      java.util.Date scheduledTime)
               throws java.rmi.RemoteException,
                      ApplicationException,
                      AuthorizationException

Removes multiple accounts from the provisioning platform. If there is an automatic provisioning policy defined for a person and a service, then a person should have at least one account on that service. If all these accounts are requested to be deleted, then the ApplicationException will be thrown.

Parameters:

accounts - Collection of Account DirectoryObjects to remove.

scheduledTime - The scheduled starting time of the process. If null, the process will start immediately. In case this method is invoked remotely, passing this parameter as the current date/time of the client machine is not a safe technique to use, since the date/time of the client machine may not be the same as the date/time of the ITIM server machine.

Returns:

Request object representing the operation's status. If the schedule time is set for the future, then the Request's getStatus() will return the current status at that point of time.

Throws:

java.rmi.RemoteException - Thrown if unable to communicate with platform.

AuthorizationException - Thrown if client is unauthorized to remove any of the accounts.

ApplicationException - Thrown if unable to submit the request. This may caused by (1) if the account was already removed by another client prevous to this call, or (2) if the accounts being removed are required by the automatic provisioning policy.

recertifyOverride

public void recertifyOverride(java.util.Collection accounts,
                              java.lang.String justification)
                       throws ApplicationException,
                              java.rmi.RemoteException

Audits the collection of accounts passed in.

Parameters:

accounts - A collection of Account objects to audit for recertification.

justification - The comments provided by the requester while recertifying the accounts.

Throws:

ApplicationException, - RemoteException An exception will be thrown on any failure.

ApplicationException

java.rmi.RemoteException

recertifyAccessOverride

public void recertifyAccessOverride(java.util.Collection<com.ibm.itim.apps.provisioning.access.UserAccess> accesses,
                                    java.lang.String justification)
                             throws ApplicationException,
                                    java.rmi.RemoteException

Recertifies the given accesses by immediately overriding their recertification status.

Parameters:

accesses - A collection of UserAccess objects to audit for recertification.

justification - The comments provided by the requester while recertifying the accesses.

Throws:

ApplicationException - Thrown if unable to set the recertification status of an access.

java.rmi.RemoteException - An exception will be thrown on any failure.

getRequiredAccounts

public java.util.Collection<Account> getRequiredAccounts(PersonMO owner,
                                                         java.util.Collection<Account> accounts)
                                                  throws ApplicationException,
                                                         java.rmi.RemoteException

Determines which of the given accounts are required by provisioning policy for the specified account owner. An account is considered required if, together with the other specified accounts, it cannot be deleted or taken away from the user. More precisely, this method considers an account to be required if and only if:
1) The account exists on a service that is automatically entitled to the user.
2) All other accounts owned by the user on the same service are also passed to this method.

Parameters:

owner - owner of the given accounts. An IllegalArgumentException is thrown if this paramter is null.

accounts - accounts owned by specified owner. An IllegalArgumentException is thrown if this parameter is null.

Returns:

accounts that are required by policy for the specified owner.

Throws:

ApplicationException - if the specified owner is not the account owner of all of the given accounts, or if an error occurs while checking policy or communicating with the datastore.

java.rmi.RemoteException - if unable to communicate with the platform.

getMandatoryGroupNames

public java.util.Map<Account,java.util.Collection<java.lang.String>> getMandatoryGroupNames(java.util.Collection<Account> accounts)
                                                                                     throws ApplicationException,
                                                                                            java.rmi.RemoteException

Provides the names of the mandatory groups for the given accounts. Only the mandatory groups that currently exist on the account are returned. For SystemUser accounts, the group names represent SystemRole distinguished names.

Parameters:

accounts - accounts whose mandatory groups to determine. An IllegalArgumentException is thrown if this paramter is null.

Returns:

mapping of each given account to a collection of mandatory group names.

Throws:

ApplicationException - if an error occurs while checking policy or retrieving profile information.

java.rmi.RemoteException - if unable to communicate with the platform.

submitAdoptionRequest

public Request submitAdoptionRequest(DistinguishedName ownerDN,
                                     java.lang.String ownershipType,
                                     java.util.Collection accounts)
                              throws java.rmi.RemoteException,
                                     AuthorizationException,
                                     ApplicationException

Adopts multiple accounts, or assigns the same owner (given) to all the accounts submitted.

Parameters:

ownerDN - DistinguishedName of the new account owner.

accounts - Collection of Account DirectoryObject to assign an owner to.

Returns:

Request object representing the operation's status.

Throws:

java.rmi.RemoteException - Thrown if unable to communicate with platform.

AuthorizationException - Thrown if client is unauthorized to modify any of the account or owner attribute of the account.

ApplicationException - Thrown if unable to adopt any of the accounts. This may possibly be caused by the account or owner being removed by another client previous to this call. Also thrown if the account is disallowed and the hosting service's enforcement action is set to "Correct".

java.lang.IllegalArgumentException - Thrown if the ownerDN is null. Also thrown if the accounts is null or the empty collection.