![]() | |
Sun Java System Identity Manager 6.0 Resources Reference 2005Q4M3 |
3
Adding Actions to Resources
This chapter describes how to create and implement actions on UNIX, Windows NT, and Windows Active Directory resources in Sun Java System Identity Manager.
What are Actions?Actions are scripts that run within the context of a managed resource, if native support exists for scripted actions. For example, on a system with a UNIX operating system, actions are sequences of UNIX shell commands. In Microsoft Windows environments, actions are DOS-style console commands that can execute within the CMD console. Actions reside within Identity Manager repository as objects. In mainframe environments, actions are Javascript scripts that are capable of sending and receiving keystrokes and commands to and from the mainframe.
Use actions to perform work that is not performed directly against the resource account object but that is instead performed before or after that resource account is created, updated, or deleted. Resource actions support copying files to a new user’s directory, updating the SUDOers file on UNIX for the user after they have been created, or other native activities. You could perform this type of work by using a custom resource adapter. However, it is simpler to deploy a resource adapter with actions than to deploy a custom resource adapter.
Three types of results messages are associated with actions:
Supported ProcessesThe following processes support before and after actions:
Supported ResourcesYou can add actions to the following resources:
Refer to the individual adapter sections in this book for a list of supported versions.
Defining ActionsTo create a new resource action, you must
Creating the Action File
To create an action, you must create a file with the following text:
<ResourceAction name="Name">
<ResTypeAction restype="ResourceType" timeout="Milliseconds">
<act>
...
</act>
</ResTypeAction>
</ResourceAction>
where:
For example, the following XML defines an action for the Solaris resource:
<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE Waveset PUBLIC 'waveset.dtd' 'waveset.dtd'>
<Waveset><ResourceAction name='after-create'>
<ResTypeAction restype='Solaris' timeout='60000'>
<act>
#!/bin/ksh
echo "$WSUSER_accountId says Hello World!"
# exit $DISPLAY_INFO_CODE if there is not a failure, but you want
# the output to be propagated to the UI
#exit 0
exit $DISPLAY_INFO_CODE
</act>
</ResTypeAction>
</ResourceAction>
</Waveset>
Note The code contained within the <act> elements is the same as seen in a UNIX script (ksh or sh) or a Windows batch script.
Environment variables are exported and available to actions. These comprise any one of the schema-mapped attributes that have values on the user (defined in the resource schema map in the Identity System Resource Attribute column), prefixed by WSUSER_. For instance, the preceding example uses the environment variable WSUSER_AccountId, formed by preceding the AccountId attribute defined in the Solaris resource schema map by WSUSER_. These variables should be identified as environment variables within the respective shell, so that in Solaris, the variable name is preceded by $ (dollar sign).
Notes:
- If you change any variable names in the Identity Manager Resource Attribute column on the schema map, you must change the names in this object as well.
- Because the actions are included in an XML expression, some characters must be escaped. Escape these characters as follows:
& (ampersand): &
< (less than): <
- On UNIX resources, spaces in attribute names are replaced with _ (underscore). On Windows NT and Active Directory resources, spaces are maintained.
- Multi-valued attributes consist of a comma-separated list, as in:
WSUSER_groups=staff,admin,users
- Gateway-based adapters use a pipe-delimited list for multi-valued attributes. For example:
WSUSER_NotesGroups=group1|group2|group3
- On Windows NT and Active Directory resources, actions are run using the Windows command interpreter cmd.exe with extensions enabled.
Actions that run before a user operation must return a zero value. Otherwise, the operation is aborted.
- On mainframe adapters (ACF2, Natural, RACF, and Top Secret), actions are interpreted as Javascript. The JavaScript should be written assuming the availability of the following global variables:
- hostAccess — an instance of com.waveset.adapter.HostAccess. It is used for sending and receiving keystrokes and commands to/from the mainframe.
- identity — (String) Contains the accountId for the user on the resource
- userAttrs — Instance of java.util.Map containing values for each of the Resource User Attributes needed by the action
- out — Instance of java.io.PrintStream. If the Javascript writes to this stream (for example, out.print(“Hello”) ), the contents will be traced, and will be shown in the UI results displayed for resource actions.
- err — This is an instance of java.io.PrintStream. If the Javascript writes to this stream (for example,. err.print(“Error”)), the contents will be traced, and will be shown in the UI results displayed for resource actions.
- A Javascript is assumed to have completed successfully unless it throws an exception.
Loading the Action File into Identity Manager
Follow these steps to import the action into Identity Manager:
Implementing ActionsAfter you have defined an action, follow these steps to implement it:
Step 1: Define Identity Manager User Form Fields
Create user form fields to assign an action that will run before or after a user operation:
In this example, the field defines an action named after-create that runs after a user create operation:
<Field name='global.create after action'>
<Expansion>
<s>after-create</s>
</Expansion>
</Field>The field name is formatted as:
{create|update|delete} {before|after} action
For detailed information about working with forms in Identity Manager, refer to the chapter titled Identity Manager Forms.
Step 2: Add Schema Map Entries
Add an entry to the schema map for the resources on which you want the action to run. To do this:
- Click Resources on the Identity Manager menu bar, and then select a resource.
- On the Edit Resource page, click Edit Schema.
- On the schema map, click New Row to add a row to the schema map.
- In the Identity System User Attribute column, enter create after action.
- Enter IGNORE_ATTR in the Resource User Attribute column. The IGNORE_ATTR entry causes the attribute to be ignored during normal account attribute processing.
- Click Save.
Windows NT ExamplesThis section provides examples of actions that you can run on a Windows NT resource after a resource adapter performs the following operations:
Example 1: Action that Follows Creation of a User
This procedure shows how to include an action that will run after the creation of a new user on the WIndows NT resource.
- Enter create after action in the Identity Manager User Attribute column of the Windows NT schema map.
- In the Attribute Type column, select string.
- In the Resource User Attribute column, enter IGNORE_ATTR. Leave the Required, Audit, Read Only, and Write Only columns unchecked.
- Add the following code to the user form you are using to create or edit users:
<Field name='accounts[NT].create after action'>
<Expansion>
<s>AfterCreate</s>
</Expansion>
</Field>
- Create the following XML file and import it into Identity Manager. (Change the file paths according to your environment.)
<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE Waveset PUBLIC 'waveset.dtd' 'waveset.dtd'>
<Waveset>
<ResourceAction name='AfterCreate'>
<ResTypeAction restype='Windows NT' timeout='6000'>
<act>
echo create >> C:\Temp\%WSUSER_accountId%.txt
exit
</act>
</ResTypeAction>
</ResourceAction>
</Waveset>
Example 2: Action that Follows the Update or Edit of a User Account
This procedure shows how to include an action that will run after the update or edit of a user on a Windows NT resource.
- Enter update after action in the Identity Manager User Attribute column of the Windows NT schema map.
- In the Attribute Type column, select string.
- In the Resource User Attribute column, enter IGNORE_ATTR. Leave the Required, Audit, Read Only, and Write Only columns unchecked.
- Add the following fields to the user form that you are using to create and edit users:
<Field name='accounts[NT].update after action'>
<Expansion>
<s>AfterUpdate</s>
</Expansion>
</Field>
- Create the following XML file and import it into Identity Manager. (Change file paths according to your environment.)
<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE Waveset PUBLIC 'waveset.dtd' 'waveset.dtd'>
<Waveset>
<ResourceAction name='AfterUpdate'>
<ResTypeAction restype='Windows NT' timeout='6000'>
<act>
echo update >> C:\Temp\%WSUSER_accountId%.txt
exit
</act>
</ResTypeAction>
</ResourceAction>
</Waveset>
Example 3: Action that Follows the Deletion of a User
This procedure shows how to include an action that will run after the deletion of a user on the Windows NT resource.
- Enter delete after action in the Identity Manager User Attribute column of the Windows NT schema map.
- In the Attribute Type column, select string.
- In the Resource User Attribute column, enter IGNORE_ATTR. Leave the Required, Audit, Read Only, and Write Only columns unchecked.
- Add this to the Deprovision Form user form after the </Include> tag:
<Field name= 'accounts[NT].attributes.delete after action'>
<Expansion>
<s>AfterDelete</s>
</Expansion>
</Field>
- Create the following XML file and import into Identity Manager. (Change file paths according to your environment.)
<?xml version='1.0' encoding='UTF-8'?> <!DOCTYPE Waveset PUBLIC 'waveset.dtd' 'waveset.dtd'>
<Waveset>
<ResourceAction name='AfterDelete'>
<ResTypeAction restype='Windows NT' timeout='6000'>
<act>
echo delete >> C:\Temp\%WSUSER_accountId%.txt
exit
</act>
</ResTypeAction>
</ResourceAction>
</Waveset>
- Edit the XML for the NT resource and add information to the “delete after action” schema mapping. Here is an example of a complete schema mapping for this resource with the new additions. (You will be adding the views-related information.)
<AccountAttributeType id='12' name='delete after action' syntax='string' mapName='IGNORE_ATTR' mapType='string'>
<Views>
<String>Delete</String>
</Views>
</AccountAttributeType>
Domino ExampleDomino resources support before and after actions.
There are currently two supported types of actions: LotusScript and cmd shell. Any operation action can have any number of actions that will be executed.
The following examples demonstrate the use of LotusScript and cmd shell resource actions:
LotusScript Example
<ResourceAction name='iterateAttributes' createDate='1083868010032'>
<ResTypeAction restype='Domino Gateway' actionType='lotusscript'>
<act>
Sub Initialize
Main
End Sub
Sub Main
Dim session As New NotesSession
Dim doc As NotesDocument
Set doc = session.DocumentContext
Forall i In doc.Items
Dim attrVal As Variant
attrVal = doc.GetItemValue(i.Name)
End Forall
End Sub
</act>
</ResTypeAction>
</ResourceAction>
cmd shell Example
<ResourceAction name='getDirectoryContents' createDate='1083868010032'>
<ResTypeAction restype='Domino Gateway'>
<act>dir</act>
</ResTypeAction>
</ResourceAction>
Note A null actionType defaults to cmd script type.
Running LotusScript
On Domino, the execution of LotusScript is handled by an agent attached to a database. The Domino adapter will execute LotusScript in any one of the following ways:
The following customized account attributes can be used with LotusScript. If any of these attributes are to be used, add the attribute on the Domino Gateway schema map. Specify IGNORE_ATTR as the value in the Resource User Attribute column.
- agentName - Name of the agent to execute. This attribute must be specified, or an error will be returned.
- agentServer - Location of the database where the agent has been installed, and where to run the agent. This attribute defaults to the value specified in the Registration Server Machine resource parameter (REG_SERVER) if not present.
- agentDBName - Database name where the agent can be found. This attribute defaults to the value specified in the Names Database resource parameter (NAB) on the resource.
- agentCreate - Flag that indicates whether the adapter should create a new agent, if the named agent is not found. This attribute defaults to false. A non-NULL value enables this flag.
Note If you specify agentCreate you must also specify LotusScript to be executed.
Arguments to LotusScript
Agents arguments will be given in a note handle to LotusScript via a special property from the back-end NotesSession class. It can be defined as follows:
NotesDocument = NotesSession.DocumentContext
The NotesDocument can be instantiated by the action script routine and its field values can be read in as parameters to the LotusScript subroutine.
The following is a Lotus script example that gets the name a value of any arguments defined in the document.
Dim session As New NotesSession
Dim doc As NotesDocument
Set doc = session.DocumentContext
Forall i In doc.Items
Dim attrVal As Variant
attrVal = doc.GetItemValue(i.Name)
Print(" Attribute Name: " + i.Name + " Value: " + attrVal(0))
End Forall
All of the attributes defined during the action call will be put into the NotesDocument prefixed with WSUSER_, just as in the case of the NT actions.
Running cmd Shell
Actions are run using the Windows command interpreter cmd.exe with extensions enabled. Actions that run before a user operation must return a zero value. Otherwise, the operation is aborted.
Arguments to the cmd Shell
As with NT/ADSI cmd actions, the environment variables are exported and available to actions. These comprise any one of the schema-mapped attributes that have values on the user (defined in the resource schema map in the Identity Manager User Attribute column), prefixed by WSUSER_.
Multi-valued attributes consist of a pipe-separated list, as in:
WSUSER_groups=staff|admin|users
Extending ViewsYou can add additional attributes to a view. All attributes must be registered.
The user attributes that are available to the different provisioning activities in Identity Manager are limited to those necessary to complete the action. For example, when editing a user, all possible user attributes are retrieved form the assigned resources and available for update. In contrast, the Change Password process needs only a subset of attributes to perform the request.
Attribute Registration
Attributes can be registered in one of two locations:
You can register different attributes for different views. For example, you can register the lock attribute for the Password view and the firstname attribute for the Rename view or the resource action for the Enable, Disable, or Delete view.
Note In the case of before or after actions, you must extend the view for any process except the create or update user process. For information on extending a view, see Identity Manager Views.
Global Registration
To make global registrations, add an attribute in the System Configuration object with this path:
updatableAttributes.ViewName.ResourceTypeName
where ViewName is one of Password, Reset, Enable, Disable, Rename, or Delete, and ResourceTypeName is the name of the resource type. The type name all is reserved for registrations that apply to all resources.
The value of this attribute must be a List of <String>s. The strings are names of the attributes you want to update. The following example registers the attribute named delete before action in the Delete view for all resources.
<Attribute name='updatableAttributes'>
<Object>
<Attribute name='Delete'>
<Object>
<Attribute name='all'>
<List>
<String>delete before action</String>
</List>
</Attribute>
</Object>
</Attribute>
<Attribute name='Enable'>
<Object>
<Attribute name='all'>
<List>
<String>enable before action</String>
</List>
</Attribute>
</Object>
</Attribute>
</Object>
</Attribute>
Resource-Specific Registration
To make resource-specific registrations, modify the resource object from the Identity Manager Debug page and insert a <Views> sub-element in the AccountAttributeType element. <Views> must contain a list of strings whose values are the names of the views in which this attribute can be updated.
<AccountAttributeType name='lastname' mapName='sn' mapType='string'>
<Views>
<String>Rename</String>
</Views>
</AccountAttributeType>
In the view, attributes you want to modify are placed within this object:
resourceAccounts.currentResourceAccounts[ResourceTypeName].attributes
Example:
<Field name= 'resourceAccounts.currentResourceAccounts[OS400ResourceName].attribute s.delete before action' hidden='true'>
<Expansion>
<s>os400BeforeDeleteAction</s>
</Expansion>
</Field>