Chapter 37 Scripted Host

The 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.

Adapter Details

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:

Installing the Scripted Host Resource Adapter

1. 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

2. 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: habase.jar hacp.jar ha3270.jar hassl.jar hodbase.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.  RWebSDK.jar wrqtls12.jar profile.jaw Contact Sun Professional Services about getting this product.

3. Add the following definitions to the Waveset.properties file to define which service manages the terminal session:

   serverSettings.serverId.mainframeSessionType=Value serverSettings.default.mainframeSessionType=Value

   Value can be set as follows:

   • 1, which indicates IBM Host On-Demand (HOD)

     • 3, which indicates Attachmate WRQ

       If these properties are not explicitly set, then Identity Manager attempts to use WRQ first then HOD.

4. 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.

5. 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 can be replaced with a newer version from Mozilla.

6. Restart your application server so that the modifications to the Waveset.properties file can take effect.

7. See Chapter 53, 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

• Specifying Resource Actions

• SSL Configuration

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:

1. Loads the JavaScript from the ResourceAction corresponding to the current provisioning action.

2. Prepares the necessary Java input objects to make available to the JavaScript.

3. Invokes the JavaScript.

4. Processes the result returned (or exceptions and errors) from the JavaScript.

   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:

   Action	Description	Required?
   create	Create a new user.	No, but if not provided, users cannot be created.
   delete	Delete an existing user.	No, but if not provided, users cannot be deleted.
   disable	Disable an existing user.	No, but if not provided, users cannot be disabled.
   enable	Enable an existing user.	No, but if not provided, users cannot be enabled.
   getAccountIterator	Return an object used to perform iteration of existing users.	No, but if neither getAccountIterator nor listAll is provided, account iteration cannot be performed.
   getUser	Fetch attributes for an existing user.	Yes.
   login	Login to application.	Yes.
   logoff	Logoff application.	Yes.
   listAll	Return a list of existing user IDs.	No, but if neither getAccountIterator nor listAll is provided, account iteration cannot be performed.
   update	Update attributes for an existing user.	No, but if not provided, users cannot be updated.

   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:

   • Context. Describes the set of entries available in the actionContext map added into the Javascript execution context by the adapter before the script executes.

   • Error Handling. Notes describing how the script is expected to handle abnormal or error conditions

   For additional information about the actions listed in the previous table, see the following sections:

   • create Action

   • delete Action

   • disable Action

   • enable Action

   • getAccountIterator Action

   • getUser Action

   • listAll Action

   • login Action

   • logoff Action

   • update Action

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:

Key	Value Type	Value Description
hostAccess	com.waveset.adapter.HostAccess	Provides 3270 emulation access to a mainframe.
adapter	com.waveset.object.ScriptedHostResourceAdapter	Adapter instance.
action	java.lang.String	The string create.
id	java.lang.String	Account ID of the user to create.
password	java.lang.String	If present, this is the decrypted password for the new user.
attributes	java.lang.Map	Map of attributes to set for the new user. The key identifies the attribute to set, and the value is the decrypted value to which the attribute should be set.
errors	java.util.List	This is initially an empty list. The script must add java.lang.String objects to this list if any errors are found during processing.
trace	com.waveset.adapter.Trace	An object used to trace execution. Scripts can use methods of this class to make itself “debuggable” in a customer environment.

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:

Key	Value Type	Value Description
id	java.lang.String	Account ID of the user to delete.
hostAccess	com.waveset.adapter.HostAccess	Provides 3270 emulation access to a mainframe.
adapter	com.waveset.object.ScriptedHostResourceAdapter	Adapter instance
action	java.lang.String	The string delete.
trace	com.waveset.adapter.Trace	An object used to trace execution. Scripts can use methods of this class to make itself “debuggable” in a customer environment.
errors	java.util.List	This is initially an empty list. The script must add java.lang.String objects to this list if any errors are found during processing.

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:

Key	Value Type	Value Description
hostAccess	com.waveset.adapter.HostAccess	Provides 3270 emulation access to a mainframe.
action	java.lang.String	The string disable.
id	java.lang.String	The account ID to disable
errors	java.util.List	This is initially an empty list. The script must add java.lang.String objects to this list if any errors are found during processing.
trace	com.waveset.adapter.Trace	An object used to trace execution. Scripts can use methods of this class to make itself “debuggable” in a customer environment.

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:

Key	Value Type	Value Description
hostAccess	com.waveset.adapter.HostAccess	Provides 3270 emulation access to a mainframe.
action	java.lang.String	The string enable.
id	java.lang.String	Account ID to enable.
errors	java.util.List	This is initially an empty list. The script must add java.lang.String objects to this list if any errors are found during processing.
trace	com.waveset.adapter.Trace	An object used to trace execution. Scripts can use methods of this class to make itself “debuggable” in a customer environment.

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:

Key	Value Type	Value Description
hostAccess	com.waveset.adapter.HostAccess	Provides 3270 emulation access to a mainframe.
adapter	com.waveset.object.ScriptedHostResourceAdapter	Adapter instance
action	java.lang.String	The string getAccountIterator.
trace	com.waveset.adapter.Trace	An object used to trace execution. Scripts can use methods of this class to make itself “debuggable” in a customer environment.

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:

• A string of screens or responses from which the adapter can parse the user attributes for a given user.

• A map of user attributes for a given user.

The getUser action must be defined.

Context

The actionContext map will contain the following entries:

Key	Value Type	Value Description
hostAccess	com.waveset.adapter.HostAccess	Provides 3270 emulation access to a mainframe.
adapter	com.waveset.object.ScriptedHostResourceAdapter	Adapter instance
action	java.lang.String	The string getUser.
attrsToGet	java.util.List	List of strings identifying the user attributes to be fetch. This list is derived from the right-hand side of the schema map.
id	java.lang.String	Account ID of the user to fetch
errors	java.util.List	This is initially an empty list. The script must add java.lang.String objects to this list if any errors are found during processing.
trace	com.waveset.adapter.Trace	An object used to trace execution. Scripts can use methods of this class to make itself “debuggable” in a customer environment.
result	java.util.Map	The script adds entries to the map to return user attributes. See the entry table below.

The result map is expected to be populated by the script with the following entries:

Key	Value Type	Value Description
text	String	Contains the text to be parsed for the user attributes. This may be the contents of one or more screens or responses.  The user attributes will be extracted from this string later using the AttrParse object named in the attrParse entry of this map. Do not put this entry into the map if no matching user is found. Do not add this field to the map. Populate the attrMap map instead.
attrParse	String	Name of an AttrParse object which will be used by the adapter to parse user attributes from the string found in the text entry of this map. Set this entry only in combination with setting the text entry.
attrMap	java.util.Map	If the script is capable of directly retrieving the user attributes, then the script can set this entry with a map of the user attributes. Note that this attrMap entry is respected by the adapter only if the text entry of this map is not present.

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:

Key	Value Type	Value Description
hostAccess	com.waveset.adapter.HostAccess	Provides 3270 emulation access to a mainframe.
adapter	com.waveset.object.ScriptedHostResourceAdapter	Adapter instance
action	java.lang.String	The string listAll.
resultList	java.util.List	The script adds entries to this list. Each item added to the list by the script should be a string corresponding to a host account ID.
errors	java.util.List	This is initially an empty list. The script must add java.lang.String objects to this list if any errors are found during processing.
trace	com.waveset.adapter.Trace	An object used to trace execution. Scripts can use methods of this class to make itself “debuggable” in a customer environment.

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:

Key	Value Type	Value Description
hostAccess	com.waveset.adapter.HostAccess	Provides 3270 emulation access to a mainframe.
action	java.lang.String	The string login.
user	java.lang.String	User name of the host application admin user.
password	com.waveset.util.EncryptedData	Encrypted object that stores the password of the host application admin user. Use decryptToString() to convert to plain text.
errors	java.util.List	This is initially an empty list. The script must add java.lang.String objects to this list if any errors are found during processing.
trace	com.waveset.adapter.Trace	An object used to trace execution. Scripts can use methods of this class to make itself “debuggable” in a customer environment.

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:

Key	Value Type	Value Description
hostAccess	com.waveset.adapter.HostAccess	Provides 3270 emulation access to a mainframe.
action	java.lang.String	The string logoff.
errors	java.util.List	This is initially an empty list. The script must add java.lang.String objects to this list if any errors are found during processing.
trace	com.waveset.adapter.Trace	An object used to trace execution. Scripts can use methods of this class to make itself “debuggable” in a customer environment.

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:

Key	Value Type	Value Description
hostAccess	com.waveset.adapter.HostAccess	Provides 3270 emulation access to a mainframe.
adapter	com.waveset.object.ScriptedHostResourceAdapter	Adapter instance
action	java.lang.String	The string update.
id	java.lang.String	Account ID of the user to modify
password	java.lang.String	If present, this is the new decrypted password for the user.
attributes	java.lang.Map	Map of attributes to update on the existing user. The key identifies the attribute to set, and the value is the decrypted value to which the attribute should be set.
errors	java.util.List	This is initially an empty list. The script must add java.lang.String objects to this list if any errors are found during processing.
trace	com.waveset.adapter.Trace	An object used to trace execution. Scripts can use methods of this class to make itself “debuggable” in a customer environment.

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 Chapter 53, 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	Import directly from resource Reconciliation

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:

• com.waveset.adapter.ScriptedHostResourceAdapter

• com.waveset.adapter.HostAccess

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”);