None
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 Waveset 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 Waveset installation.
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 Waveset attempts to use WRQ first then HOD.
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 Waveset 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.
Restart your application server so that the modifications to the Waveset.properties file can take effect.
See Chapter 54, Mainframe Connectivity for information about configuring SSL connections to the resource.
This section provides information related to using the Scripted Host resource adapter, which is organized into the following sections:
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.
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:
Loads the JavaScript from the ResourceAction corresponding to the current provisioning action.
Prepares the necessary Java input objects to make available to the JavaScript.
Invokes the JavaScript.
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:
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
Waveset uses TN3270 connections to communicate with the resource.
See Chapter 54, Mainframe Connectivity for information about setting up an SSL connection to a RACF resource.
This section provides information about supported connections and privilege requirements.
Waveset uses TN3270 to communicate with the Scripted Host adapter.
The Waveset administrators that connect to the host application must be assigned sufficient privileges to create and manage users within the host application.
The following table summarizes the provisioning capabilities of this adapter.
The Scripted Host adapter does not provide default account attributes, because the account attributes will vary, depending on the host application being managed.
Not supported
$accountId$
None
Use the Waveset 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”);