Using the Directory Utility
The Directory Utility is a Java application you can use to manage user, group, or session configuration information stored either in Z and I Emulator for Web or in an LDAP server. The Directory Utility enables you to add or update large numbers of users, groups, or sessions from an ASCII file, instead of individually through the Administration client. For example, you can use the utility to:
- Add, update and delete groups
- Add, update, and delete users from groups
- Add and delete sessions from users or groups
- List existing users and groups (in output files)
- List existing users and groups (in output files) as products of unique searches, using criteria with flexible wild card options
- Perform actions on list output to quickly modify users and groups
The Directory Utility uses an ASCII file that defines all groups, users, and sessions. The text file needs to be in XML format, with a .xml extension.
Running the Directory Utility | |
Using the Directory Utility GUI | |
XML file format / element descriptions | |
XML file example | |
Searching with the List function | |
Using output of the List function |
Running the Directory Utility
The Directory Utility can be run using either a graphical user interface or a command line interface.
Graphical user interface
To start the graphical user interface ...
In the Directory Utility graphical user interface enter the following fields as appropriate:
- Connection Properties
-
- User ID
- The Z and I Emulator for Web administrator's user ID.
- Password
- The Z and I Emulator for Web administrator's password.
- Host
- The Z and I Emulator for Web service manager's hostname or IP address. This field is optional. The default is localhost ( 127.0.0.1).
- Port
- The Z and I Emulator for Web service manager's port. This field is optional. The default is 8999.
- File Operations
-
- Input XML File
- The name of the XML file that contains the actions you want to perform. See
XML file format / element descriptions.
- Browse
- Click to browse for the input XML file.
- Generate HTML file for list action
- Select this option when the action in the input XML file is
list, and you want the list results displayed in an output HTML file.
This option is ignored for the add, delete, and update actions in the input XML file.
- Output HTML
- The name of the output HTML file to display the list results.
- Browse
- Click to browse for an existing output HTML file.
- Output
-
- Console
- This is the output area that displays a summary of the results of the actions in the input XML file.
- Clear
- Click to clear the Console area.
Command line interface
On Windows systems the command or script file to run the Directory Utility and sample file are located in the C:\Program Files\HCL\ZIEForWeb\lib\samples\DirUtil directory. The command file is called DirUtil.cmd and the sample text file is called sample.xml. The command or script file for other operating systems and the sample text file are located in the zieforweb\lib\samples\DirUtilCommandFiles directory. The sample text file is called Sample.xml. The command or script files are called:
- DirUtil-AIX for AIX
- DirUtil-UNIX for HP-UX, Linux, and Solaris
- DirUtil-AS400.sh for iSeries, AS/400
- DirUtil-S390 for zSeries, OS/390
To run the Directory Utility, type the following at the command line:
The order of the parameters is important. |
DirUtil-xxx filename.xml admin password [hostname] [port] [CO |
where the following are used:
- DirUtil-xxx is the Directory Utility command or script file for your operating system
- filename.xml is the file that contains the XML elements to manage users, groups and sessions. The text file must have an .xml extension, and be a valid XML file. If the text file is not in the same directory as the Directory Utility command file, you must specify the path to the file. This parameter must be present on the command line.
- admin is the Z and I Emulator for Web administrator's user ID. This parameter must be present on the command line.
- password is the Z and I Emulator for Web administrator's password. This parameter must be present on the command line.
- hostname is the Z and I Emulator for Web Service Manager's hostname or IP address. This parameter is optional. The default hostname is localhost (127.0.0.1).
- port is the Z and I Emulator for Web Service Manager's port. This parameter is optional. The default Service Manager port is 8999.
- CON | FILE determines how messages will be logged and displayed. If the command line contains the string CON, messages will go only to the console. If the command line contains the string FILE, messages will only be written to a log file. If neither string is included (the default), the messages will be written to the console and also to a log file. The name of the log file is based on the name of the XML file. If your XML filename is myxmlfile.xml, then your log file name is myxmlfile.log.
The Z and I Emulator for Web Service Manager must be running on the Z and I Emulator for Web server specified by hostname in order for the Directory Utility to update Z and I Emulator for Web or LDAP configuration information. |
For example, on AIX you could run:
DirUtil-AIX file.xml admin password myhostname 8999 CON
Using the Directory Utility GUI
The Directory Utility GUI is the GUI interface for the command line application. You can use it to manage users, groups, or the information of session configurations that is stored either in Z and I Emulator for Web or in an LDAP server. The Directory Utility GUI allows you to add or update large numbers of users, groups, or sessions from an ASCII file, instead of individually through the Administration client.
There is a sample.xml which is already provided in the DirUtil folder. The text file needs to be in XML format, with an .xml extension for the GUI to recognize the options.
Running the Directory Utility GUI
On Windows 64 bit OS, the utility can be launched with DirUtilGUI.bat which is located in the C:\Program Files\HCL\ZIEForWeb\lib\samples\DirUtil directory.
On Windows 32 bit OS, the utility can be launched with DirUtilGUI.bat which is located in the C:\Program Files (x86)\HCL\ZIEForWeb\lib\samples\DirUtil directory.
On a Unix/Linux based OS, the utility can be launched with DirUtilGUI.sh which is located in the /opt/HCL\ZIEForWeb/lib/samples/DirUtil directory.
Note:These are the default directories where ZIEWeb is installed. In case ZIEWeb is installed in a user defined directory location would be the <<ZIEWeb_INSTALL_DIRECTORY>> \lib\samples\DirUtil directory. The command or script files are called:
- DirUtilGUI.bat for Windows
- DirUtilGUI-UNIX for Linux, and Solaris
Interface of the GUI
The GUI has the User name and the Password fields where the user name and password of an administrtor are required. By default, admin is set as the user name and password is set as the password.
Host name is pre-defined as localhost and port number is pre-defined as 8999. You also can enter the desired hostname and port number in case of changes.
You need to chose the XML File that contains details about the user,the group, or the session. Your options include Add, Update, and Delete.
The checkbox Generate HTML file for List action is used to generate a list of users or groups as per the option defined in the xml file. The HTML file field is auto generated when the XML file is selected. The automatically generated html file would be named with the xml file name and placed in the same location of xml file.
Generating list of User(s) or Group(s) on the html file is valid only when the checkbox Generate HTML file for List action is checked and list of User(s) or Group(s) would be listed in the default HTML file if unchanged.
You can clear the console output by clicking the Clear button. You can also copy it to clipboard with the click of Copy button.
You can click Help to open the help content of DirUtilGUI.
Using output of the List function
Here are two examples of generating list action on the HTML file:
- User(s) List
<action type = "list"> <userlist> <userid>*</userid> </userlist> </action>
- Group(s) List
<action type = "list"> <grouplist> <groupid>*</groupid> </grouplist> </action>
XML file format / element descriptions
The descriptions of the elements below describe the format for valid XML elements that can be included in the XML file used by Directory Utility. A basic understanding of XML is assumed. Lines that begin with an "<!--" and end with "-->" are treated as comments. Elements are case sensitive.
To create or edit the XML file, you must use an ASCII editor that generates valid unicode characters. If you receive the error DIR0037 Fatal error: Invalid XML Character while using the XML file with the Directory Utility, the ASCII editor did not generate valid unicode characters. Use a different ASCII editor that does generate valid unicode characters.
<dirscript>
<action>
<group>
<groupid>
<description>
<parent>
<removeusers>
<user>
<userid>
<groupid>
<description>
<authentication>
<pw>
<nativeid>
<savepref>
<session>
<filename>
<groupid>
<userid>
<description>
<userlist>
<userid>
<groupid>
<filename>
<grouplist>
<userid>
<groupid>
<filename>
<dirscript>..</dirscript>
The root element in the XML file that contains all the other elements, and identifies the document as one that can be processed by the Directory Utility.
Attributes: none
Required elements: <action type=xxx>
Optional elements: none
<action type=xxx>..</action>
The action that is performed on the elements enclosed in the <action> element. You can have multiple action elements within the <dirscript> element. Elements placed outside either the <dirscript> element or this element in the XML file are ignored by the Directory Utility.
Values: add, delete, update, or list
Required elements: At least one of the following is required within the <action> element:
- <group>..</group>
- The group that is affected by the action. If the action is add and the group already exists, you will receive a message that the group is a duplicate.
- <user>..</user>
- The user that is affected by the action. If the action is add and the user already exists, you will receive a message that the user is a duplicate.
- <session>..</session>
- The session that is affected by the action. The session element is not valid when the action is update. If the session already exists, a new session named "1:description" is added, the same way that the Administration client adds a duplicate session.
- <userlist>..</userlist>
- Valid only if the action is list. Creates an output XML file of user-specific information. See Searching with the List function.
- <grouplist>..</grouplist>
- Valid only if the action is list. Creates an output XML file of group-specific information. See Searching with the List function.
Directory Utility does not support the <grouplist> element for LDAP. |
<group>..</group>
The enclosing element for a group.
Attributes: none
Required elements:
- <groupid>..</groupid>
- A unicode text string that identifies the group in LDAP or Z and I Emulator for
Web. If you are using Z and I Emulator for Web the
groupid
is converted to uppercase when the group is added. If you are using LDAP thegroupid
can be mixed-case.
Optional elements:
- <description>..</description>
- A unicode text string that describes the group. This element is only valid when the action type is add or update.
- <parent>..</parent>
- The parent of this group. This element is only valid when the action is add or update, and when using LDAP. If this element is not specified when the action is add, the group is added to the top level.
- <removeusers>..</removeusers>
- This element allows you to delete all the users which belong only to this group when you delete the group. This element is only valid when the action is delete, and this element is not valid when using LDAP. Valid values are Yes and No. If Yes is specified then the users in this group will be deleted when the group is deleted. If No is specified and there are users in the group, the users which belong only to this group are moved to the ZIEWeb group and the group is deleted. The Default is No. If you have many users, it may take some time for the processing of this element to complete.
<user>..</user>
The enclosing element for a user.
Attributes: none
Required elements:
- <userid>..</userid>
- The user identifier. This element is always required. If you are using Z and I
Emulator for Web the
userid
is converted to lower-case. If you are using LDAP theuserid
can be mixed-case. - <groupid>..</groupid>
- The group to which the user is being added. This element is required when the action type is "add" and ignored when the action type is delete. If you are not using LDAP you can specify multiple <groupid> elements. If you are using LDAP and you specify multiple groups, an error message is generated and the user is not added. Groups specified must exist before you can add a user to them. If the action type is update, the user is updated to have membership in this group.
Optional elements:
- <description>..</description>
- A unicode text string that describes the user.
- <authentication type=xxx>..</authentication>
- You can specify the authentication that is used for the user. Valid types are native and pw. If this element is not specified, then no authentication will be configured for the user.
- <savepref>..</savepref>
- You can specify if the user is authorized to save preferences (changes that the user might make to a host session configuration). Valid values are Yes or No. If this element is not specified the default of Yes is set for the user, so that the user is able to save preferences.
- <removegroupid>..</removegroupid>
- You can update a user so that they no longer have membership in the specified group. This element is only valid if the action type is update. You must use a valid groupid which contains this user.
<authentication type=xxx>..</authentication>
The authentication used for the user. You can use either native authentication, only if you are also using LDAP, or password authentication. No authentication will be configured for the user if this element is not specified when the action type is add, or if native is selected and you are not using LDAP.
Attributes: pw or native
Required elements:
- <nativeid>..</nativeid>
- The user ID of the user on the native operating system. This element is required and valid only when using LDAP and when the authentication type is native.
Optional elements:
- <pw>..</pw>
- The password associated with the user. This element is only valid when the authentication type is pw.
- <changepw>..</changepw>
- You can specify if the user is authorized to change their password. Valid values are Yes or No. If this element is not specified the default of Yes is set for the user, and the user is able to change their password. This element is only valid if the authentication type is pw and is ignored if the authentication type is native.
<session>..</session>
The enclosing element for a session.
Attributes: none
Required elements:
- <filename>..</filename>
- The file containing the session definition. You can create a session definition file by using the Export Session menu option from any defined Z and I Emulator for Web session. The default extension for session files is .ws. The <filename> element may contain the full path to the session file, and it is only required when adding a session.
- <description>..</description>
- A unicode text string that describes the session and is used as the session name. The <description> is required to update or delete a session. If <description> is omitted the session name will be used for the description of the file.
- <userid>..</userid>
- The user identifier for the user to which this session is being added. User IDs must already exist before the session can be added. You can include multiple <userid> elements to add this session for multiple users.
- <groupid>..</groupid>
- The group identifier for the group to which the session is being added. Groups must already exist before the session can be added. You can include multiple <groupid> elements to add a session for multiple groups.
You can specify multiple users or multiple groups in the session element, but you cannot specify both users and groups in the same session element. |
Optional elements: none
<userlist>..</userlist>
The enclosing element for a user-based search.
Attributes: none
Required elements: Not more than one of each of the following elements can be used:
- <userid>..</userid>
- The user ID to be used in the search criteria.
- <groupid>..</groupid>
- The group ID to be used in the search criteria.
If either the <userid> or the <groupid> tag is missing, Directory Utility assumes a wildcard for the element and runs the search accordingly. |
Optional elements: Use this element only once, to refer to only one file:
- <filename>..</filename>
- The file to which Directory Utility writes XML output. You must name this file with a valid XML file name.
The Directory Utility writes to a default file if you do not specify a file name. That default file is DirUtilList.xml, which resides in the zieforweb\lib\samples\DirUtil directory. Every time you do not specify an output file, the list function adds the results of your search to DirUtilList.xml. See Using output of the List function. |
<grouplist>..</grouplist>
The enclosing element for a group-based search.
Directory Utility does not support this element for LDAP. |
Attributes: none
Required elements: Not more than one of each of the following elements can be used:
- <userid>..</userid>
- The user ID to be used in the search criteria.
- <groupid>..</groupid>
- The group ID to be used in the search criteria.
If either the <userid> or the <groupid> tag is missing, Directory Utility assumes a wildcard for the element and runs the search accordingly. |
Optional elements: Use this element only once, to refer to only one file:
- <filename>..</filename>
- The file to which Directory Utility writes XML output. You must name this file with a valid XML file name.
The Directory Utility writes to a default file if you do not specify a file name. That default file is DirUtilList.xml, which resides in the zieforweb\lib\samples\DirUtil directory. Every time you do not specify an output file, the list function adds the results of your search to DirUtilList.xml. See Using output of the List function. |
XML file example
Below is an example XML file demonstrating the add and list actions. It adds three groups, adds the users to the groups, and if the sessions are exported and the comments are removed, then adds the sessions to the users and the groups. (To delete or update users, groups, or sessions, change the action type to delete or update and change the elements accordingly.) On Windows NT and Windows 2000 this sample file, called sample.xml, is located in the C:\Program Files\HCL\ZIEForWeb\lib\samples\DirUtil directory. The sample.xml text file for the other operating systems is located in the zieforweb\lib\samples\DirUtilCommandFiles directory.
This example uses the list action in its simplest form: it sends a list of all users and groups to the default XML output file of Directory Utility. To learn about more sophisticated searches and how to use their output, see Searching with the List function. |
<?xml version="1.0" encoding="UTF-8"?>
<!-- Begin DTD - The DTD should not be modified.-->
<!DOCTYPE dirscript [
<!ELEMENT dirscript (action)+>
<!ELEMENT action (group | user | session)+>
<!ELEMENT group (groupid, description?, parent?, removeusers?)>
<!ELEMENT user (userid, groupid*, description?, authentication?, savepref?, removegroupid?)>
<!ELEMENT session (filename?, (groupid | userid)+, description?)>
<!ELEMENT groupid (#PCDATA)>
<!ELEMENT userid (#PCDATA)>
<!ELEMENT description (#PCDATA)>
<!ELEMENT userlist (userid+, groupid+, filename+)>
<!ELEMENT grouplist (userid+, groupid+, filename+)>
<!ELEMENT parent (#PCDATA)>
<!ELEMENT removeusers (#PCDATA)>
<!ELEMENT removegroupid (#PCDATA)>
<!ELEMENT authentication ((pw?, changepw?) | (nativeid))>
<!ELEMENT pw (#PCDATA)>
<!ELEMENT changepw (#PCDATA)>
<!ELEMENT nativeid (#PCDATA)>
<!ELEMENT savepref (#PCDATA)>
<!ELEMENT filename (#PCDATA)>
<!ATTLIST action type (add | delete | update | list) #REQUIRED>
<!ATTLIST authentication type (pw | native) #REQUIRED>
]>
<!-- End DTD -->
<dirscript>
<action type="add">
<!-- Add three groups -->
<group>
<groupid>3270GROUP</groupid>
<description>Group with 3270 sessions</description>
</group>
<group>
<groupid>5250GROUP</groupid>
<description>Group with 5250 sessions</description>
</group>
<group>
<groupid>mygroup</groupid>
<description>Group with parent</description>
<!-- the parent element should only be specified if using LDAP -->
<!-- <parent>3270GROUP</parent> -->
</group>
<!-- Add a user to the 3270 group and give them a password. -->
<user>
<userid>user1</userid>
<description>First User</description>
<authentication type="pw">
<pw>mypw</pw>
<changepw>yes</changepw>
</authentication>
<groupid>3270GROUP</groupid>
</user>
<!-- Add a user to the 5250 group and do not allow them to save their session preferences -->
<user>
<userid>user2</userid>
<description>Second User</description>
<authentication type="pw">
<pw>mypw</pw>
<changepw>yes</changepw>
</authentication>
<groupid>3270GROUP</groupid>
<savepref>no</savepref>
</user>
<!-- The session elements are commented because the file may not exist. -->
<!-- If you would like to add a session, then export a session with the -->
<!-- correct file name and remove the comment tags before running DirUtil. -->
<!-- Add a session to the 3270 group -->
<!--
<session>
<description>3270 Display</description>
<filename>3270dsp.zie</filename>
<groupid>3270GROUP</groupid>
</session>
-->
<!-- Add a session to the 5250 group -->
<!--
<session>
<description>5250 Display</description>
<filename>5250dsp.zie</filename>
<groupid>5250GROUP</groupid>
</session>
-->
<!-- Add a session to user1 -->
<!--
<session>
<description>3270 Printer</description>
<filename>3270prt.zie</filename>
<userid>user1</userid>
</session>
-->
</action>
<!-- List all users and all groups in the system and send output to the default XML output file -->
<!--
<action type = "list">
<userlist>
<userid>*</userid>
</userlist>
<grouplist>
<userid>*</userid>
<groupid>*</groupid>
</grouplist>
</action>
-->
</dirscript>
Searching with the List function
Search basics | |
Using wildcards | |
Search examples |
Search basics Invoke the list function by designating it as a value for an action type: <action type="list">. Next you specify either, or both, of two search types (which apply to existing users and groups only):
- User-based searching, delimited by the <userlist> element. A <userlist> search returns user-specific information: user ID, group ID, description, and authentication type. Example
-
Group-based searching, delimited by the <grouplist> element. A <grouplist> search returns
group-specific information: group ID, description. Example
Group-based searching is not supported for LDAP.
For each search type, you can define criteria only with the <userid> and <groupid> elements. You do, however, have the flexibility to incorporate wildcards into your search criteria. Because you can use any number of wildcards, and place them at any location in the search string, you can make a search as open as you like.
Default criteria: When you do not specify one of the <userid> or <groupid> elements (or fail to specify both elements), the list function defaults to a wildcard assumption for the element(s). You are therefore assured of the most open search possible.
Directory Utility writes your search output to an XML file.
Using wildcards The wildcard character is the asterisk (*).
Directory Utility supports virtually any wildcard placement for the two searchable tags, <groupid> and <userid>. Wildcards may appear in either searchable element, both elements, or neither. They can appear any number of times, interspersed with alpha-numeric characters, or by themselves. If you omit either of the two ID tags from the search criteria, Directory Utility assumes the element to be a wildcard (*), and performs the wildcard search for that tag by default.
Examples of valid wildcard placement:
<userid>*</userid> | All users |
<groupid>*</groupid> | All groups |
<userid>a*</userid> <groupid>*</groupid> | Users with ID starting with an "a" and in any group |
<userid>a*s</userid> <groupid>zieweb</groupid> | Users with ID starting with an "a" and ending with an "s," in the group zieweb |
<userid>alhines</userid> <groupid>zieweb</groupid> | User "alhines" in the group zieweb |
Search examples Examples combining all of the elements within the list function:
<userlist> <userid>*</userid> <groupid>*</groupid> <filename>my.xml</filename> </userlist> | Perform a user-based search (meaning return user-based output) for all users in all groups, and send output to my.xml. |
<grouplist> <userid>a*</userid> <groupid>zieweb</groupid> <filename>your.xml</filename> </grouplist> | Perform a group-based search (meaning return group-based output) for the group zieweb that contains a user ID starting with an "a," and send output to your.xml. |
General summary information for the list function, such as a count of searches performed, follows the same structure as other Directory Utility summary information. You can send the list summary data to the console, log file, or both. |
Using output of the List function
Because all output from the list function is written to an XML file, you can immediately reuse it as input for other Directory Utility functions. In the XML output file, you simply change the action command from list to add, delete, or modify.
If you name an output file (with the tag <filename>) when you input search criteria, Directory Utility writes the list results in the directory and file you designate. See search examples. If you do not supply an output file name, Directory Utility stores results in the default file, DirUtilList.xml, which resides in the zieforweb\lib\samples\DirUtil directory. Every time you do not specify a file for search output, the list function appends your results to DirUtilList.xml.
If you mistakenly specify a nonexistent file path, the results are the same: Directory Utility writes to the default file, adding to its contents with every new search.
For Unix environments: Ensure that the pathnames for your XML output files are valid according to your particular Unix operating system. For example, if your operating system does not recognize all characters in your file pathname, its interpretation of the unknown characters may render the file name invalid. Then you may not be able to open the output file and retrieve your search results. |
Output sample
If you input the following:
<dirscript>
<action type="list">
<userlist>
<userid>*</userid>
<groupid>*</groupid>
</userlist>
<grouplist>
<userid>*</userid>
<groupid>*</groupid>
</grouplist>
<action>
<dirscript>
You generate the following output in the default XML file, DirUtilList.xml:
(So that you can keep track of your searches, Directory Utility displays your original criteria as comments at the beginning of the file.)
<!--Searching based on: Userlist -->
<!--with: userid= * -->
<!-- groupid= * -->
<dirscript>
<action type="list">
<user>
<userid>user1</userid>
<groupid>zieweb</groupid>
<description></description>
<authentication>pw</authentication>
</user>
<user>
<userid>user2</userid>
<groupid>group2</groupid>
<description></description>
<authentication>nativeid</authentication>
</user>
</action>
</dirscript>
<!--Searching based on: Grouplist -->
<!--with: userid= * -->
<!-- groupid= * -->
<dirscript>
<action type="list">
<group>
<groupid>zieweb1</groupid>
<description>ZIEWeb Users</description>
<parent></parent>
</group>
<group>
<groupid>group2</groupid>
<description>Other Users</description>
<parent></parent>
</group>
</action>
</dirscript>