Running the Application API Examples

Overview

The following are working examples that use the Applications API. This API allows direct access to various objects within the provisioning system but all access is still subject to the rules and policies of the provisioning system. For example, when deprovisioning an account, the provisioning system is configured to either delete or suspend an account that has been deprovisioned. This system configuration will have the same effect on accounts deprovisioned via this API.

When working with the Application API, it is highly recommended that any operations to be performed are first tested manually via the standard ITIM UI.

The source code for the examples can be found in the $ITIM_HOME/extensions/examples/apps/src directory. The scripts to run the examples can be found in the $ITIM_HOME/extensions/examples/apps/bin/win directory for Windows and $ITIM_HOME/extensions/examples/apps/bin/unix directory for UNIX.


Building the Examples

To build the examples follow the instructions given in Building the Examples.

Installing the Examples on WebSphere

There is nothing additional that needs to be done if the examples are executed from their default location (ITIM installation area). The examples can also be configured to run with the WebSphere Application Client on a separate system. The instructions to setup the examples remotely are out of scope of this document. Refer to the instructions given in the API Packaging Guide to configure the ITIM APIs with the WebSphere Application Client.

Running the Examples

Build the Examples before running them. Make sure the ITIM server is running. Also verify that the values entered for the environment variables ITIM_USER and ITIM_PSWD in the setEnv.bat/setEnv.sh files have a valid ITIM user and password respectively.

Creating a new Person

The CreatePerson.java source file demonstrates how to create a new Person.

Execute the accompanying createPerson.sh or createPerson.bat file using the following command syntax:

Windows usage:

usage: createPerson -[argument] ? "[value]"

-profile        Profile name of the new Person to create
-attribute      An attribute name and value

Example: createPerson -profile?"Person" -attribute?"cn=Jenny Brown" -attribute?"sn=Brown"

The command line syntax is a list of name/value pairs in the format –[argument] ? “[value]”. The list of attributes should include all of the required attributes for a Person. The default required attributes are sn and cn.
 

Changing a Person’s Attributes

The ChangePerson.java source file demonstrates how to modify a Person’s attributes.

Execute the accompanying changePerson.sh or changePerson.bat file using the following command syntax:

Windows usage:

usage: changePerson -[argument] ? "[value]"

-personfilter   Ldap Filter to search for the Person to change
-attribute      Attribute name and new value

Example: changePerson -personfilter?"(cn=Jenny Brown)" -attribute?"cn=Jenny Green"

The command line arguments are an LDAP search filter, followed by a list of name/value pairs in the form –[argument] ? “[value]”. The Search Filter argument is used to identify the person being modified. In most instances, the ‘cn’ attribute will be used to identify a person.

Deleting a Person

The DeletePerson.java source file demonstrates how to Delete a Person.

Execute the accompanying deletePerson.sh or deletePerson.bat file using the following command syntax:

Windows usage:

usage: deletePerson -[argument] ? "[value]"

-personfilter   Ldap Filter to search for the Person to delete

Example: deletePerson -personfilter?"(cn=Jenny Brown)"


The command line argument is a Search Filter used to identify the person being deleted. In most instances, the ‘cn’ attribute will be used to identify a person.

Note that when a person is deleted, all of his accounts will be deprovisioned.

Provisioning an Account

The ProvisionAccount.java source file demonstrates how to Provision an Account.

Execute the accompanying provisionAccount.sh or provisionAccount.bat file using the following command syntax and argument list:

Windows Usage:

usage: provisionAccount -[argument] ? "[value]"

-profile           Object Profile Name for the Account to provision (e.g., NT40Account)
-serviceprofile    Object Profile Name for the Service

-uid               UserId to assign to the new Account
-password          Password to assign to the new Account
-attribute         Any attribute name/value pair (e.g., description=NT Account)
-servicefilter     Ldap Filter to search for a Service instance on which to provision the Account
-ownerfiler        Ldap Filter to search for a Person to own the Account
-[category]        Category for Person to own the Account(e.g., BPPerson). Default value is "Person"
-[categoryprofile] Category profile name for Person to own the Account
                   (e.g., MyPerson(custom class)). Default value is "Person"


Arguments enclosed in [] are optional

Example: provisionAccount -profile?NT40Account -serviceprofile?NT40Profile -uid?JSmith
-password?secret -servicefilter?"(erservicename=NT Service)" -ownerfilter?"(cn=John Smith)"
-category?Person -categoryprofile?MyPerson


Note that the list of attributes should include at least all the required attributes to create the type of account.

Changing an Account

The ChangeAccount.java source file demonstrates how to change an account’s attributes.

Execute the accompanying changeAccount.sh or changeAccount.bat file using the following command syntax:

Windows usage:

usage: changeAccount -[argument] ? "[value]"

-profile        Object Profile Name for the Account to change (e.g., NT40Account)
-accountfilter  Ldap Filter to search for the Account to change
-attribute      Attribute name and new value

Example: changeAccount -profile?NT40Account -accountfilter?"(eruid=JSmith)"
-attribute?"description=NT Account"


The command line arguments are the profile name of the Account, an LDAP search filter to lookup the account to be changed, and a list of attribute name? value pairs defining the attributes to change.
 
Changing an Account Password

The ChangePassword.java source file demonstrates how to change an account’s password.

Execute the accompanying changePassword.sh or changePassword.bat file using the following command syntax:

usage: changePassword -[argument] ? "[value]"

-profile        Object Profile Name for the Account to change password (e.g., ITIMAccount)
-accountfilter  Ldap Filter to search for the Account to change password
-password       New password

Example: changePassword -profile?ITIMAccount -accountfilter?"(eruid=JSmith)" -password?"secret"


The command line arguments are the profile name of the Account, an LDAP search filter to lookup the account, and a password value.

Deprovisioning an Account

The DeprovisionAccount.java source file demonstrates how to deprovision an Account.

Execute the accompanying deprovisionAccount.sh or deprovisionAccount.bat file using the following command syntax:

usage: deprovisionAccount -[argument] ? "[value]"

-profile        Object Profile Name for the Account to deprovision (e.g., NT40Account)
-accountfilter  Ldap Filter to search for the Account to deprovision

Example: deprovisionAccount -profile?NT40Account -accountfilter?"(eruid=JSmith)"


The command line arguments are the profile name of the Account, and an LDAP search filter to to lookup the account to be removed (deprovisioned).

Synchronizing all of a Person’s Account Passwords

The SynchPasswords.java source file demonstrates how to set all of the passwords for a person’s accounts.

Execute the accompanying synchPassword.sh or synchPassword.bat file using the following command syntax:

usage: synchPassword -[argument] ? "[value]"

-ownerfilter    Ldap Filter to search for a Person whose account passwords are to be synchronized
-password       New password

Example: synchPassword -ownerfilter?"(cn=Joe Smith)" -password?"secret"


The command line arguments are an LDAP search filter to lookup a Person, and a new password for all accounts the Person owns. In most instances, the ‘cn’ attribute will be used to identify a person.

Retrieving Assignments of a Person Account

The PersonAssignments.java source file demonstrates how to get all assignments for a person account.

Execute the accompanying personAssignments.sh or personAssignments.bat file using the following command syntax:

usage: personAssignments -[argument] ? "[value]"

-accountfilter    Ldap Filter to search for an account whose assignments are to be retrieved

Example: personAssignments -accountfilter?"(eruid=JSmith)"


The command line arguments are an LDAP search filter to lookup an Account. In most instances, the ‘eruid’ attribute will be used to identify an account.

Changing an Account Password by invoke the operation through Lifecycle Management APIs

The ChangePasswordOperation.java source file demonstrates how to invoke change account’s password operation.

Execute the accompanying changePasswordOperation.sh or changePasswordOperation.bat file using the following command syntax:

usage: changePasswordOperation -[argument] ? "[value]"

-profile        Object Profile Name for the Account to change password (e.g., ITIMAccount)
-accountfilter  Ldap Filter to search for the Account to change password
-password       New password
-notifypassword  Optional flag to identify whether to notify password. Valid values are true and false

Example: changePasswordOperation -profile?ITIMAccount -accountfilter?"(eruid=JSmith)" -password?"secret" -notifypassword?"true"



Reconciliation API related examples.

To run a reconciliation for any service, a reconciliation unit is required. A reconciliation unit contains a recurring or a one-time schedule which decides when to execute the reconciliation on the resource, specified by the service. It also contains few other parameters which affect the reconciliation process, explained in the API docs and example usage section below.

A service can have multiple reconciliation units configured, but with different schedules. A schedule uniquely identifies a reconciliation unit of a service.

The published class com.ibm.itim.apps.recon.ReconUnitData, represents a reconciliation unit of a service at the API level.
The published class com.ibm.itim.apps.recon.ReconManager, provides all functions required to perform reconciliation related operations, through API.

As a service points to a remote resource, the terms 'service' and 'resource' are used interchangeably in this documentation. Also the term 'reconciliation' and 'recon' are used interchangeably.

Scheduling Reconciliation for a service

The AddReconUnit.java source file demonstrates how to add a new recon unit.

Execute the accompanying addReconUnit.sh or addReconUnit.bat file using the following command syntax and argument list:

Windows Usage:

usage: addReconUnit -[argument] ? "[value]"

-serviceprofile      Profile Name of the Service to add a recon (e.g., WinLocalProfile)
-servicefilter       Ldap Filter to search for a Service instance to add recon
-month               Month to add recon. Valid values 1-12, -1 indicates Monthly.
-day                 Day to add recon. Valid values 1-31, -1 indicates Daily.
-dayofweek           Day of week to add recon. Valid values 1-7.(1 = Sunday, 2 = Monday,..)

NOTE: Either day or dayofweek is mandatory. If both are specified, then dayofweek will be ignored

-hour                Hour to add recon, Valid values 0-23, -1 indicates Hourly.
-minute              Minute to add recon, Valid values 0-59
-[reconfilter]       Ldap Filter to reconcile accounts
-[lockservice]       Specifies if the Service needs to be locked during recon, default value is "true"
-[maxduration]       Maximum duration(in minutes) for recon process to run (default value 600 minutes)
-[excludeattributes] Attribute(s) separated by comma to be excluded during reconciliation
-[reconcallback]     If "true" then class implementing IReconCompleteCallback interface whose                      'onReconComplete()' method gets executed after completion of scheduled recon                            process, default value="false"

Arguments enclosed in [] are optional

Example: addReconUnit -serviceprofile?WinLocalProfile -servicefilter?"(erservicename=WinLocal)"
-reconfilter?"(eruid=a*)" -excludeattributes?"erntpasswordneverexpires,description"
-maxduration?10 -month?10 -day?26 -hour?10 -minute?10 -reconcallback?"true"

Example: addReconUnit -serviceprofile?WinLocalProfile -servicefilter?"(erservicename=WinLocal)"
-reconfilter?"(eruid=a*)" -excludeattributes?"erntpasswordneverexpires,description"
-maxduration?10 -month?10 -dayofweek?1 -hour?10 -minute?10 -reconcallback?"true"


NOTE: If negative value -1 needs to be entered for month,day or hour, then change the StringTokenizer to '+' instead of '-' in function AddReconUnit.parseArgs() to identify the arguments prefixed with '+'


Removing a Reconciliation Unit of a service

A schedule uniquely identifies a reconciliation unit of a service, so it's specification is enough to identify and remove the reconciliation unit.
The RemoveReconUnit.java source file demonstrates how to remove an existing recon unit.

Execute the accompanying removeReconUnit.sh or removeReconUnit.bat file using the following command syntax and argument list:

Windows Usage:

usage: removeReconUnit -[argument] ? "[value]"

-serviceprofile      Profile Name of the Service (e.g., WinLocalProfile)
-servicefilter       Ldap Filter to search for a Service instance to remove recon
-month               Month to remove recon. Valid values 1-12, -1 indicates Monthly.
-day                 Day to remove recon. Valid values 1-31, -1 indicates Daily.
-dayofweek           Day of week to remove recon. Valid values 1-7.(1 = Sunday, 2 = Monday,..)

NOTE: Either day or dayofweek is mandatory. If both are specified, then dayofweek will be ignored

-hour                Hour to remove recon, Valid values 0-23, -1 indicates Hourly.
-minute              Minute to remove recon, Valid values 0-59

Example: removeReconUnit -serviceprofile?WinLocalProfile -servicefilter?"(erservicename=WinLocal)"
-month?10 -day?26 -hour?10 -minute?10

Example: removeReconUnit -serviceprofile?WinLocalProfile -servicefilter?"(erservicename=WinLocal)"
-month?10 -dayofweek?1 -hour?10 -minute?10


NOTE: If negative value -1 needs to be entered for month,day or hour, then change the StringTokenizer to '+' instead of '-' in function RemoveReconUnit.parseArgs() to identify the arguments prefixed with '+'


Running Reconciliation for a service immediately


The RunRecon.java source file demonstrates how to perform reconciliation on a service immediately.

This example performs a dual job, of adding a new reconciliation unit and then running reconciliation with this new unit. Details on how to run reconciliation using an existing reconciliation unit, have been documented in the example source file.

Execute the accompanying runRecon.sh or runRecon.bat file using the following command syntax and argument list:

Windows Usage:

usage: runRecon -[argument] ? "[value]"

-serviceprofile      Profile Name of the Service to run recon (e.g., WinLocalProfile)
-servicefilter       Ldap Filter to search for a Service instance to run recon
-month               Month to run recon, Valid values 1-12, -1 indicates Monthly
-day                 Day to run recon. Valid values 1-31, -1 indicates Daily.
-dayofweek           Day of week to run recon. Valid values 1-7.(1 = Sunday, 2 = Monday,..)

NOTE: Either day or dayofweek is mandatory. If both are specified, then dayofweek will be ignored

-hour                Hour to run recon, Valid values 0-23, -1 indicates Hourly.
-minute              Minute to run recon, Valid values 0-59
-[reconfilter]       Ldap Filter to reconcile accounts
-[lockservice]       Specifies if the Service needs to be locked during recon, default value = "true"
-[maxduration]       Maximum duration(in minutes) for recon process to run (default value 600 minutes)
-[reconcallback]     If "true" then class implementing IReconCompleteCallback interface whose                      'onReconComplete()' method gets executed after completion of scheduled recon                            process, default value="false"
-[excludeattributes] Attribute(s) separated by comma to be excluded during reconciliation

Arguments enclosed in [] are optional

Example: runRecon -serviceprofile?WinLocalProfile -servicefilter?"(erservicename=WinLocal)"
-reconfilter?"(eruid=a*)" -excludeattributes?"erntpasswordneverexpires,description"
-maxduration?10 -month?10 -day?26 -hour?10 -minute?10 -reconcallback?"true"

Example: runRecon -serviceprofile?WinLocalProfile -servicefilter?"(erservicename=WinLocal)"
-reconfilter?"(eruid=a*)" -excludeattributes?"erntpasswordneverexpires,description"
-maxduration?10 -month?10 -dayofweek?1 -hour?10 -minute?10 -reconcallback?"true"


NOTE: If negative value -1 needs to be entered for month,day or hour, then change the StringTokenizer to '+' instead of '-' in function RunRecon.parseArgs() to identify the arguments prefixed with '+'


Get all attribute names available for reconciliation for a service.

The GetAvailableReconAttributes.java source file demonstrates how to get attributes available for reconciliation for a given service.

Execute the accompanying getAvailableReconAttributes.sh or getAvailableReconAttributes.bat file using the following command syntax and argument list:

Windows Usage:

usage: getAvailableReconAttributes -[argument] ? "[value]"

-serviceprofile      Profile Name of the Service (e.g., WinLocalProfile)
-servicefilter       Ldap Filter to search for a Service instance

Example: getAvailableReconAttributes -serviceprofile?WinLocalProfile -servicefilter?"(erservicename=WinLocal)"


To check if filtered reconciliation is supported for a service.

The IsFilterSupported.java source file demonstrates how to check if LDAP filter is supported for a service.

Execute the accompanying isFilterSupported.sh or isFilterSupported.bat file using the following command syntax and argument list:

Windows Usage:

usage: isFilterSupported -[argument] ? "[value]"

-serviceprofile      Profile Name of the Service (e.g., WinLocalProfile)
-servicefilter       Ldap Filter to search for a Service instance

Example: isFilterSupported -serviceprofile?WinLocalProfile -servicefilter?"(erservicename=WinLocal)"


Retrieval and Listing of all Reconciliation Units for a service.

The GetReconUnits.java source file demonstrates how to get recon units.

Execute the accompanying getReconUnits.sh or getReconUnits.bat file using the following command syntax and argument list:

Windows Usage:

usage: getReconUnits -[argument] ? "[value]"

-serviceprofile      Profile Name of the Service (e.g., WinLocalProfile)
-servicefilter       Ldap Filter to search for a Service instance

Example: getReconUnits -serviceprofile?WinLocalProfile -servicefilter?"(erservicename=WinLocal)"


Setting reconciliation related parameters for a service.

These parameters are common for all reconciliation units configured for the service and take affect only during reconciliation on a service.
The SetServiceReconParams.java source file demonstrates how to set recon params.

Execute the accompanying setServiceReconParams.sh or setServiceReconParams.bat file using the following command syntax and argument list:

Windows Usage:

usage: setServiceReconParams -[argument] ? "[value]"

-serviceprofile              Profile Name of the Service (e.g., WinLocalProfile)
-servicefilter               Ldap Filter to search for a Service instance
-checkpolicy                 If policy needs to be checked.
-[constraintviolationaction] String to set constraint violation action
-[disallowedaction]          String to set disallowed action

Arguments enclosed in [] are optional

Example: setServiceReconParams -serviceprofile?WinLocalProfile -servicefilter?"(erservicename=WinLocal)"