|
| |
| Sun[TM] Identity Manager 8.0 Resources Reference | |
Scripted HostThe Scripted Host resource adapter supports management of application user accounts on an OS/390 mainframe. The adapter manages host applications over a TN3270 emulator session.
This adapter is a general purpose adapter, and is therefore highly configurable. The adapter makes no assumptions about the host application being managed, and instead relies on calling out to a set of customer-supplied scripts to perform the interactions with the host application.
The Scripted Host resource adapter is defined in the com.waveset.adapter.ScriptedHostResourceAdapter class.
Resource Configuration Notes
None
Identity Manager Installation Notes
The Scripted Host resource adapter is a custom adapter. You must perform the following steps to complete the installation process:
- To add the Scripted Host resource to the Identity Manager resources list, you must add the following value in the Custom Resources section of the Configure Managed Resources page.
com.waveset.adapter.ScriptedHostResourceAdapter
- Copy the appropriate JAR files to the WEB-INF/lib directory of your Identity Manager installation.
Connection Manager
JAR Files
Host On Demand
The IBM Host Access Class Library (HACL) manages connections to the mainframe. The recommended JAR file containing HACL is habeans.jar. It is installed with the HOD Toolkit (or Host Access Toolkit) that comes with HOD. The supported versions of HACL are in HOD V7.0, V8.0, V9.0, and V10.
However, if the toolkit installation is not available, the HOD installation contains the following JAR files that can be used in place of the habeans.jar:
See http://www.ibm.com/software/webservers/hostondemand/ for more information.
Attachmate WRQ
The Attachmate 3270 Mainframe Adapter for Sun product contains the files needed to manage connections to the mainframe.
Contact Sun Professional Services about getting this product.
- Add the following definitions to the Waveset.properties file to define which service manages the terminal session:
serverSettings.serverId.mainframeSessionType=Value
serverSettings.default.mainframeSessionType=ValueValue can be set as follows:
- When the Attachmate libraries are installed into a WebSphere or WebLogic application server, add the property com.wrq.profile.dir=LibraryDirectory to the WebSphere/AppServer/configuration/config.ini or startWeblogic.sh file.
This allows the Attachmate code to find the licensing file.
- The Scripted Host adapter requires customer-supplied Javascripts. These scripts must be compatible with Mozilla Rhino. Mozilla Rhino v1_5R2 ships with Identity Manager and is located at $WSHOME/WEB-INF/lib/javascript.jar.
If you need improved Javascript error reporting capability, the latest version of Mozilla Rhino (http://www.mozilla.org/rhino/) offers great improvement in the messages generated for syntax errors and other errors. The default javascript.jar may be replaced with a newer version from Mozilla.
- Restart your application server so that the modifications to the Waveset.properties file can take effect.
- See Mainframe Connectivity for information about configuring SSL connections to the resource.
Usage Notes
This section provides information related to using the Scripted Host resource adapter, which is organized into the following sections:
Administrators
Host resource adapters do not enforce maximum connections for an affinity administrator across multiple host resources connecting to the same host. Instead, the adapter enforces maximum connections for affinity administrators within each host resource.
If you have multiple host resources managing the same system, and they are currently configured to use the same administrator accounts, you might have to update those resources to ensure that the same administrator is not trying to perform multiple actions on the resource simultaneously.
Specifying Resource Actions
The Resource Parameters page of the resource wizard for the Scripted Host adapter contains a set of text boxes that allow you to specify a resource action for various provisioning actions, such as login, create, delete, and iterate. These fields refer to ResourceAction objects that contain Rhino Javascript and loaded into the repository.
At run-time, the adapter does the following:
The $WSHOME/sample/ScriptedHost/ScreenSampleActions.xml file contains a set of sample resource action definitions that could be used to provision users to a theoretical screen-based host application. You will need to customize these definitions to your application.
The Scripted Host adapter supports end-user scripting for the following provisioning actions:
Every action script receives an actionContext map, as defined by the java.util.Map class. The possible contents of the map vary for each action. The following sections describe each action, and provide the following information about the action:
For additional information about the actions listed in the previous table, see the following sections:
create Action
The create action creates a user in the host application. If the create action is not defined, then new users cannot be added to the host application.
Context
The actionContext map will contain the following entries:
Error Handling
If any application-specific errors are found in a screen or response, the script should add appropriate strings to the errors key. Determining that an error has occurred may require a string search for various known error strings.
The presence of any items in the errors List is considered a creation failure. Additionally, any throw from within the script is considered a creation failure.
delete Action
The delete action deletes a specified user from the host application. If no delete action is defined, then users cannot be deleted from the host application.
Context
The actionContext map will contain the following entries:
Error Handling
If any application-specific errors are found in a screen or response, the script should add appropriate strings to the errors key. Determining that an error has occurred may require a string search for various known error strings.
The presence of any items in the errors List is considered a deletion failure. Additionally, any throw from within the script is considered a deletion failure.
disable Action
The disable action disables an existing user within the host application. If this action is not defined, then users on the host application cannot be disabled.
Context
The actionContext map will contain the following entries:
Error Handling
If any application-specific errors are found in a screen or response, the script should add appropriate strings to the errors key. Determining that an error has occurred may require a string search for various known error strings.
The presence of any items in the errors List is considered a disablement failure. Additionally, any throw from within the script is considered a disablement failure.
enable Action
The enable action enables an existing user within the host application. If this action is not defined, then users on the host application cannot be enabled.
Context
The actionContext map will contain the following entries:
Error Handling
If any application-specific errors are found in a screen or response, the script should add appropriate strings to the errors key. Determining that an error has occurred may require a string search for various known error strings.
The presence of any items in the errors List is considered an enablement failure. Additionally, any throw from within the script is considered an enablement failure.
getAccountIterator Action
The getAccountIterator action returns an object used to perform iteration of existing users.
If you wish to perform account iteration (reconciliation, Load From Resource), either this action or the listAll action must be defined.
If the getAccountIterator action is not defined, then account iteration will be performed by calling listAll, and then calling getUser for each ID in the list from listAll.
If the getAccountIterator action is not defined and the listAll action is not defined, then account iteration is not supported.
Inputs
The actionContext map will contain the following entries:
Return Value
The script must return a Java object that implements the Java interface com.waveset.adapter.ScriptedHostAccessAdapter.ObjectIterator.
public interface ObjectIterator {
public boolean hasNext();
public void next(java.util.Map nextObj);
public void close();
}The nextObj Map argument to the next() method is to be populated by the script in the same manner as the result entry discussed in the getUser action.
Error Handling
Any throw from within the script is considered an iteration failure.
Any thrown exceptions encountered while invoking methods on the Java object returned from the script are also considered iteration failures.
getUser Action
The getUser action retrieves one of the following from the host application:
The getUser action must be defined.
Context
The actionContext map will contain the following entries:
The result map is expected to be populated by the script with the following entries:
Error Handling
If there is no matching user found, then the result map should be left empty.
If any application-specific errors are found in a screen or response, the script should add appropriate strings to the errors key. Determining that an error has occurred may require a string search for various known error strings.
The presence of any items in the errors List is considered a retrieval failure. Additionally, any throw from within the script is considered a retrieval failure.
listAll Action
The listAll action retrieves a list of user IDs found for the host application.
If the listAll action is not defined, then you cannot call the FormUtil.listResourceObjects methods for this resource instance from a form.
If the listAll action is not defined and the getAccountIterator action is not defined, then account iteration (reconciliation, Load From Resource) is not supported.
Context
The actionContext map will contain the following entries:
Error Handling
If any application-specific errors are found in a screen or response, the script should add appropriate strings to the errors key. Determining that an error has occurred may require a string search for various known error strings.
The presence of any items in the errors List is considered a retrieval failure. Additionally, any throw from within the script is considered a retrieval failure.
login Action
The login action negotiates an authenticated session with the host required to manage users in the custom host application. This action must be defined.
Context
The actionContext map will contain the following entries:
Error Handling
If any application-specific errors are found in a screen or response, the script should add appropriate strings to the errors key. Determining that an error has occurred may require a string search for various known error strings.
The presence of any items in the errors List is considered a login failure. Additionally, any throw from within the script is considered a login failure.
logoff Action
The logoff action performs a disconnect from the host. This is called when the connection is no longer required. This action must be defined.
Context
The actionContext map will contain the following entries:
Error Handling
If any application-specific errors are found in a screen or response, the script should add appropriate strings to the errors key. Determining that an error has occurred may require a string search for various known error strings.
The presence of any items in the errors List is considered a logoff failure. Additionally, any throw from within the script is considered a logoff failure.
update Action
The update action updates a user in the host application. If the update action is not defined, then users on the host application cannot be updated.
Context
The actionContext map will contain the following entries:
Error Handling
If any application-specific errors are found in a screen or response, the script should add appropriate strings to the errors key. Determining that an error has occurred may require a string search for various known error strings.
The presence of any items in the errors List is considered an update failure. Additionally, any throw from within the script is considered an update failure.
SSL Configuration
Identity Manager uses TN3270 connections to communicate with the resource.
See Mainframe Connectivity for information about setting up an SSL connection to a RACF resource.
Security Notes
This section provides information about supported connections and privilege requirements.
Supported Connections
Identity Manager uses TN3270 to communicate with the Scripted Host adapter.
Required Administrative Privileges
The Identity Manager administrators that connect to the host application must be assigned sufficient privileges to create and manage users within the host application.
Provisioning Notes
The following table summarizes the provisioning capabilities of this adapter.
Feature
Supported?
Enable/disable account
Yes
Rename account
No
Create account
Yes
Update account
Yes
Delete account
Yes
Pass-through authentication
No
Before/after actions
Yes
Data loading methods
Account Attributes
The Scripted Host adapter does not provide default account attributes, because the account attributes will vary, depending on the host application being managed.
Resource Object Management
Not supported
Identity Template
$accountId$
Sample Forms
None
Troubleshooting
Use the Identity Manager debug pages to set trace options on the following classes:
See the Troubleshooting for the Top Secret adapter for more information about troubleshooting the HostAccess class.
There is always a com.waveset.adapter.Trace object passed in the context to the Javascripts. Enabling trace on com.waveset.adapter.ScriptedHostResourceAdapter will enable tracing in the Javascripts.
Additionally, for temporary tracing to stdout, the Javascripts can make calls to the Java System.out.println() method. For example:
java.lang.System.out.println(“Hello World”);