Q000241e admin guide

Cybermation ESP: dSeries
Release 5.0
Administrator’s Guide
ESPD-5.0-AG-02

Second Edition (February 2007)
This edition applies to Cybermation ESP: dSeries Release 5.0. The software and related
manuals are protected by copyright law.
Cybermation ESP: dSeries documentation
This documentation and any related computer software help programs (hereinafter referred to
as the “Documentation”) is for the end user’s informational purposes only and is subject to
change or withdrawal by CA at any time.
This Documentation may not be copied, transferred, reproduced, disclosed, modified or
duplicated, in whole or in part, without the prior written consent of CA. This
Documentation is confidential and proprietary information of CA and protected by the
copyright laws of the United States and international treaties.
Notwithstanding the foregoing, licensed users may print a reasonable number of copies of the
documentation for their own internal use, and may make one copy of the related software as
reasonably required for back-up and disaster recovery purposes, provided that all CA
copyright notices and legends are affixed to each reproduced copy. Only authorized
employees, consultants, or agents of the user who are bound by the provisions of the license
for the product are permitted to have access to such copies.
The right to print copies of the documentation and to make a copy of the related software is
limited to the period during which the applicable license for the Product remains in full force
and effect. Should the license terminate for any reason, it shall be the user’s responsibility to
certify in writing to CA that all copies and partial copies of the Documentation have been
returned to CA or destroyed.
EXCEPT AS OTHERWISE STATED IN THE APPLICABLE LICENSE AGREEMENT,
TO THE EXTENT PERMITTED BY APPLICABLE LAW, CA PROVIDES THIS
DOCUMENTATION “AS IS” WITHOUT WARRANTY OF ANY KIND, INCLUDING
WITHOUT LIMITATION, ANY IMPLIED WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE OR NONINFRINGEMENT. IN NO
EVENT WILL CA BE LIABLE TO THE END USER OR ANY THIRD PARTY FOR
ANY LOSS OR DAMAGE, DIRECT OR INDIRECT, FROM THE USE OF THIS
DOCUMENTATION, INCLUDING WITHOUT LIMITATION, LOST PROFITS,
BUSINESS INTERRUPTION, GOODWILL, OR LOST DATA, EVEN IF CA IS
EXPRESSLY ADVISED OF SUCH LOSS OR DAMAGE.
The use of any product referenced in the Documentation is governed by the end user’s
applicable license agreement.
The manufacturer of this Documentation is CA.
Provided with “Restricted Rights.” Use, duplication or disclosure by the United States
Government is subject to the restrictions set forth in FAR Sections 12.212, 52.227-14, and
52.227-19(c)(1) - (2) and DFARS Section 252.227-7014(b)(3), as applicable, or their
successors.
All trademarks, trade names, service marks, and logos referenced herein belong to their
respective companies.
Copyright © 2007 CA. All rights reserved.

Contents
Using this guide ................................................................................................. 1
Other guides in the Cybermation ESP: dSeries library ....................................... 2
Changes in this edition....................................................................................... 2
1 Introduction to Cybermation ESP: dSeries 5
Cybermation ESP system components ............................................................... 6
How the components work together .................................................................. 7
2 Maintaining Cybermation ESP Desktop Client 9
About the ESP Desktop Client Admin perspective........................................... 10
Using the Admin perspective............................................................................ 10
Managing server connections ........................................................................... 11
Changing passwords......................................................................................... 11
Resetting a user’s password............................................................................... 12
Viewing a list of users connected to the server .................................................. 12
Applying software updates to ESP Desktop Client ........................................... 13
3 Working with Cybermation ESP Server 15
Checking server status ...................................................................................... 16
About ESP Server start types ............................................................................ 17
Starting the server ............................................................................................ 18
Stopping the server........................................................................................... 20
Recycling the server.......................................................................................... 20
Configuring the server...................................................................................... 22
Changing the email addresses or SMTP server ................................................. 23
ESPD-5.0-AG-02 iv

Setting up failure notifications when Applications fail to generate .................... 24
Setting up notifications when a job is forced to complete ................................. 24
Checking the server memory usage................................................................... 25
Viewing a list of artifacts in the system ............................................................. 25
Viewing your license status............................................................................... 26
Monitoring the shared directory....................................................................... 26
Changing the Windows service name for Cybermation ESP Server .................. 30
Installing the ESP High Security Option.......................................................... 30
4 Working with Cybermation ESP Agents 33
Supported ESP Agents and related documentation........................................... 34
Setting up ESP Agents to work with ESP Server............................................... 34
Setting up strong encryption between ESP System Agents and ESP Server....... 51
Removing ESP Agent from ESP Server ............................................................ 54
Modifying ESP Agent configuration parameters............................................... 55
Configuring the z/OS ESP Agent..................................................................... 57
Controlling ESP Agents ................................................................................... 58
5 Establishing and Controlling Security 61
About ESP Server security................................................................................ 62
Working with users .......................................................................................... 66
Working with groups ....................................................................................... 69
Summary of security permissions ..................................................................... 72
Setting up your ESP Server security network.................................................... 84
6 Handling Cybermation ESP Server Log Files 95
About log files .................................................................................................. 96
Changing a log’s location or name ................................................................... 97
Creating an audit log report ............................................................................. 98
Filtering messages sent to trace logs .................................................................. 99
Summary of filter IDs .................................................................................... 101
7 Administering ESP High Availability 105
ESP High Availability terminology................................................................. 106
The ESP High Availability process ................................................................. 107
Configuring ESP High Availability detection ................................................. 110
Changing the type of failback......................................................................... 111
Switching Primary and Standby roles ............................................................. 112
Converting to an ESP High Availability installation....................................... 112
Verifying the ESP High Availability configuration ......................................... 117
Preventing auto connection to the Standby .................................................... 119
8 Monitoring SNMP Messages 121
About SNMP messages .................................................................................. 122
Interpreting SNMP messages ......................................................................... 122
Changing the SNMP Manager settings .......................................................... 124
v ESPD-5.0-AG-02

Contents
Using third-party SNMP Managers ............................................................... 125
Enabling SNMP messages from ESP System Agents ...................................... 125
Receiving SNMP messages............................................................................. 126
Stopping the SNMP trap receiver................................................................... 126
Working with the SNMP Message Viewer ..................................................... 127
9 Working with the ESP Server Database 129
About your ESP Server database .................................................................... 130
Changing the database connectivity properties ............................................... 131
10 Cybermation ESP: dSeries Maintenance Procedures 133
Setting up a housekeeping Application........................................................... 134
ESP Server maintenance................................................................................. 136
ESP Agent maintenance ................................................................................. 143
11 Command Console Commands 155
Command definitions and syntax................................................................... 156
Issuing appcmd commands using the Command Utility ................................ 159
12 Integrating Cybermation ESP: dSeries Servers 163
Integrating your ESP Servers .......................................................................... 164
Verifying your integration .............................................................................. 168
13 Using the Import/Export Utility 171
Index 175
ESPD-5.0-AG-02 vi

Using this guide
This guide assumes you have installed Cybermation ESP: dSeries. Use this guide for
post-installation tasks such as setting up security, configuring ESP High Availability,
and performing maintenance tasks.
Following installation, you will need to perform the following administrative tasks.
Administrator Task See
Define, configure, maintain, and control
Agents
• Working with Cybermation ESP Agents
• ESP Agent maintenance
Create and maintain security profiles • Establishing and Controlling Security
Set up, maintain, and periodically archive
and clear server logs produced within
Cybermation ESP: dSeries
• Handling Cybermation ESP Server Log
Files
• Performing an automated cleanup of
ESP Server
• Archiving server log files
• Clearing server log files
ESPD-5.0-AG-02 1

Section–Other guides in the Cybermation ESP: dSeries library
Other guides in the Cybermation ESP: dSeries library
Installing Cybermation ESP: dSeries
This guide covers the installation process for installing and configuring the ESP Server
components: ESP Server and its default Agent, and ESP Desktop Client. The guide
provides instructions for two types of installation: single ESP Server (stand-alone)
installations and ESP High Availability installations.
Cybermation ESP System Agent Administrator’s Guide
This guide describes how to install, configure, secure, maintain, and control ESP
System Agent. This guide also provides instructions to configure Cybermation Hosts
to work with ESP System Agent. The final chapters contain troubleshooting and
reference information.
Getting Started with Cybermation ESP: dSeries
This guide is for new Cybermation ESP: dSeries users who want to learn about the
product. Getting Started is a tutorial that teaches users how to schedule and run jobs
with Cybermation ESP: dSeries.
User’s Guide
The User’s Guide describes how to define, schedule, monitor, and control workflow
with Cybermation ESP: dSeries. This guide is the primary resource for schedulers and
operators. It includes information on forecast and history reporting, previously found
in the Workload Reporting Guide, and real-life examples from the Examples Cookbook.
Beyond Basic Scheduling: A Guide to Using Scripts
This guide is intended for anyone who wants to create scripts that work with
Applications. The first six chapters of the guide cover JavaScript scripts. The final
chapter and appendix cover the ESPmgr utility and using it within scripts.
Changes in this edition
In this edition, the tasks and references related to the Oracle packaged database have
been removed, including the chapter titled "Working with the Packaged Oracle
Database" and the "Oracle Administration Primer" contained in the Appendix .
2 ESPD-5.0-AG-02

Section–Changes in this edition
4 ESPD-5.0-AG-02

Introduction to Cybermation ESP: dSeries
ESP: dSeries provides distributed job scheduling and workflow management across the
enterprise. It is a simple, flexible, and powerful solution for enterprise application
integration (EAI) and systems operations. Platform-independent as a result of its next-generation
XML and JAVA architecture, ESP: dSeries functions across various server
and Enterprise Resource Planning (ERP) platforms, including
• UNIX
• Windows NT/2000/2003
• z/OS®
• IBM OS/400
• OpenVMS
• Compaq NSK
• SAP® R/3
• PeopleSoft
• Oracle
ESPD-5.0-AG-02 5

Section–Cybermation ESP system components
Cybermation ESP system components
An ESP system consists of the following components:
• ESP Server
• ESP Desktop Client
• ESP Agents
ESP Server
ESP Server is the core of the ESP system. ESP Server handles and directs all incoming
communication from ESP Desktop Client, ESP Agents, a Relational Database
Management System (RDBMS), and a peer ESP Server in an ESP High Availability
configuration.
ESP Server requires a RDBMS for message processing, ESP High Availability, and
storing server configuration files, resource definition files, and historical reporting
data.
ESP Desktop Client
ESP Desktop Client is a graphical interface for defining, monitoring, and controlling
enterprise workflow. The interface enables users to quickly drag-and-drop their way
through workflow definitions, manage calendars, and monitor and control batch
workflow, regardless of the operating system. A ESP system can have many ESP
Desktop Clients.
ESP Desktop Client also includes the administrator’s tools for setting up, monitoring,
and diagnosing problems with the ESP: dSeries solution. For example, administrators
can use the SNMP Message Viewer to monitor traps sent from ESP Servers, ESP
Agents or jobs.
6 ESPD-5.0-AG-02

Chapter 1–Introduction to Cybermation ESP: dSeries
ESP Agents
ESP Agents are applications that extend batch workflow across multiple operating
systems. ESP Agents automatically run batch workflow and monitor its progress. ESP
Agents communicate with ESP Server through TCP/IP.
When you install ESP Server, a default ESP System Agent automatically installs on
the same platform as ESP Server. For example, if you install ESP Server on Windows
2000, an ESP System Agent automatically installs on the same machine.
How the components work together
The following diagram illustrates how the ESP components work together.
• The top of the diagram shows ESP Client, the application you use to schedule and
monitor workflow and manage the ESP system.
• The middle of the diagram shows ESP Server, which services requests from ESP
Desktop Client and submits work to ESP Agent machines. ESP Server runs on
UNIX and Windows platforms.
• The bottom of the diagram shows ESP Agents, which initiate and monitor the
scheduled workflow (such as commands and scripts) and communicate status
information to ESP Server.
ESPD-5.0-AG-02 7

Section–How the components work together
8 ESPD-5.0-AG-02

Maintaining Cybermation ESP Desktop
Client
This chapter contains the following topics:
• About the ESP Desktop Client Admin perspective
• Using the Admin perspective
• Managing server connections
• Changing passwords
• Resetting a user’s password
• Viewing a list of users connected to the server
• Applying software updates to ESP Desktop Client
ESPD-5.0-AG-02 9

Section–About the ESP Desktop Client Admin perspective
About the ESP Desktop Client Admin perspective
As an administrator, you will use the ESP Desktop Client Admin perspective to
perform tasks associated with ESP Server and ESP Agents. The Admin perspective
provides access to the following views:
• Command Console — For issuing appcmds
• Console View — For monitoring messages sent from ESP Server
• Security — For setting up and managing users and groups to access ESP Server
• SNMP Message Viewer — For monitoring SNMP messages that contain
information regarding ESP Server, ESP Agents, ESP High Availability, and Alerts
• Topology — For configuring ESP Server parameters, setting ESP High Availability
parameters, defining ESP Agents in the ESP Server topology, and configuring ESP
Agent parameters
Using the Admin perspective
To use the ESP Desktop Client Admin perspective, you must connect to ESP Server
as a user assigned ADMINGRP permissions. The default administrator’s user ID and
password are ADMIN and admin.
Typically, ESP Desktop Client is set up with a default server connection that uses the
SCHEDMASTER user ID. For convenience, you may want to either change your
default connection to use ADMIN or add a server connection for ADMIN.
Note: For security purposes, you should change the ADMIN user’s password once you
have connected.
10 ESPD-5.0-AG-02

Chapter 2–Maintaining Cybermation ESP Desktop Client
Managing server connections
You can add, modify and remove ESP Desktop Client server connections.
To add a server connection
1. Collect the following information for ESP Server:
• Address — The IP address or DNS name of the machine where you have
installed ESP Server
• Port — The ESP Server client port number. The default value is 7500.
• User ID — Your Cybermation ESP user name for scheduling. The default name
is SCHEDMASTER (in upper case).
• Password — The password that corresponds to the user ID. The default
scheduling password is schedmaster (in lower case).
2. Open the ESP Desktop Client Connections view using one of the following
methods:
• Click the Show the Connections View icon.
• Select Window > Show View > Connections.
3. Click the Create a new connection icon.
The New Connection dialog appears.
4. Enter the required details and click Save.
To delete a server connection
In the ESP Desktop Client Connections view, right-click the server connection and
select Remove.
Changing passwords
Passwords don’t expire. Users can change their passwords any time. When specifying a
new password, do not leave the field blank. The password cannot exceed 32
characters. The first character must be alphabetical. The password is case sensitive.
ESPD-5.0-AG-02 11

Section–Resetting a user’s password
To change a password
1. Connect to ESP Server using ESP Desktop Client.
2. In the Connections view, right-click the server connection and select
Change Password.
3. In the Change Password dialog, enter the old and new passwords, confirm the new
password, and click OK.
Resetting a user’s password
From time to time, users may forget their passwords. You can reset a user’s password
using the Admin perspective Security view.
To reset a password
2. Open the Admin perspective.
3. Right-click Security and select Open.
4. On the Users tab, right-click the user whose password you need to reset and select
Reset Password.
5. In the Reset Password dialog, enter the new password, confirm it, and click OK.
Viewing a list of users connected to the server
You can use an appcmd to see who is connected to ESP Server. The generated list is
helpful if, for example, you need to shut down the server and want to notify those
users who are connected before shutting it down.
To view a list of users connected to ESP Server
3. Open the Command Console.
4. Enter the about command.
The command lists ESP Desktop Client users connected to ESP Server.
12 ESPD-5.0-AG-02

Chapter 2–Maintaining Cybermation ESP Desktop Client
Related topic
For more information about appcmds, see “Command definitions and syntax” on
page 156.
Applying software updates to ESP Desktop Client
To provide required software updates for ESP Desktop Client, Cybermation may
occasionally release fixes. You can download these fixes and distribute them internally
to your ESP Desktop Client users.
Distributing the software updates
1. Download the update zip file.
2. Create a directory on your system where users will access the updates.
3. Copy the update zip file to the directory you set up in step 2.
4. Notify users that updates are available and where to find them.
Tip: You might send users an email that specifies the name and location of the
update zip file. Your communication might also include the instructions described
under “Installing an ESP Desktop Client update”.
Installing an ESP Desktop Client update
1. Open ESP Desktop Client.
Note: Keep all perspectives closed.
2. Select Help > Software Updates.
The Select Update Archive dialog appears.
3. Browse to the location where the updates are stored.
4. Select the update zip file, and click Open.
The Updates dialog appears.
5. In the tree view, select the update feature and click Next.
Tip: To view a description of the feature, click More Info.
6. Follow the instructions on screen.
7. After you complete the installation, restart ESP Desktop Client.
ESPD-5.0-AG-02 13

Section–Applying software updates to ESP Desktop Client
14 ESPD-5.0-AG-02

Working with Cybermation ESP Server
• Checking server status
• About ESP Server start types
• Starting the server
• Stopping the server
• Recycling the server
• Configuring the server
• Changing the email addresses or SMTP server
• Setting up failure notifications when Applications fail to generate
• Checking the server memory usage
• Viewing a list of artifacts in the system
• Viewing your license status
• Monitoring the shared directory
• Changing the Windows service name for Cybermation ESP Server
• Installing the ESP High Security Option
ESPD-5.0-AG-02 15

Section–Checking server status
For information about Cybermation ESP Server maintenance, see Chapter 10,
“Cybermation ESP: dSeries Maintenance Procedures”
Checking server status
Checking ESP Server status on UNIX
1. Change to the ESP Server installation directory.
2. Run the status script.
./status
If the server is active, the script displays the process id of ESP Server, for example
:::::::::::::::
ESP Server
:::::::::::::::
18982
If the server is inactive, the process id is blank.
Checking ESP Server status on Windows
You can check the server status using Windows services, if the server is installed as a
service, or using Windows Console Mode.
To check ESP Server status using Windows services
1. From the Control Panel, double-click the Administrative Tools icon.
The Administrative Tools dialog appears.
2. Double-click the Services icon.
The Services dialog appears.
3. For the Cybermation ESP: dSeries Server service, check the Status field.
• If ESP Server is active, the field displays Started.
• If ESP Server is inactive, the field is blank.
To check ESP Server status using Windows Console Mode
If ESP Server is running in console mode, you can check its window (Start Cybermation
ESP: dSeries Server) for information on its status. In console mode, ESP Server stops
running if the Start Cybermation ESP: dSeries Server window is closed.
16 ESPD-5.0-AG-02

Chapter 3–Working with Cybermation ESP Server
About ESP Server start types
The start type specifies whether ESP Server will start with a warm or cold start. The
following table describes the impact of a warm and cold start on active workflow,
Events, and resource status.
Impact on Cold Start Warm Start
Active workflow Deletes any active workflow and
associated states
Events Does not process Events that
have not been processed at the
time of shutdown
Resource status Reverts the status of all logical
resources to their original
definition
Performing a cold start
Reads active workflow from the
time ESP Server shuts down. Upon
startup, ESP Server continues
running workflow from this point
onward.
Reads and schedules Events that
have not yet been processed at the
time of shutdown and continues
monitoring for Events that are to be
processed
Reads the status of all logical
resources from the time of
shutdown and continues managing
resource states from this point
onward
By default, ESP Server starts with a warm start. When you perform a cold start, ESP
Server deletes all active workflow and associated states, and you lose all active
processing data. For rare situations when you must perform a cold start, use the
following procedures.
Note: If the runonce.properties files exists in the ESP Server directory, ESP
Server will use the start type specified in the file. Otherwise, ESP Server uses a warm
start.
Stand-alone configuration
To perform a cold start on a single ESP Server
1. Stop ESP Server.
2. Open the runonce.properties.bak file, located in the ESP Server
installation directory.
3. Ensure the start type in the file is set to cold.
4. Remove the .bak extension from the filename to change it to
runonce.properties.
ESPD-5.0-AG-02 17

Section–Starting the server
5. Start ESP Server.
When ESP Server starts, it will rename the runonce.properties file to
runonce.properties.bak and default to a warm start.
Cybermation ESP High Availability configuration
To perform a cold start on a single ESP Server in a Cybermation ESP High Availability
configuration
1. Stop both servers.
Note: If either server is left running, the cold start cannot take effect.
2. Open the runonce.properties.bak file, located in the ESP Server
installation directory.
3. Ensure the start type in the file is set to cold.
4. Remove the .bak extension from the filename to change it to
runonce.properties.
5. Start the server you want to cold start.
When ESP Server starts, it will rename the runonce.properties file to
runonce.properties.bak and default to a warm start.
6. Start the other server.
Starting the server
Starting ESP Server on UNIX
2. Run the startEspServer script.
./startEspServer
ESP Server starts. If this server is a standalone server, or the preferred server in an
ESP High Availability configuration, the default ESP Agent also starts.
Starting ESP Server on Windows
You can start ESP Server using Windows services or using shortcuts.
To start ESP Server as a Windows service
1. From the Windows Control Panel, double-click the Administrative Tools icon.
18 ESPD-5.0-AG-02

3. Right-click the Cybermation ESP: dSeries Server service, and click Start.
Note: The ESP Server installation program provides the option of selecting an
automatic startup type for the Windows service. The default startup type for the
service is manual. If you left the default and want the service to start automatically at
startup, change its startup type to Automatic.
Important: In an ESP High Availability configuration, to start ESP Server as a
Windows service, the Cybermation ESP: dSeries Server service needs to log
on to a user account with network privileges. For more information,
see “Changing the user account a Windows service logs on to” on
page 19.
To start ESP Server using Windows shortcuts
If you did not install ESP Server as a Windows service, do one of the following:
• Select Start > Programs > Cybermation > ESP dSeries Server > Start ESP Server.
• In Windows Explorer, go to the ESP Server installation directory and double-click
startServer.exe.
The Start ESP Server window appears. ESP Server runs in console mode.
Note: Keep this window open. Closing the window stops ESP Server.
Changing the user account a Windows service logs on to
Note: This procedure applies to ESP High Availability configurations only.
1. From the Services dialog, right-click the Cybermation ESP: dSeries Server service, and
click Properties.
2. On the Log On tab, change the Log on as account to an account with network
privileges.
You can now start Cybermation ESP: dSeries Server as a Windows service.
ESPD-5.0-AG-02 19

Section–Stopping the server
Stopping the server
Stopping ESP Server on UNIX
2. Run the stopEspServer script.
./stopEspServer
ESP Server stops. If this server is the standalone server, or the preferred server in
an ESP High Availability configuration, the default ESP Agent also stops.
Stopping ESP Server on Windows
You can stop ESP Server using Windows services, if the server is installed as a service,
or using shortcuts.
To stop ESP Server using Windows services
1. From the Control Panel, double-click the Administrative Tools icon.
3. Right-click the Cybermation ESP: dSeries Server service, and click Stop.
To stop ESP Server using Windows shortcuts
If you did not install ESP Server as a Windows service, do one of the following:
• Select Start > Programs > Cybermation > ESP dSeries Server > Stop ESP Server.
• In Windows Explorer, go to the ESP Server installation directory and double-click
stopServer.exe.
Recycling the server
To recycle ESP Server, you must stop it and then restart it. You can stop ESP Server
through the Command Console or from the machine where the server is installed.
However, you cannot restart ESP Server from the Command Console. To restart the
server, you must start it from the machine where it is installed.
Note: Recycling ESP Server does not start or stop the default ESP Agent. To stop and
start the ESP Agent, refer to “Controlling ESP Agents” on page 58.
20 ESPD-5.0-AG-02

Stopping ESP Server using the Command Console
4. Enter the following command:
stop
On the server machine, ESP Server returns an acknowledgement message
indicating that it has shut down.
ESP Server with pid (19287) is down
Note:
• To use the stop command, you must be logged in as a user who is a member of
the ADMIN group.
• If ESP Server does not respond with an acknowledgment message, you must stop
it using the stopServer script.
Stopping ESP Server on UNIX
2. Run the stopServer script.
./stopServer
ESP Server stops. If the default Agent is running, the script does not stop it.
Stopping ESP Server on Windows
See “Stopping ESP Server on Windows” on page 20.
Restarting ESP Server on UNIX
You must restart ESP Server from the machine where it is installed. You cannot restart
the server using the Command Console.
2. Run the startServer script.
./startServer
The script starts ESP Server.
Restarting ESP Server on Windows
See “Starting ESP Server on Windows” on page 18.
ESPD-5.0-AG-02 21

Section–Configuring the server
Configuring the server
ESP Server has two sets of configuration parameters you can change: instance
parameters and shared parameters. Instance parameters contain server- and system-specific
information, such as ports and server names. Shared parameters contain non-server-
specific information, such as the information shared between ESP Servers in an
ESP High Availability installation.
You can view and modify server parameters using the Admin perspective Topology
view.
Note: For changes to take effect, you must recycle ESP Server.
Configuring server parameters
3. Open the Topology view.
4. In the network tree, right-click the ESP Server connection and select a menu
option:
• Configure instance parameters
• Configure shared parameters
5. Configure the parameters.
6. Click Update to save your changes.
7. If you are modifying any of the following parameters, you must recycle ESP
Server:
Topology View Properties
Server Shared Parameters >
General tab
• Global Agent heartbeat interval in minutes
• Messages processed before garbage collection
• Maximum client sessions
• Disk space monitoring ESP Agent
Failover tab
• Enable Automatic Failback to Preferred Server
• Ping Frequency
SNMP tab
• SNMP Manager Address
• SNMP Input Port
• Community of SNMP Manager
Server Instance Parameters >
Properties
• ESP Server RMI Port
• ESP Desktop Client Port
• Preferred server
22 ESPD-5.0-AG-02

Changing ESP Server port numbers
4. In the network tree, right-click the ESP Server connection and select
Configure instance parameters.
5. Modify the port settings.
• ESP Server RMI Port — The port ESP Desktop Client uses to make RMI calls to
ESP Server. The default port number is 1099.
• ESP Desktop Client Port — The port ESP Server uses to communicate with ESP
Desktop Client. The default is 7500.
7. Recycle ESP Server.
Changing the email addresses or SMTP server
You can specify two email addresses for ESP Server communications:
• Email address to identify ESP Server is the address to identify email sent by a particular
ESP Server.
• Send administrative emails to is a valid internal email address to which ESP Server will
send license-related and other administrative issues.
Use this procedure to change these email addresses or the name of your SMTP server.
To change the email addresses
Configure shared parameters.
The Server shared parameters view appears.
5. Click the Email tab.
6. Change the fields, as required.
ESPD-5.0-AG-02 23

Section–Setting up failure notifications when Applications fail to generate
Setting up failure notifications when Applications fail to
generate
By default, ESP Server sends an email when a triggered Event fails or fails to generate
an Application. An SNMP message appears in the email subject and contains a short
description of the failure reason. You can also set up SNMP failure notification for
these situations.
ESP Server sends the email notification to the ESP Server email recipient defined
during ESP Server installation. You can change the recipient after installation by
setting the Send administrative emails To parameter.
To prevent ESP Server from sending email when an Application fails to generate, set
Send email message when Application trigger fails to false.
To set up failure notifications when Applications fail to generate
5. On the General tab, set the following fields to true, as required:
• Send email message when application trigger fails
• Send SNMP message when application trigger fails
Setting up notifications when a job is forced to complete
Explanation of what this does and when you would set this up.
To set up notifications when a job is forced to complete
24 ESPD-5.0-AG-02

5. On the General tab, set the Process notifications when a WOB is forced to complete value
to true.
Checking the server memory usage
You can check the ESP Server current memory using the Command Console. The
console displays the total free memory and maximum heap size.
To check ESP Server memory usage
memcheck
The Command Console displays a message similar to the example below.
Viewing a list of artifacts in the system
You can view the total number of each ESP artifact types in your system using the
Command Console. The console lists the following ESP artifact types:
• Agents
• Forecasts
• Alerts
• Groups
• Applications
• JavaScripts
• Calendars
• Resources
• Events
• Users
To view a list of artifacts in the system
ESPD-5.0-AG-02 25

Section–Viewing your license status
countlist
The Command Console displays a message similar to the example below.
Viewing your license status
You can issue a command to view the total number of licenses available, the number
of licenses in use, and the temporary license’s expiry date.
To view your license status
licensestatus
The details of your license appear.
Monitoring the shared directory
ESP Server has two built-in monitoring features for its shared directory. You will
receive warning notifications when the following situations occur:
• The disk space drops below a warning threshold
• Access to the NFS server used by the shared directory becomes slow or unavailable
Note: To monitor the disk space, you must set the disk monitoring ESP Agent.
26 ESPD-5.0-AG-02

Related topics
• “Monitoring disk space available for the shared directory” on page 27
• “Setting the disk monitoring ESP Agent” on page 27
• “Configuring the disk space monitor” on page 28
• “Monitoring the shared directory availability” on page 28
• “Setting the warning threshold for monitoring the shared directory availability”
on page 29
Monitoring disk space available for the shared directory
ESP Server stores PSE Pro Object Database files in a shared directory. Over time, the
disk space for storing those files decreases. To prevent that disk space from running
out, ESP Server has a built-in feature that uses the default ESP Agent to monitor disk
space. When the disk space drops below a warning threshold, ESP Server will send an
SNMP message and an email to the administrative email recipient designated in its
topology. When the disk space drops below a shutdown threshold, ESP Server shuts
itself down.
Note: If you use ESP High Availability, when disk space becomes critically low, ESP
Server shuts down the Standby before shutting itself down.
Important: Do not run ESP Server from an account that uses disk quotas; disk
space monitor does not monitor disk quotas.
Setting the disk monitoring ESP Agent
To enable disk space monitoring, you must set the Disk monitoring ESP Agent parameter
in the ESP Server topology to the name of your default Agent.
To set the disk monitoring ESP Agent
5. In the Disk monitoring ESP Agent field, enter the name of the ESP Agent you will use
to monitor disk space.
6. Click Update to save your change.
ESPD-5.0-AG-02 27

Section–Monitoring the shared directory
Configuring the disk space monitor
Cybermation recommends you leave the default settings for disk space monitoring.
However, if required, you can override the defaults by adding the following properties
to the espresso.properties file located in the ESP Server installation directory.
Property Default
value
Description
diskmon.freekbwarnthresh 102400 The warning threshold value in kilobytes. When
the free disk-space level drops below this value,
ESP Server will send an email and SNMP
message. By default, ESP Server starts warning
when the disk space drops below 100 MB.
diskmon.freekbshutdownthres 5120 The warning shutdown value in kilobytes. When
the free disk space level drops below this value,
ESP Server shuts down. By default, ESP Server
shuts down when the disk space drops below 5
MB.
diskmon.cancelwarndeltakb 1024 After ESP Server issues the disk-space warning, it
cancels the warning when the disk-space level
reaches the sum of this property and the
diskmon.freekbwarnthresh value.
diskmon.rewarnintervalmin 15 The minimum interval, in minutes, at which ESP
Server re-sends warning messages when disk space
is low. For example, if you set this property to 5,
ESP Server re-sends warning messages at least five
minutes apart.
diskmon.emailprefix If set, ESP Server will prefix the subject line of the
warning email with this property’s value. Use this
field if you automatically filter subject lines.
Monitoring the shared directory availability
If the NFS server where the shared directory resides becomes unavailable, ESP Server
stops processing workflow. When the NFS server becomes available, ESP Server will
continue processing workflow normally. No workflow is lost during the unavailable
period.
To test access to the shared directory, ESP Server performs a check of the time it takes
to write and delete an 8K file to and from the shared directory. If the time to write and
delete the file exceeds a threshold value, ESP Server sends an SNMP message and
email warning that access to the shared directory is slow. If ESP Server can’t write the
file, it sends an SNMP message and email warning that the shared directory is
unresponsive. In this case, the NFS server may be down.
28 ESPD-5.0-AG-02

Setting the warning threshold for monitoring the shared directory
availability
If you are receiving too many warning messages, you can increase the time set by the
Max. acceptable disk write time parameter. The default threshold value is 1000ms.
To set the warning threshold
5. In the Max. acceptable disk write time field, enter the time (in milliseconds).
6. Click Update to save your change.
ESPD-5.0-AG-02 29

Section–Changing the Windows service name for Cybermation ESP Server
Changing the Windows service name for Cybermation ESP
Server
When you install ESP Server on Windows, you must install it as a Windows service. If
you want to change the service name after installing ESP Server, you can by following
this procedure.
To change the Windows service name for ESP Server
1. Run the removeServices.bat script located in the
<installDir>/Resources/Service directory.
The removeServices script removes the ESP Server display name from the
Windows Services dialog.
2. Open the espressoparm.txt file located in the
3. In the espressoparm file, change the Windows service name by modifying the
following parameters:
• Servicename
• Servicedisplayname
Note: Cybermation recommends you use the same name for both parameters. The
name must not include any spaces. You can use upper and lower characters in the
name.
4. Run the addServices.bat script located in the
The addServices script adds the ESP Server display name to the Windows Services
dialog.
Installing the ESP High Security Option
Stand-alone configuration
To install the ESP High Security Option on a single ESP Server
1. Stop ESP Server.
2. Copy the strongencryption.jar file into the following ESP Server
directory:
<installDir>/JAR_Library
30 ESPD-5.0-AG-02

3. Edit the following variables.
• On UNIX:
Edit the classpath variable in <installDir>/classpath.sh to
include strongencryption.jar by appending $JAR_LIB/
strongencryption.jar to export CLASSPTH.
• On Windows:
Edit the classpath variable in <installDir>/Resources/Service/
espressoparms.txt and the lax.class.path variable in
<installDir>/startServer.lax
Changing the classpath and lax.class.path variables will enable
strong encryption for running ESP Server as a Windows service and as a
console application, respectively.
4. Start ESP Server.
ESP High Availability configuration
To install the ESP High Security Option in an ESP High Availability configuration
1. Install the ESP High Security Option on the Standby. Follow the instructions
above for the stand-alone configuration. When you have completed this step, the
Standby should be running.
2. Using the ESP Desktop Client Admin perspective, open the Command Console
and invoke the changerole command against either the Primary or Standby.
3. Install the ESP High Security Option on the Primary. Follow the instructions
above for the stand-alone configuration. When you have completed this step, the
Primary should be running.
4. Using the ESP Desktop Client Admin perspective, open the Command Console
and invoke the changerole command against either the Primary or Standby.
Related topics
“Setting up strong encryption between ESP System Agents and ESP Server” on
page 51.
ESPD-5.0-AG-02 31

Section–Installing the ESP High Security Option
32 ESPD-5.0-AG-02

Working with Cybermation ESP Agents
• Supported ESP Agents and related documentation
• Setting up ESP Agents to work with ESP Server
• Setting up strong encryption between ESP System Agents and ESP Server
• Removing ESP Agent from ESP Server
• Modifying ESP Agent configuration parameters
• Defining ESP Agent users
• Configuring the z/OS ESP Agent
• Controlling ESP Agents
For information about ESP Agent maintenance, see Chapter 10, “Cybermation
ESP: dSeries Maintenance Procedures.”.
ESPD-5.0-AG-02 33

Section–Supported ESP Agents and related documentation
Supported ESP Agents and related documentation
Cybermation ESP: dSeries supports the following types of ESP Agents:
• ESP System Agent (for UNIX and Windows)
• ESP Agent for z/OS
• ESP Business Agent for PeopleSoft
• ESP Business Agent for SAP Solutions
• ESP Business Agent for Oracle E-Business Suite
• ESP Business Agent for Micro Focus Enterprise Server
Related documentation
For detailed information for a specific ESP Agent, refer to its associated
documentation. The following documents are supplied for each ESP Agent:
• Release Notes
• Administrator’s Guide
To schedule and monitor workflow on different operating system using ESP Agents,
refer to the Cybermation ESP: dSeries User’s Guide.
Setting up ESP Agents to work with ESP Server
You can install ESP Agents on various operating systems to run workflow using ESP
Server. You can also configure virtual ESP Agents. A virtual ESP Agent is one that
runs with a Tandem or OpenVMS parent ESP Agent. The parent ESP Agent routes
requests to the virtual ESP Agent.
To set up an ESP Agent to work with ESP Server, complete the following steps.
Step Activity Page 9
1. Prepare to install ESP Agent 35
2. Install and configure ESP Agent. 35
3. Add ESP Agent to the ESP Server Topology. 35
4. Set up ESP Agent security on ESP Server. 37
34 ESPD-5.0-AG-02

Chapter 4–Working with Cybermation ESP Agents
5. Start ESP Agent. 46
6. Check the communication between ESP Agent and ESP Server. 47
7. Run a test Application to verify your setup. 47
Prepare to install ESP Agent
Before you install ESP Agent, complete these steps:
• Verify the system requirements
To ensure your system meets the requirements, refer to the Release Notes for the
specific ESP Agent you are installing.
• Collect the information you need to install ESP Agent
Refer to the Administrator’s Guide for the information you must collect.
Install and configure ESP Agent
For installation and configuration instructions, refer to the Administrator’s Guide
provided with each ESP Agent.
Note: Ensure you have enough licenses available before adding a new ESP Agent to
the ESP Server topology. To check your license status, see “Viewing your license
status” on page 26.
Add ESP Agent to the ESP Server Topology
4. In the Topology view, right-click the ESP Server connection and select Add Agent.
The New Agent view appears.
5. In the Agent type field, select the type of ESP Agent you want to add.
The Properties tab appears.
6. Complete the following mandatory fields:
• Name — agentname parameter from the ESP Agent’s agentparm.txt file.
ESPD-5.0-AG-02 35

Section–Setting up ESP Agents to work with ESP Server
Note: ESP Server converts the ESP Agent name into uppercase. Ensure the
agentname parameter in the agentparm.txt file is in uppercase;
otherwise, ESP Server and ESP Agent cannot communicate.
• Address — IP address or DNS name of the machine where ESP Agent is
installed.
• Port number — IP port number ESP Agent uses to listen for traffic. This port
number must match the communication.inputport field in the
agentparm.txt file.
• Release number — Release number for ESP Agent.
• Encryption key — security.cryptkey parameter from the
agentparm.txt file, minus the prefix 0x.
• Heartbeat frequency (in minutes) — Frequency with which you want ESP Server
to send the heartbeat signal. If you want individual ESP Agents to have their
own heartbeat frequencies, set the shared configuration parameter Global Agent
heartbeat frequency to zero.
• Heartbeat attempts before sending an SNMP notification — Number of heartbeat
signals the ESP Server attempts before it sends an SNMP message indicating
ESP Agent inactivity.
7. Enter values for the other fields, as required.
8. To add a virtual ESP Agent to a Tandem or OpenVMS parent ESP Agent,
complete the following steps:
a. Click the Virtual ESP Agent tab.
b. Enter the parameter values for the virtual ESP Agent.
9. If an ESP Agent user specified in a job definition requires a password, define ESP
Agent users.
a. Click the Users tab.
b. Click Add.
The Add ESP Agent User dialog appears.
c. Complete the required fields: User ID, Password, and Confirm Password.
10. Click Update.
Set up security
To set up security, complete the following steps.
1. Set up ESP Agent security on ESP Server. 37
2. Set up 56-bit encryption on ESP Server. 37
3. Set up encryption on ESP Agent. 38
36 ESPD-5.0-AG-02

4. Turn on ESP Agent security. 38
5. Set up local security on ESP Agent. 39
6. Reload the ESP Agent security file. 45
Set up ESP Agent security on ESP Server
To control ESP Agent access, you must set up the following security permissions on
ESP Server.
Access to Requires Allow Access to this
permission
Type of Access
ESP Agents AGENT.agentname Run work on the ESP Agent
specified by agentname
User IDs AGENTUSR.agentname.user
id
Run a job on the ESP Agent
specified by agentname under
the user ID specified by userid
Issue
commands
AGENTMSG.cmd.agentname Issue ESP Agent control commands
to the ESP Agent specified by
agentname.
Note: cmd is APPCMD.
Related topics
“Set up local security on ESP Agent” on page 39
Set up 56-bit encryption on ESP Server
You must set up regular 56-bit encryption on ESP Server by specifying the encryption
key for your ESP Agent in the ESP Server Topology. If you are eligible, you can also
set up strong (256-bit) encryption.
To set up 56-bit encryption on ESP Server
4. In the Topology view, right-click ESP Agent and select View Properties.
5. In the Encryption key field, enter the encryption key for ESP Agent. This is the same
key specified in the security.cryptkey parameter in the agentparm.txt
file, but without the prefix “0x”.
6. Click Update.
ESPD-5.0-AG-02 37

Related topics
“Setting up strong encryption between ESP System Agents and ESP Server” on
page 51
Set up encryption on ESP Agent
To set up encryption on ESP Agent, add the security.cryptkey parameter to the
agentparm.txt file located in the ESP Agent installation directory.
The value for the security.cryptkey parameter on ESP Agent must match the
encryption key defined for ESP Agent on ESP Server. If these values do not match,
encryption will fail and communication will not be allowed between ESP Server and
ESP Agent.
Tip: To locate the encryption key, use the Admin perspective to open the Topology
view for the Agent.
Syntax
security.cryptkey=<pathcryptkey.txt|Key>
Example
security.cryptkey=0x0102030405060708
The security.cryptkey parameter turns on encryption and automatically turns
on Level 2 message prefixing, which is required for encryption. Level 2 message
prefixing is required in all instances. If security.cryptkey is set, ESP Agent uses
Level 2 message prefixing regardless of the value specified in the
communication.prefixlevel parameter.
Turn on ESP Agent security
1. In the agentparm.txt file located in the ESP Agent installation directory,
change the value of the security.level parameter to on.
security.level=on
2. Stop and restart ESP Agent.
38 ESPD-5.0-AG-02

Related topics
“Modifying ESP Agent configuration parameters” on page 55
Set up local security on ESP Agent
Important: In this section, examples apply to UNIX operating systems. Paths
contain forward slashes, no drive is identified, and references are made
to root authority. Apart from these items, however, the examples apply
to ESP Agent on Windows also.
About the security file
The ESP Agent security file is named security.txt. It must reside in the ESP
Agent installation directory. If the file does not exist, default security rules apply, as
described under “Default security rules” on page 40.
The security file contains three types of rules:
• Rules that allow or prevent ESP Server users from submitting jobs that run under
a specific user ID, from a specific directory. These rules begin with the letter x, as
follows:
x <a | d> <ESP_HostuserID> <Agent_UserID> path
• Rules that allow or prevent an FTP user ID from issuing FTP-related commands
to files in specified directories. These rules begin with the letter f, as follows:
f <a | d> <FTP_UserID> <operation> <path>
Note: Paths are case sensitive.
• Rules that allow or prevent a user ID the authority to issue control commands to
ESP Agent. These rules begin with the letter c, as follows:
c <a | d> <ESP_HostuserID> CONTROL command
Note: ESP Agent security rules do not override permissions set at the operating system
level.
Rule parameter descriptions
The following describes the rule parameters.
Entry Description
rule type Identifies the ESP Agent rule type
(x) identifies a rule controlling execution of scripts and
commands.
(c) identifies a rule controlling operational commands to an ESP
Agent.
(f ) identifies FTP commands.
ESPD-5.0-AG-02 39

Entry Description (Continued)
permission Identifies whether access is allowed or denied. This parameter
contains two possible values:
• a indicates permission is allowed.
• d indicates permission is denied.
ESP_HostuserID Identifies the ESP Host Manager name or the ESP Host user ID
this rule applies to
Agent_UserID Identifies the user ID on the ESP Agent machine under which the
job is run
FTP_UserID Identifies the FTP user ID this rule applies to
path Identifies the path ESP Host is allowed to submit jobs from, using
the user ID identified by Agent_UserID
operation Identifies the FTP command. Valid commands are
• list — Changes directory and list files (CD, LIST,
NLST)
• read — Retrieves the file (RETR)
• write — Stores the file or makes a directory (STOR,
STOU, RNFR, RNTO, MKD)
• delete — Deletes the file or directory (DELE, RMD)
Note: The above commands apply to ESP Agent as FTP server.
For FTP jobs, only read and write apply.
command Identifies the control command. Valid commands are: shutdown,
refresh, clrfiles, flush, quiesce, and restart. You can also specify an
asterisk (*) for all commands.
Default security rules
When ESP Agent starts, it checks for the security file.
• If the file does not exist, default security rules apply.
• If the file exists, ESP Agent uses the rules defined in the file. It does not use the
default security rules. If a request does not have a match in the security file, ESP
Agent denies the request.
• If the file does not exist and ESP Agent security is turned off in the
agentparm.txt file (security.level=off ), ESP Agent does not check security.
Note: The following default security rules apply when the security file does not exist,
and ESP Agent security is turned on in the agentparm.txt file
(security.level=on):
x a * * +
x d * root +
c a * * *
f a * * +
Note: For ESP Agent on Windows, substitute Administrator for root.
40 ESPD-5.0-AG-02

Security rule for Micro Focus jobs
If ESP Agent security is turned on (security.level=on), you must add the
following security rule to the security.txt file in order to run Micro Focus jobs
on the ESP Agent machine. This rule allows any ESP Server user to submit Micro
Focus jobs that run under any ESP Agent user ID.
x a * * cybMFCommand.exe
If you do not want to allow all ESP Server users to submit MicroFocus jobs, you can
restrict the submission of Micro Focus jobs to specific users instead. For example, the
following rule allows the ESP Server user, SCHEDMASTER, to submit Micro Focus
jobs that run under the ESP Agent user ID, SYSTEM.
x a SCHEDMASTER SYSTEM cybMFCommand.exe
If you do not add the Micro Focus security rule to the security.txt file and ESP
Agent security is turned on, ESP Agent will not run Micro Focus jobs.
Additional security file rules
Wildcards
The Cybermation Host name, user IDs, paths, verbs, and subverbs can contain a
single wildcard character at the end of the field only. For wildcards, use the asterisk (*)
and the plus sign (+).
Wildcard Description
Asterisk (*) Represents 0 or more character matches in the current directory
only
plus sign (+) Represents 0 or more character matches in the current directory
and all subdirectories
Start point and spacing
Every security rule starts in column 1. Items on a line are
• Separated by one or more blanks or tab characters.
• End with a new-line character.
Comment lines
The file can contain comment lines. An asterisk (*) or a number sign (#) in column 1
identifies comment lines.
ESPD-5.0-AG-02 41

Understanding security rule interpretation
For a rule to match, three components of a rule have to match. If two or more rules
match, the closest match overrides the others, as follows:
Interpretation Explanation
A specific rule overrides a generic rule. A generic rule
is a rule that contains wildcards.
If both rules are generic, the more specific one
overrides the other.
The ESP_HostuserID user ID takes precedence over
the server user ID, and the server user ID takes
precedence over the directory name.
If there is still ambiguity after these rules have been
applied, a deny rule will override an allow rule.
Security file example #1
/u1/jsmith
overrides
/u1/jsmith*
/u1/jsmith/scripts/*
overrides
/u1/jsmith*
/u1/jsmith/scripts/a*
overrides
/u1/jsmith/scripts*
A rule is considered a closer match if
the ESP_HostuserID is a closer
match. If the ESP_HostuserIDs of
two rules are the same, the rule with
the closest matching server ID
overrides the other.
c d root * *
overrides
c a root * *
Line Security File Example #1
1 # Example 1
2 * Last updated on August 01, 2002.
3 x a * * +
4 x d * gem* +
5 x a * root /prod/employee+
6 x d * root /prod/employee*
7 x a * root /prod/+
8 x d * root /prod/expense
9 x a * root /prod/*
10 x d * root /prod/+
11 c a * CONTROL *
Note: You must specify both types of permissions (x and c) even if there is no change
to one of the entry types.
Line Explanation of Security File Example #1
1 Comment line
42 ESPD-5.0-AG-02

Line Explanation of Security File Example #1 (Continued)
2 Comment line
3 Allows the ESP Server user to submit jobs under any user ID, from all directories
4 Prohibits the ESP Server user from submitting jobs under gem, or any user IDs
that begin with gem, from all directories
5 Allows the ESP Server user to submit the following jobs as root
Job Example
A job called employee from
directory
/prod/
All jobs beginning with employee
from directory /prod/
All jobs from the subdirectory
/prod/employee/ or its
subdirectories
All jobs from directories whose name
begins with employee in directory
/prod/ or their subdirectories
6 Prohibits the ESP Host user from submitting any jobs called employee, or any
jobs that begin with employee, as root in directory /prod/
7 Allows the ESP Host user to submit all jobs as root from directory /prod/ and
onwards
8 Prohibits the ESP Host user from submitting the job expense as root from
/prod/
9 Allows the ESP Host user to submit all jobs as root in directory /prod/
10 Denies the ESP Host user from submitting any jobs as root from directory
/prod/ and onwards
11 Allows all users to issue all control commands to this ESP Agent
Security file example #2
/prod/employee
/prod/employee_pay
/prod/employee_vacation
/prod/employee/fulltime_pay
/prod/employee/sales/
fulltime_pay
/prod/employee1999/
fulltime-pay
/prod/employee1999/sales/
fulltime_pay
Line Example
1 # Example 2
2 * Last updated on February 28, 2002.
3 x a SCHED* root /prod/+
4 x a ADM* root* /prod/*
5 x a JSMITH * /prod/+
6 c a MANAGER CONTROL *
7 f a * * +
8 f d user1 write /prod/*
9 f a user1 write /prod/W*
ESPD-5.0-AG-02 43

Line Example (Continued)
10 f d l* read /prod/report*
11 f a user2 * /program files/
Line Explanation of Security File Example #2
1 Comment line
2 Comment line
3 Allows any ESP Host user ID beginning with SCHED to submit jobs as root from
the directory /prod/ and onwards
4 Allows any ESP Host user ID beginning with ADM to submit jobs as root, or under
any user ID beginning with root, in directory /prod/
5 Allows JSMITH to submit jobs under any user ID from directory /prod/ and
onwards
6 Allows MANAGER to issue all control commands to this Agent
7 Allows all users to submit any FTP jobs in any directory
8 Denies user1 writing to any file in the directory /prod/
9 Allows user1 to write to any file starting with W in directory /prod
10 Denies all users whose ID starts with the letter l read access to any file that begins
with report in the directory /prod/
11 Allows user2 from using all FTP operations in any directory starting with
/program_files/cyb and any subdirectories
How the security file works
1. A sample security.txt file contains these entries.
cyb+
c a * * *
x d * * +
x a SCHEDMASTER UNIXUSR1 /usr/+
This file allows Cybermation ESP: dSeries user SCHEDMASTER to submit jobs
under user UNIXUSR1 from directory /usr/ and its subdirectories.
2. Security is turned on in the agentparm.txt file:
security.level=on
3. The job definition includes the user ID under which the job is to be run
(UNIXUSR1 in the sample above), as shown in the following job definition
examples:
44 ESPD-5.0-AG-02

Cybermation ESP: dSeries job definition
Reload the ESP Agent security file
The refresh command reloads an ESP Agent’s security file.
To reload ESP Agent’s security file
1. Connect to the ESP Server using ESP Desktop Client.
agentmsg control agentname(agentname) refresh
agentname is the name of the ESP Agent whose security file you want to reload.
The command reloads the ESP Agent’s security file.
ESPD-5.0-AG-02 45

Start ESP Agent
Starting ESP Agent on UNIX
1. Change to the directory ESP Agent is installed in.
./cybAgent &
The ESP Agent runs in the background.
Note: Before you start ESP Agent, make sure the cybAgent process and related Java
processes from the previous run of ESP Agent were shut down correctly.
Starting ESP Agent on Windows using the Start Agent program
shortcut
Click the Start Agent program shortcut.
Starting ESP Agent on Windows from the Control Panel
1. Open the Windows Control Panel.
2. Double-click Administrative Tools.
3. Double-click Services.
4. Right-click the ESP Agent service and click Start.
The default name for ESP Agent is ESP System Agent for Microsoft
Windows.
Starting ESP Agent on Windows from the command prompt
1. Change to the directory ESP Agent is installed in.
By default, ESP Agent is installed in
C:Program FilesCybermationESP System Agent
2. Enter one of the following:
• cybAgent -a
• net start Service_Name
Starting ESP Agent on Windows automatically
By default, the service is installed as Manual Startup Type. It is not started on system
startup. You can start ESP Agent manually via the Control Panel or command
prompt. You can set the Service Startup Type as Automatic, and the service will start
at startup.
1. Open the Windows Control Panel.
2. Double-click Administrative Tools.
46 ESPD-5.0-AG-02

3. Double-click Services.
4. Right-click the ESP Agent service and select Properties.
The default name for ESP Agent is ESP System Agent for Microsoft
Windows.
5. At Startup type on the Properties dialog, select Automatic.
Check the communication between ESP Agent and ESP Server
If you have administrator access to ESP Server, you can verify communications
between ESP Agent and ESP Server by checking the afmlog.txt file.
1. After defining ESP Agent to ESP Server, start ESP Agent.
2. Wait for a minute to ensure that communication between ESP Server and ESP
Agent is established.
3. Open the afmlog.txt file located in <installDir>/Resources/
LogFiles (UNIX) or <installDir>ResourcesLogFiles (Windows).
4. Search the afmlog.txt file for ESP Agent name and check for one of the
following types of responses (a or b):
a. The words RESPONSE STATUS, as shown in bold in the example below.
20040531 11364082+0400 MANAGER AGENT
2004053111363993+0400/MANAGER.1/MAIN RESPONSE STATUS
Plugin(CybControlStatusHandler) User(AGENT)
Host(HOSTNAME)
b. The words CONTROL ACTIVE, as shown in bold in the example below:
20040614 11070459+0400 MANAGER AGENT . CONTROL ACTIVE
OSText(Windows 2000 for x86) ByUser(User) User(AGENT)
Host(HOSTNAME)
Run a test Application to verify your setup
This section describes the steps to create a test Application to verify ESP Agent works
with Cybermation ESP: dSeries. In this verification test, you create an Application that
contains one job.
Note: Before you run the following procedures, ensure ESP Server, the relational
database server, and ESP Agent are running.
ESPD-5.0-AG-02 47

Step 1: Define your workflow
Connecting to ESP Server using ESP Desktop Client
1. Launch ESP Desktop Client.
2. In the Connect to ESP dialog, enter a user ID and password, and click Connect.
The welcome screen appears.
Tip: If your ESP Server is not the default connection name, select the connection
name, and enter the appropriate user ID and password for the ESP Server.
Creating an Application
1. From the welcome screen, click the Define icon.
The Define perspective opens. Ensure Application Workspace is the active view.
2. In the Application Workspace view, right-click your ESP Server name and click
New.
The Application Properties dialog appears.
3. In the Name field, enter Quick and click OK.
The Event Triggers and Workflow Objects palettes appear in an Application view
labelled Quick.
Note: You can resize and move the views to suit your requirements.
Defining an Event Trigger in the Application
You define an Event to schedule the workflow. When an Event is triggered, the
Application runs.
Setup: Ensure the tab containing the Application name Quick is active.
1. From the Event Triggers palette, click Trigger.
2. Click the workspace to the right of the palette.
A Trigger job icon appears on the workspace.
3. Right-click the Trigger icon and click Edit.
The New Date/Time Event view appears.
4. In the Prefix field, enter a prefix that identifies the Event you want to create.
An Event name has two parts: a prefix and a descriptive name. The prefix allows
you to group Events together. For example, a prefix could be the name of a user
ID or group ID. You can list Events based on their prefix.
5. In the Name field, enter a name for the Event.
Event names must be unique. You can give your Event a name related to the
function the Event is performing. For this scenario, enter Quick.
48 ESPD-5.0-AG-02

6. In the Application to run field, enter Quick.
7. In the Specify schedule criteria section, click the Add Row button.
8. In the Statement field, enter Run.
9. In the Criteria field, enter 4 pm daily.
10. Click Upload to upload the Event definition to ESP Server.
A message appears informing you when this Event will first execute.
Defining a job in the Application
For this test Application, create a script or batch file on the ESP Agent machine for
the test job:
1. Using Notepad or another text editor, create a file.
2. In the file, type exit.
3. Save the file as test.bat (Windows) or test.sh (UNIX).
Remember where you stored the test file.
You can verify communication between ESP Agent and ESP Server using a job type
(for example, UNIX and Windows jobs) that can run the test file you created.
Setup: Ensure the tab containing the Application name Quick is active.
1. From the Workflow Objects job palette, click the job type that matches your ESP
Agent machine. For example, choose the UNIX job type if your ESP Agent is
installed on a UNIX machine.
2. Click the workspace to the right of the job palette.
A job icon appears on the workspace.
3. Right-click the job icon and click Edit.
The job definition dialog appears.
4. In the Name field, enter a name for the job or use the default.
5. In the Agent name field, enter or select the ESP Agent name.
6. In the Command to run field, enter the full path to the test file you created.
7. Click OK.
Uploading the Application to ESP Server
In the Application Workspace view, right-click the Quick Application and click Upload.
The Application is uploaded to ESP Server.
ESPD-5.0-AG-02 49

Simulating the Event
Use the simulation feature to see a graphical representation of the test Application for
the Event Trigger schedule criteria.
1. Right-click the Trigger icon and click Simulate.
The Simulate the Event dialog appears.
2. Leave the fields blank and click OK.
Both a graphical representation and a text-based representation of the Application
appear.
Step 2: Run your workflow
The Application runs according to the criteria you define in the Event Trigger.
However, you can also trigger the Event manually to run immediately.
Triggering the Event manually
1. Click the >> icon and click Event Manager.
The Event Manager view appears.
2. In the Event Manager view, click the plus (+) sign beside Connections.
3. Double-click your ESP Server name.
The Events view for your ESP Server appears.
4. In the Prefix field, enter the prefix the test Application is grouped under, and click
List.
A list of the events under the specified prefix appears.
5. Right-click the test Application name Quick and click Trigger.
The Trigger the Event dialog appears.
6. Leave now in the Schedule criteria field (because you will trigger the Event
immediately) and select Submit Application on hold.
7. Click OK.
Step 3: Monitor your workflow
Viewing the Application
1. Click the >> icon and click Monitor.
The Application View view appears.
2. In Application View, click the plus (+) sign beside ESP Servers.
3. Right-click your ESP Server name and click Subscribe Active.
A plus (+) sign appears beside the ESP Server name.
50 ESPD-5.0-AG-02

4. Click the plus (+) sign beside the ESP Server name.
All active Applications that you have access to appears.
5. Click the plus (+) sign beside the test Application name Quick.
The QUICK folder expands, and a folder for each Application generation appears.
6. Double-click the test Application generation.
A graphical view of the test Application appears.
Monitoring the Application
Monitor the jobs in the graphical view. One by one the jobs start and end, and status
information is updated. Some of the jobs may go into a WAITING state because they
have built-in time delays. You should see all jobs in a COMPLETE state within a few
minutes. Once the final job goes into a COMPLETE state, your setup is successful.
As jobs in an Application pass through different states, the job label indicates the job’s
state and the border surrounding the job icon changes color.
• Jobs with a blue border are in a COMPLETE state.
• Jobs with a green border are in an EXEC state (the job is running).
• Jobs with a red border are in a TROUBLE state.
If the job label indicates AGENTDOWN, it means that ESP Agent is not running or
that Cybermation ESP: dSeries cannot contact ESP Agent. Ensure the Topology entries
for ESP Agent match what you specified during installation. If you set up Strong
Encryption for this Agent, ensure the encryption key is the same on ESP Agent and
Cybermation ESP: dSeries.
If a job goes into a SUBERROR state, it usually means the path to the command file
is wrong.
Setting up strong encryption between ESP System Agents and
ESP Server
You can set up strong (256-bit) encryption between ESP System Agents and ESP
Server. Support for strong encryption is only available with Release 7 ESP System
Agents.
Important: The high security option for ESP Server and ESP System Agent is
subject to export controls. To determine whether you are eligible for
this option, contact Cybermation.
ESPD-5.0-AG-02 51

Section–Setting up strong encryption between ESP System Agents and ESP Server
To set up strong encryption between ESP Agents and ESP Server, complete the
following steps.
1. Set up strong encryption on ESP Agent. 52
2. Enable strong encryption for ESP Agent in the ESP Server
topology.
3. Restart ESP Agent. 53
4. Test the encryption between ESP Server and ESP Agent. 54
Note: You must install the ESP Server High Security Option.
Set up strong encryption on ESP Agent
53
After you install the standard edition of ESP System Agent R7, you run the
strongEncrypt executable file you obtain from Cybermation.
To set up strong encryption on ESP Agent
1. Obtain the strongEncrypt executable file for ESP System Agent R7 from
Cybermation.
2. Stop ESP Agent if it is running.
3. Run the strongEncrypt executable file:
• On UNIX:
At the command prompt, type ./strongEncrypt.bin -i console
• On Windows, double-click the strongEncrypt.exe file.
Note: The installation program prompts you for the path to ESP Agent. Make
note of the path. You use this path in step 4.
4. Use a command prompt and change to the ESP Agent installation directory.
5. Run the CybKeygen utility that the strongEncrypt file installed.
• On UNIX:
Type CybKeygen.sh 0xkey strong
• On Windows:
Type cybkeygen.bat 0xkey strong
where key is the strong encryption key. This key must be 16 to 64 characters
long. You can specify up to 64 alphanumeric characters, using any digit and letters
A through F only.
52 ESPD-5.0-AG-02

Note: Make note of your new encryption key. You need this key when you enable
strong encryption of ESP Agent in the ESP Server topology.
Running the CybKeygen utility does the following:
• Converts the encryption key defined in the agentparm.txt file
(security.cryptkey parameter) and creates cryptkey.txt.
• Sets the value of the security.cryptkey parameter in the
agentparm.txt file to the path of the cryptkey.txt.
• Installs a utility called CybKeygen.
Enable strong encryption for ESP Agent in the ESP Server topology
You use the ESP Desktop Client Admin perspective to configure ESP Agent. The key
you specified for ESP Agent using the CybKeygen utility and the key you specify
using the ESP Server topology must be the same. If the keys are different, ESP Server
and ESP Agent cannot communicate and you receive an AGENTDOWN state when you
try to run workflow.
To enable strong encryption for ESP Agent in the ESP Server topology
4. In the Topology view, right-click ESP Agent and select View Properties.
5. Change the value of these parameters:
• Encryption Key — Enter the encryption key you created for ESP Agent using the
CybKeygen utility. Do not enter the "0x" used as the prefix when you
changed the key using the CybKeygen utility.
• Strong Encryption Enabled — Select true.
6. To accept the changes, click Update.
Restart ESP Agent
After you have set up strong encryption on ESP Agent and enabled strong encryption
in the ESP Server topology, restart ESP Agent.
To restart ESP Agent
1. On the ESP Agent machine, change to the ESP Agent installation directory.
2. At the command prompt, enter the following command to stop ESP Agent:
• On UNIX
./cybAgent -s
• On Windows
cybAgent -s
ESPD-5.0-AG-02 53

Section–Removing ESP Agent from ESP Server
3. Enter the following command to start ESP Agent:
• On UNIX
./cybAgent &
• On Windows
cybAgent -a
Test the encryption between ESP Server and ESP Agent
You can run and monitor a simple Application, like the VERIFY Application
packaged with ESP Server, to test the communication between ESP Server and ESP
Agent.
Note: If you use the VERIFY Application, make sure you change the ESP Agent name
to the ESP Agent you are testing.
Troubleshooting
When there is a communication problem between ESP Server and ESP Agent, the
AGENTDOWN state appears for the jobs in the Monitor perspective. The following are
possible causes:
• ESP Agent is not started.
• ESP Server and ESP Agent have different encryption keys.
• The parameters in ESP Server’s Topology are different than the ones defined in
the agentparm.txt file. Make sure the values of parameters listed in the table
below are the same.
Topology agentparm.txt Value
Name agentname
Parent communication.managerid
Address communication.manageraddress
Port
communication.inputport
number
Removing ESP Agent from ESP Server
54 ESPD-5.0-AG-02

4. In the Topology view, right-click the ESP Agent you want to remove and select
Remove Agent.
The ESP Agent disappears from the Topology view.
Note: If you remove a parent ESP Agent that contains virtual ESP Agents, the parent
and all its virtual ESP Agents are removed. Also, if you remove all the virtual ESP
Agents from a parent ESP Agent, that parent is also removed.
Modifying ESP Agent configuration parameters
4. In the Topology view, right-click the ESP Agent whose properties you want to
modify and select View Properties.
5. Change the parameter values, as required.
For parameter descriptions, select the field and press F1.
6. To save your changes, click the save icon at the top right corner of the Agent view.
Note: For the changes to take effect, you must recycle (stop and restart) ESP Agent.
Changing the log level on ESP Agent
Dependency: ESP System Agent Release 7
You can change the log level on a remote ESP System Agent without restarting it. Log
levels specify the type of information to record in the ESP Agent log files, which help
in troubleshooting ESP Agent problems.
agentmsg control agentname(agentname) loglevel(2|3|4|5)
persistent(TRUE|FALSE)
agentname is the name of the ESP Agent whose log level you want to change.
Example
agentmsg control agentname(WINAGENT) loglevel(5)
persistent(TRUE)
ESPD-5.0-AG-02 55

Section–Modifying ESP Agent configuration parameters
Log levels
ESP Agent supports log levels 0, 1, 2, 3, 4, and 5, where level 0 provides the least
information and level 5 provides the most.
• Levels 0, 1, and 2 create logs of any errors including the receiver and transmitter
logs.
• Level 3 adds queues.
• Levels 4 and 5 add debugging information.
Level 2 is adequate for general, initial testing, and level 0 is adequate for production
unless problems arise requiring more details for troubleshooting.
For more information on the log files created for each log level, see the
troubleshooting chapter in the Cybermation ESP System Agent Administrator’s Guide.
Changing the log level permanently
The persistent operand enables you to change the log level permanently.
• If the change is not permanent (the persistent operand is set to FALSE), the
log level is changed for the current session only. The log level is reset to the level
defined in the agentparm.txt file the next time ESP Agent is restarted.
• If the change is permanent (the persistent operand is set to TRUE), the
log.level parameter in the agentparm.txt file is updated with the new log
level. A backup copy of the original agentparm.txt file is created with the
name agentparm.txt.manager.<date_time_stamp>.txt.
Defining ESP Agent users
If an ESP Agent user specified in a job definition requires a password, such as
Windows, SAP, PeopleSoft, FTP, and database users do, you must define the user to
ESP Server. This procedure does not apply to UNIX and Oracle users.
To define an ESP Agent user
4. In the Topology view, right-click ESP Agent you want to add the user to and select
View Properties.
The ESP Agent view appears.
5. Click the Users tab.
6. Click Add.
The Add Agent User dialog appears.
56 ESPD-5.0-AG-02

7. Complete the required fields: User ID, Password, and Confirm Password.
8. Click Update.
Changing an ESP Agent user’s password
To change an ESP Agent user’s password
4. In the Topology view, right-click ESP Agent you want to change a user’s password
for and select View Properties.
5. Click the Users tab.
6. Select the user and click Change Password.
The Change password dialog appears.
7. Complete the required fields and save.
Configuring the z/OS ESP Agent
To use the z/OS ESP Agent, you need to specify the encryption key the z/OS ESP
Agent uses to communicate with ESP Server.
Note: In an ESP High Availability configuration, the z/OS ESP Agent requires PTF
SU02174 to run z/OS workflow.
To configure the z/OS ESP Agent’s encryption key in the ESP Server topology
4. In the Topology view, right-click the z/OS ESP Agent you want to configure and
select View Properties.
5. In the Encryption key field, enter the encryption key that is defined for the
COMMCHAN initialization parameter in the z/OS ESP Agent's Agent definition
data set.
Note: All z/OS ESP Agents must use the same encryption key to communicate
with ESP Server.
ESPD-5.0-AG-02 57

Section–Controlling ESP Agents
Related procedures
• To add the z/OS ESP Agent to the ESP Server network topology, see “Add ESP
Agent to the ESP Server Topology” on page 35.
• For information on configuring an ESP Agent definition data set, see the ESP
System Agent IBM z/OS Installation and Configuration Guide.
Controlling ESP Agents
Use ESP Agent control commands to control ESP Agents from a client machine.
Enter the following ESP Agent commands from the Command Console.
Command Description Syntax
shutdown Shuts down ESP Agent after all
workload has completed
refresh Reloads the ESP Agent security file agentmsg control
clrfiles Clears the ESP Agent log files agentmsg control
flush Purges all pending messages for the
specified ESP Agent
quiesce Holds all messages to be sent to the
named ESP Agent. To resume message
sending, use the restart command.
restart Resumes sending messages to the named
ESP Agent. Used following quiesce.
Shutting down an ESP Agent
agentmsg control
agentname(agentname) shutdown
agentname(agentname) refresh
agentname(agentname) clrfiles
agent agentname(agentname) flush
agent agentname(agentname)
quiesce
agent agentname(agentname)
restart
You can shut down an ESP Agent currently processing workflow using the shutdown
command. ESP Agent will shut down and all workflow will continue running.
However, ESP Agent cannot track the workflow states.
To shut down an ESP Agent
agentmsg control agentname(agentname) shutdown
agentname is the name of the ESP Agent you want to shut down.
58 ESPD-5.0-AG-02

Clearing ESP Agent receiver messages
ESP Agent receiver messages are messages sent to an ESP Agent to tell it what
workflow needs to be processed. These messages are queued to await processing. By
issuing the flush command, you can clear these pending messages.
agent agentname(agentname) flush
agentname is the name of the ESP Agent whose messages you want to clear.
This command clears all workload processing messages in the queue.
Holding ESP Agent receiver messages
The quiesce command holds all ESP Agent receiver messages in the queue until you
enter the restart command.
agent agentname(agentname) quiesce
agentname is the name of the ESP Agent whose receiver messages you want to
hold.
The command holds all ESP Agent receiver messages in the queue until you enter
the restart command.
Resuming message sending to an ESP Agent
The restart command resumes sending messages the quiesce command previously
held.
ESPD-5.0-AG-02 59

Section–Controlling ESP Agents
agent agentname(agentname) restart
agentname is the name of the ESP Agent whose messages you want to resume
sending.
The command releases all messages the quiesce command previously held.
60 ESPD-5.0-AG-02

Establishing and Controlling Security
• About ESP Server security
• Working with users
• Working with groups
• Summary of security permissions
• Setting up your ESP Server security network
ESPD-5.0-AG-02 61

Section–About ESP Server security
About ESP Server security
ESP Server security is maintained through a set of security profiles. A security profile
can represent a user or a group (a collection of users). Security profiles have
permissions associated with them. For example, they determine access levels to
Applications and ESP Server topology information.
Users
You define users with a user ID and password. You then grant them certain
permissions that determine their access within ESP Server.
Predefined users
When you first install ESP Server, the installation program creates two predefined
users: ADMIN and SCHEDMASTER. You must use these users to connect to ESP
Server to perform post-installation tasks. When you create new users, these predefined
users serve as models for security permissions.
ADMIN user
The ADMIN user contains the required permissions for administering ESP Server
and is associated with the ADMINGRP group. The ADMIN’s default password is
admin.
SCHEDMASTER user
The SCHEDMASTER user contains the required permissions for scheduling
workflow and is associated with the SCHEDGRP group. The SCHEDMASTER’s
default password is schedmaster.
Related topics
• “Creating a user” on page 66
• “Creating a group” on page 69
Groups
You use groups to define the same set of permissions for different users. Once you
assign permissions to a group, you can then associate users with that group. All users
in a particular group share the permissions that belong to that group. Groups are
useful for users who share common duties and activities.
62 ESPD-5.0-AG-02

Chapter 5–Establishing and Controlling Security
Predefined groups
When you first install ESP Server, it creates the following predefined groups:
• ADMINGRP
• EVERYONE
• OPERGRP
• SCHEDGRP
Use these groups as models for other groups that you create.
ADMINGRP
The ADMINGRP group contains the required permissions for administering ESP
Server. Users associated with this group can
• View, add, and modify topology information
• View, add, and modify security profiles
• View, add, modify, lock, and unlock resource definitions
• Use a resource in an Application
• Add, change, and delete job definitions in the VERIFY Application
• Lock and unlock the VERIFY Application
• Download, display, and modify the VERIFY Application
• Run the VERIFY Application
• Issue commands against jobs in the VERIFY Application
• Insert jobs into the VERIFY Application
• Display and update the VERIFY Event
• Issue commands against the VERIFY Event
The ADMIN user belongs to this group.
EVERYONE
Every user automatically belongs to the EVERYONE group. Users associated with
this group can
• Read the SYSTEM calendar
• Use terms defined in the SYSTEM calendar
ESPD-5.0-AG-02 63

Section–About ESP Server security
OPERGRP
The OPERGRP group contains permissions needed by operators to do their work.
Users associated with this group can
• Display any Alert definition.
• Download and display any Application.
• Run any Application.
• Issue commands against jobs in all Applications.
• Insert jobs into any Application.
• Display any Event.
• Issue commands against all Events.
SCHEDGRP
The SCHEDGRP contains permissions needed by schedulers to do their work. Users
associated with this group can
• View, add, delete, lock, unlock, and modify
• Any Alert definition
• Any Application
• Any Calendar
• Any resource definition
• Any Event
• Add, modify, and delete any job definitions in any Application
• Run work on any ESP Agent
• Issue ESP Agent control commands to any ESP Agent
• Use any user ID on any ESP Agent
• Reference any calendar in an Event
• Use an Application during run time
The SCHEDMASTER user belongs to this group.
Related topics
• “Creating a group” on page 69
• “Adding, changing or removing group permissions” on page 69
Permissions
Permissions determine what type of access a user or group has to a particular element
of ESP Server. You can also use permissions to restrict access to specific things. For
example, you can restrict access to a specific Application.
64 ESPD-5.0-AG-02

Permissions can contain two types of access:
• Alter, Update, or Read access
• Allow or Deny access
With Allow or Deny access, you can use Deny to create exceptions to a user or
group’s normal access. For example, if a user needs to have access to all Calendars
except the PAYCAL Calendar, you can give the user Allow access to
CALENDAR.*, but create a permission with a Deny access called
CALENDAR.PAYCAL.
You add permissions to users and groups to define their security access. You can add
permissions to a user or group when you first create them, or you can add them later.
User vs. group permissions
Sometimes a user belonging to group can contain permissions that contradict the
group permissions. For example, a user with Allow access to AGENT.A1UNIX may
belong to a group with a Deny permission for AGENT.A1UNIX.
Also, in the case of permissions with Alter, Update, and Read access, a user may have a
higher access level than the group. For example, a user may have Alter access to
ADMIN.Security Files and belong to a group with Read access to ADMIN.Security
Files.
In these cases, the user permission always overrides the group permission. The user in
the group with a Deny permission for AGENT.A1UNIX has Allow access to that ESP
Agent, and the user who belongs to the group with Read access to ADMIN.Security
Files has Alter access.
Conventions for permissions
Permissions follow a standard convention in this guide:
permission.value (accesslevel)
• permission is the name of the permission.
• value defines what the permission affects. In the Security view, you select value
from a dropdown menu when you add a permission to a user or group. You can
use an asterisk(*) in the value field of most permissions to indicate that the value
affects all aspects of the permission.
• accesslevel defines the type of security access this permission allows.
Depending on the type of permission, you can specify the following:
• Alter, Update, or Read
• Allow or Deny
ESPD-5.0-AG-02 65

Section–Working with users
Working with users
Creating a user
When you first create a user, you can add permissions to it, or add it to groups as you
create it, or you can modify the user’s details later.
To create a user
3. Open the Security view.
4. Click the Add new user icon.
5. On the New User tab, complete the following fields:
• User ID — The user’s user ID. Each user ID must be unique. The first
character must be alphabetic, and the user ID cannot exceed 20 characters.
User IDs convert to uppercase as you type them.
• User Name — An optional user’s name
• Password — The user’s password. The first character must be alphabetic, and
the password cannot exceed 32 characters. Passwords are case-sensitive and
must be different than the user ID.
• Confirm Password —Enter the password again.
6. To add the user to a group, select a group under Available Groups and click Add.
7. To assign the user permissions, do the following:
a. Click the Permission tab.
b. Click Add.
The Add Permissions dialog appears.
c. In the Permission type field, select the permission you want to add.
d. In the Value column, type the permission’s value.
To specify multiple values, use a wildcard (*). For example, Application name
set to PAYROLL* matches all Applications that begin with PAYROLL.
e. In the Access section, select the access level for the permission.
For Alter, Update, and Read, selecting the highest level of access also selects the
levels below. For example, Alter access grants alter, update, and read access.
f. Click OK.
The permission is added to the user. Repeat the previous step until you have
added all the permissions the user needs.
8. To add the user, click Update.
66 ESPD-5.0-AG-02

Adding, changing or removing user permissions
4. Right-click the user you want to change permissions for and select View Details.
5. Click the Permissions tab.
6. To add a permission, do the following:
a. Click Add.
b. In the Permission type field, select the permission you want to add.
c. In the Value column, type the permission’s value.
d. In the Access section, select the access level for the permission.
e. Click OK.
7. To change a permission, do the following:
a. Select the permission you want to change.
b. Click Edit.
c. In the Edit permission dialog, make the required changes and click OK.
8. To remove a permission, do the following:
a. Select the permission you want to remove.
b. Click Remove.
c. Click Yes.
9. When finished, click Update.
Adding a user to a group
4. Right-click the user you want to change permissions for and select View Details.
5. On the Groups tab, select the group and click Add.
• To select multiple groups, press the Shift key while you select.
• To copy a group list from an existing user, use the Copy group list from user field.
6. Click Update.
ESPD-5.0-AG-02 67

Section–Working with users
Removing a user from a group
4. Right-click the user you want to change and select View Details.
5. On the Groups tab, in the Connected Groups list, select the groups you want to
remove and click Remove.
6. Click Update.
Changing a user’s name
4. Right-click the user you want to change and select View Details.
5. In the User Name field, enter the name and click Update.
Removing a user from the ESP Server topology
4. Right-click the user you want to remove and select Remove User.
5. Click Yes.
Note: Removing a user does not remove any groups associated with it.
Related topics
• “Users” on page 62
• “Groups” on page 62
• “Summary of security permissions” on page 72
• “Resetting a user’s password” on page 12
68 ESPD-5.0-AG-02

Working with groups
Creating a group
4. Click the Group tab.
5. Click Add new group.
6. On the New Group tab, complete the following fields:
• Name — Mandatory group name. Each group must have a unique name. A
group name must start with an alphabetic character and cannot exceed 20
characters.
• Description — Brief description of the group. The first character must be
alphabetic. The description cannot exceed 40 characters.
7. To add users to the group, select a user under Available Users and click Add.
Tip: To copy a user list from an existing group, use the Copy user list from group field.
8. To assign the group permissions, do the following:
a. Click the Permission tab.
b. Click Add.
c. On the Add Permissions tab, in the Permission type field, select the permission
you want to add.
d. In the Value column, type the permission’s value.
e. In the Access section, select the access level for the permission.
f. Click OK.
The permission is added to the group. Repeat the previous step until you have
added all the permissions the user needs.
Tip: To copy a permissions list from an existing group, use the Copy permission list
from group field.
9. To add the group, click Update.
Adding, changing or removing group permissions
ESPD-5.0-AG-02 69

Section–Working with groups
4. Click the Groups tab.
5. To add a permission, do the following:
a. Right-click the group and select View Details.
b. Click the Permissions tab.
c. Click Add.
d. In the Permission type field, select the permission you want to add.
e. In the Value column, type the permission’s value.
f. In the Access section, select the access level for the permission.
g. Click OK.
6. To change a permission, do the following:
a. Right-click the group and select View Details.
b. Click the Permissions tab.
c. Select the permission you want to change.
d. Click Edit.
e. In the Edit permission dialog, make the required changes and click OK.
7. To remove a permission, do the following:
a. Right-click the group you want to remove and select Remove Group.
b. Click Yes.
8. When finished, click Update.
Changing a group’s description
4. Click the Groups tab.
5. Right-click the group you want to change and select View Details.
6. Make the required changes, and click Update.
Removing a group from the ESP Server topology
To remove a group from the ESP Server topology
70 ESPD-5.0-AG-02

4. Right-click the group you want to remove and select Remove Group.
5. Click Yes.
Note: Removing a group does not remove the users associated with it.
Related topics
• “Users” on page 62
• “Groups” on page 62
• “Summary of security permissions” on page 72
ESPD-5.0-AG-02 71

Section–Summary of security permissions
Summary of security permissions
The following table summarizes the permissions you can add to users and groups.
Permission Determines access to Access Values See Page
ADMIN Network topology and security files Alter, Update, Read 72
AGENT Running workflow on an ESP Agent Allow, Deny 73
AGENTMSG ESP Agent control commands Allow, Deny 74
AGENTUSER ESP Agent user IDs Allow, Deny 75
ALERT Alert definitions Alter, Update, Read 76
APPL Application definitions Alter, Update, Read 76
APPLX Active Applications Allow, Deny 78
CALENDAR Calendars Alter, Update, Read 79
CMD Issuing commands from the
EVENT Events Alter, Update, Read 81
EVENTX Issuing commands against an Event Allow, Deny 82
JAVASCRIPT JavaScript scripts Alter, Update, Read 83
RESOURCE Resources Alter, Update, Read 83
ADMIN
Command Console
Allow, Deny 80
Affects topology information and security files.
Syntax
ADMIN.Network Topology
Determines access to the topology.
This permission affects what a user can do in the Topology view. Tasks include
• Modifying ESP Server configuration and initialization parameters
• Modifying ESP Agent configuration parameters
• Adding and removing ESP Agents from your network
You can associate the following access values with this permission:
• Alter enables a user or group to view, update, add, and delete topology
information.
• Update enables a user or group to view and update topology information.
• Read enables a user to view topology information.
Note: To access the Topology view, a user requires Update or Alter access.
72 ESPD-5.0-AG-02

Examples: ADMIN.Network topology
Permission Definition
(Alter)
The user can view and modify ESP Server and ESP Agent
parameters as well as add and delete ESP Agents from the
network.
(Update)
The user can view and modify ESP Server and ESP Agent
parameters in the Topology view.
(Read)
The user can view topology information.
Syntax
ADMIN.Security Files
Determines access to ESP Server security files.
• Alter enables a user or group to view, update, add, and delete users and groups.
• Update enables a user or group to view and update users and groups.
• Read enables a user or group to view user and group information.
Note: To access the Security Profiles Manager, a user requires Update or Alter access.
Examples: ADMIN.Security Files
ADMIN.Security Files (Alter) • The user can view and modify users, groups, and
ADMIN.Security Files (Update) The user can view and modify users, groups, and
ADMIN.Security Files (Read) The user can view user and group information.
AGENT
permissions.
• The user can add users and groups and can create new
permissions.
permissions.
Determines whether a user or group can or cannot run work on an ESP Agent.
Syntax
AGENT.agentname
where agentname is the name of an ESP Agent in the topology. Use an asterisk in its
place to specify that all ESP Agents are affected by this permission.
For example, the permission AGENT.Unix1 determines whether a user or group can
or cannot run work on the ESP Agent named UNIX1. The permission AGENT.*
ESPD-5.0-AG-02 73

determines whether a user or group can or cannot run work on all ESP Agents in the
topology.
• Allow enables a user or group to run work on the ESP Agent specified in
agentname.
• Deny restricts a user or group from running work on the ESP Agent specified in
agentname.
Examples: AGENT usage
AGENT.A1* (Allow) The user can run work on any ESP Agent whose name
AGENT.A1UNIX (Deny) The user cannot run work on the ESP Agent named
AGENTMSG
begins with A1.
A1UNIX.
Determines whether a user or group can or cannot issue ESP Agent control
commands to an ESP Agent using the Command Console.
Syntax
AGENTMSG.CONTROL.agentname
where
• CONTROL indicates that this permission affects ESP Agent control commands
• agentname is the name of the ESP Agent that you are applying the permission
to. Use an asterisk to specify that all ESP Agents are affected by this permission.
For example, the permission AGENTMSG.CONTROL.AIXUNIX determines if a user or
group can or cannot issue ESP Agent control commands on the ESP Agent named
AIXUNIX. The permission AGENTMSG.CONTROL.* determines whether a user or
group can or cannot issue ESP Agent control commands on any ESP Agent in the
topology.
• Allow enables a user or group to run the specified ESP Agent control command
on the specified ESP Agent.
• Deny restricts a user or group from running the specified ESP Agent control
command on the specified ESP Agent.
Note: The AGENTMSG permission works with the CMD permission. To issue
ESP Agent control commands, a user also requires CMD.APPCMD* (Allow). For
more information on the CMD permission, see “CMD” on page 80.
74 ESPD-5.0-AG-02

Examples: AGENTMSG usage
AGENTMSG.CONTROL.A1*
(Allow)
AGENTMSG.CONTROL.
A1UNIX (Deny)
AGENTUSER
The user can issue ESP Agent control commands to all
ESP Agents whose name begins with A1.
The user cannot issue ESP Agent control commands to
the ESP Agent named A1UNIX.
Determines if a user can or cannot use a specific user ID on an ESP Agent.
Syntax
AGENTUSER.agentname.userid
where
• agentname is the name of an ESP Agent that this permission affects. Use an
asterisk to specify that all ESP Agents are affected by this permission.
• userid is the name of a valid ESP Agent user ID. Use an asterisk to specify that
all ESP Agent user IDs can be used. This value is case sensitive.
For example, the permission AGENTUSER.A1UNIX.User1 determines whether a
user can or cannot use the user ID User1 on the ESP Agent named A1UNIX. The
permission AGENTUSER.*.* determines if a user can or cannot use any user ID on
any ESP Agent in the topology.
• Allow enables a user or group to use the user ID specified in userid on the ESP
Agent specified in agentname.
• Deny restricts a user or group from using the user ID specified in userid on the
ESP Agent specified in agentname.
Examples: AGENTUSER usage
AGENTUSER.A1*.* (Allow) The user can use any user ID on any ESP Agent in the
topology whose name starts with A1.
AGENTUSER.A1*.User1
(Allow)
The user can use the user ID User1 on any ESP Agent in
the topology whose name starts with A1.
AGENTUSER.A1UNIX.*
(Deny)
The user cannot use any user IDs on the ESP Agent
A1UNIX.
ESPD-5.0-AG-02 75

ALERT
Determines a user or group’s access to Alert definitions.
Alerts are used to take action automatically when a job reaches a particular stage of
processing. This permission allows a user or group to view, define, modify, and delete
an Alert.
Syntax
ALERT.alertname
where alertname is the name of the Alert you are applying the permission to. Use
an asterisk to specify that the permission applies to all Alerts.
• Alter enables a user or group to create, delete, display, and update an Alert
definition
• Update enables a user or group to display and update an Alert definition.
• Read enables a user or group to read an Alert definition.
Examples: ALERT usage
APPL
ALERT.* (Alter) User can create, delete, and change any Alert definition.
ALERT.LATE_JOBS (Update) User can display and update the LATE_JOBS Alert
definition.
ALERT.FAIL* (Read) User can read any Alert definition starting with FAIL.
Determines what a user or group can do using Workload Editor.
With this permission, a user can create and view Applications as well as add, change,
and delete Applications and job definitions.
Syntax
APPL.applname
where applname is the name of an Application. Use an asterisk to specify the
permission determines access to all Applications.
For example, the permission APPL.PAYROLL determines access to the Application
PAYROLL. The permission named APPL.* determines access to all Applications.
76 ESPD-5.0-AG-02

• Alter enables a user or group to
• Create, delete, lock, and unlock an Application.
• Add, change, and delete Applications and job definitions.
• Unlock an Application definition locked by another user.
• Update enables a user or group to
• Lock or unlock an Application.
• Add, change, and delete Applications and job definitions.
• Read enables a user or group to download and display an Application.
Examples: APPL usage
APPL.* (Alter) The user can create and delete new Applications, change
Applications, and change job definitions in any
Applications.
APPL.PAYROLL (Update) Add, change and delete job definitions in the Application
called PAYROLL.
APPL.PAYROLL (Read) The user can view the Application called PAYROLL.
ESPD-5.0-AG-02 77

APPLX
Determines what a user or group can do in the Define perspective and also determines
which jobs a user can view in the Scheduled Activity report.
With this permission, a user or group can control and manage Applications, view
states, insert jobs, and retrieve spool files.
Syntax
APPLX.applname.jobname.jobqualifier.commandname
where
• applname is the name of the Application. Use an asterisk to specify that the
permission determines access to all Applications.
• jobname is the name of the job within the Application. Use an asterisk to specify
the permission affects all jobs within the Application.
• jobqualifier is the name of the job qualifier.
• commandname is either subscribe or getspoolfile. Use an asterisk to
specify the permission determines access to all Applications
The subscribe value enables a user or group to display the status of jobs within
Applications, but not control them.
The getspoolfile value enables a user or group to view the output of a job in its
spool file.
The permission APPLX.*.*.*.subscribe gives users subscription-only access to
all Applications. Users with this permission can view and monitor the status of jobs
and Applications using the Define perspective, but they can’t issue any commands (for
example, Complete, Bypass, Hold) to control the jobs and Applications.
The Administrator can restrict users or groups so they can only subscribe to one
Application in particular. To restrict users or groups to subscribe to one specific
Application, the Administrator uses the following permission syntax:
APPLX.applname.*.*.subscribe
where applname is the name of the Application the Administrator wants to restrict
subscription access to.
You can associate the following access values with the APPLX permission:
• Allow enables a user or group to run Applications or a job within an Application,
issue commands against a job within an Application, and insert jobs into the
Application. When the value subscribe is in the APPLX permission, the user or
group can view the status of jobs, but cannot issue commands against them.
• Deny restricts a user or group from running Applications or jobs within the
Applications, issuing commands against jobs, or inserting jobs.
78 ESPD-5.0-AG-02

Examples: APPLX usage
APPLX.* (Allow) The user can run all Applications and insert jobs in all
APPLX.PAYROLL.* (Allow) The user can run and insert jobs in the Application
APPLX.PAYROLL.PAYJOB1.
RUN1 (Allow)
APPLX.PAYROLL (Deny) The user cannot run and insert jobs into the Application
APPLX.*.*.*.subscribe (Allow) The user can view and monitor the status of jobs and
APPLX.PAYROLL.*.*.subscribe
(Allow)
APPLX.PAYROLL.*.*.
getspoolfile (Allow)
CALENDAR
Applications.
PAYROLL. The user can also view Scheduled Activity
reports that include this PAYROLL Application.
The user can only run and insert jobs in the Application
called PAYROLL, and can only affect the job
PAYJOB1.RUN1.
PAYROLL.
Applications using Workload Director. The user cannot
issue any commands (for example, Complete, Bypasss,
Hold) to control the jobs and Applications.
The user can only view and monitor the status of jobs that
belong to the PAYROLL Application.
The user can only view the spool file of jobs that belong to
the PAYROLL Application.
Determines a user or group’s access to Calendars.
With this permission, a user can create new Calendars, add holidays and special day
definitions, change remarks and workday settings, and reference a Calendar in Events.
Syntax
CALENDAR.calendarname
where calendarname is the name of the Calendar the permission defines access to.
Use an asterisk to indicate this permission applies to all Calendars.
For example, the permission CALENDAR.CALENDAR1 determines a user or group’s
access to the Calendar named Calendar1. The permission CALENDAR.* determines a
user or group’s access to all Calendars.
ESPD-5.0-AG-02 79

• Alter enables a user or group to
• Create and delete a Calendar.
• Add holidays and special days.
• Change remarks and workday settings.
• Display a Calendar’s content.
• Reference a Calendar in Events.
• Update enables a user or group to
• Add holidays and special days.
• Change remarks and workday settings.
• Read enables a user or group to
Examples: CALENDAR usage
CMD
CALENDAR.* (Alter) The user can create new Calendars, as well as view and
modify all Calendars.
CALENDAR.PAY* (Update) The user can view and modify any Calendar starting with
PAY.
CALENDAR.PAYROLL (Read) The user can display the Calendar called PAYROLL.
Determines whether a user or group can or cannot issue commands from the
Command Console.
Syntax
CMD.APPCMD*
• Allow enables a user or group to issue commands from the Command Console.
• Deny restricts a user or group from issuing commands from the Command
Console.
80 ESPD-5.0-AG-02

Examples: CMD usage
CMD.APPCMD* (Allow) The user can issue commands from the Command
CMD.APPCMD* (Deny) The user cannot issue commands from the Command
EVENT
Console.
Console.
Determines a user or group’s access to Event definitions.
With the EVENT permission, a user or group can create, view, and modify Event
definitions.
Note: The EVENT permission works with the APPL permission. To create and
update an Event, a user requires APPL (Alter) for the Application the Event refers to.
For more information on the APPL permission, see “APPL” on page 76.
Syntax
EVENT.eventprefix.eventname
where
• eventprefix is the prefix of the Event.
• eventname is the name of the Event.
• Alter enables a user or group to create, delete, display and update an Event.
• Update enables a user or group to display and update an Event.
• Read enables a user or group to display a specific Event.
Examples: EVENT usage
EVENT.PROD.* (Alter) The user can create, modify and view all Event definitions
with the PROD Event prefix.
EVENT.PROD.PAYROLL
(Update)
The user can display and modify the Event called
PAYROLL.
EVENT.* (Alter) The user can create, modify and view all Event
definitions.
EVENT.TEST.MRC* (Update) The user can display and modify any Event that begins
with MRC, with the Event prefix of TEST.
EVENT.* (Read) The user can display all Events.
ESPD-5.0-AG-02 81

EVENTX
Determines if a user or group can or cannot issue commands against an Event and
determines which Events are included in the Scheduled Activity Report file.
Syntax
EVENTX.eventprefix.eventname
where
• eventprefix is the prefix of the Event.
• eventname is the name of the Event.
• Allow enables a user or group to issue commands to the Event.
• Deny restricts a user or group from issuing commands to the Event.
Examples: EVENTX usage
EVENTX.* (Allow) The user can issue commands against all Events.
EVENTX.PROD.* (Allow) The user can issue commands against all Events with the
prefix PROD.
EVENTX.PROD.PAYROLL
(Deny)
The user cannot issue commands against the Event
PAYROLL, with the prefix, PROD.
EVENTX.*.MYJOBS (Allow) The user can issue commands against all Events called
MYJOBS. MYJOBS can have any prefix.
82 ESPD-5.0-AG-02

JAVASCRIPT
Determines a user or group’s access to JavaScript scripts used in scheduling.
This permission enables a user or group to view, modify, or create JavaScript scripts.
Syntax
JAVASCRIPT.javascriptname
where javascriptname is the name of a JavaScript script.
• Alter enables a user or group to create, delete, display and update a JavaScript
script.
• Update enables a user or group to display and update a JavaScript script.
• Read enables a user or group to use a JavaScript script in an Application.
Examples: JAVASCRIPT usage
JAVASCRIPT.* (Alter) The user can create JavaScript scripts as well as view and
JAVASCRIPT.
DATEVARIABLES (Update)
JAVASCRIPT.ODDJOBS
(Read)
RESOURCE
modify all existing scripts.
The user can view and modify the JavaScript script named
DATEVARIABLES.
The user can view the JavaScript script, named
ODDJOBS, in Applications.
Determines a user or group’s access to resources used in scheduling.
This permission enables a user or group to view, modify, or create resource definitions.
Syntax
RESOURCE.resourcename
where resourcename is the name of a resource. Use an asterisk to associate this
permission with all resources.
• Alter enables a user or group to create, delete, display and update a resource
definition.
• Update enables a user or group to display and update a resource definition.
• Read enables a user or group to use a resource definition in an Application.
ESPD-5.0-AG-02 83

Section–Setting up your ESP Server security network
Examples: RESOURCE usage
RESOURCE.* (Alter) The user can create new resource definitions as well as
view and modify all existing resource definitions.
RESOURCE.LOWPRIO
(Update)
The user can view and modify the resource definition
called LOWPRIO.
RESOURCE.DB2 (Read) The user can use the resource definition, DB2, in
Applications.
Setting up your ESP Server security network
To ensure proper setup, use the following guidelines when you set up new users and
groups at your installation:
• Before you define security profiles, analyze your security needs to determine the
similarities between different users. You will then have a rough idea of your needs
for users and groups.
• You can create groups that contain common permissions used by collections of
users.
• You can copy and modify the predefined users and groups if you need to create
security profiles with similar permission requirements.
• Maintain an organized set of naming conventions for your security profiles. For
example, you could organize your security profiles based on user location or job
description.
Example scenarios
This section contains some example scenarios that you may find helpful in setting up
your own ESP Server security network.
Scenario 1
This scenario shows how you can set up a simple security system using only the
predefined users and groups.
The following table contains a list of staff members and their roles.
Name Function
Andrea Administrator
Barry Administrator
Chantal Scheduler
84 ESPD-5.0-AG-02

Name Function
Dean Scheduler
Erin Scheduler
Bob Scheduler
Fred Operator
Gail Operator
Hugh Operator
Ingrid Operator
Jerry Operator
To set up this security scenario
1. Open the Security Profiles Manager.
2. Select Users from the main window.
3. Click Add.
The Add User dialog appears.
4. Fill in the User ID, User name, Password, and Confirm password fields using the
information in the following table.
User ID User name Password Confirm
Password
A_ANDREA Andrea a1 a1
A_BARRY Barry b2 b2
S_CHANTAL Chantal c3 c3
S_DEAN Dean d4 d4
S_ERIN Erin e5 e5
S_BOB Bob b6 b6
O_FRED Fred f7 f7
O_GAIL Gail g8 g8
O_HUGH Hugh h9 h9
O_INGRID Ingrid i10 i10
O_JERRY Jerry j11 j11
The user IDs in this scenario use the following naming convention:
• Administrator user IDs begin with A_. This prefix is followed by the user’s
name, for example, A_Andrea.
• Scheduler user IDs begin with S_. This prefix is followed by the user’s name,
for example S_CHANTAL.
• Operator user IDs begin with O_. This prefix is followed by the user’s name,
for example O_FRED.
ESPD-5.0-AG-02 85

5. To add these user IDs to groups, copy the group lists from the predefined users
using the information below.
User ID Copy Group List from User...
A_ANDREA ADMIN
A_BARRY ADMIN
S_CHANTAL SCHEDMASTER
S_DEAN SCHEDMASTER
S_ERIN SCHEDMASTER
S_BOB SCHEDMASTER
Because there is not a predefined user ID for operators, add the following user IDs
to the group OPERGRP:
• O_FRED
• O_GAIL
• O_HUGH
• O_INGRID
• O_JERRY
6. Once you have assigned groups to all the users, you can now add permissions. To
add permissions to the user IDs, copy the permission lists from the predefined
users using the information below.
User ID Copy Permissions from User...
A_ANDREA ADMIN
A_BARRY ADMIN
S_CHANTAL SCHEDMASTER
S_DEAN SCHEDMASTER
S_ERIN SCHEDMASTER
S_ERIN SCHEDMASTER
S_BOB SCHEDMASTER
7. Define permissions for operators for remaining User IDs.
8. Notify the users of their user IDs and passwords. Request that they change their
passwords immediately.
Scenario 2
This scenario builds on the previous scenario. It shows a typical ESP Server
installation and illustrates most ESP Server security features. Following this scenario
are some examples that show some maintenance situations relative to this scenario.
86 ESPD-5.0-AG-02

Specifications
In this scenario
• The company head office is located in Toronto with branches in New York and
London. A different set of ESP Agents is installed in each branch.
• Two administrators and a master scheduler are located in Toronto. The master
scheduler needs access to everything at both a scheduling and operating level.
• There is one scheduler located in Toronto and one each in New York and London.
These schedulers work exclusively on their own branches’ data. The policy is that
schedulers can only operate for test Applications.
• There are three operators in Toronto and one each in New York and London.
• There is one tape drive resource in each branch (Toronto, New York, and
London). Only the branch operators can control the tape drives.
• One of Toronto’s operators is the only person authorized to run payroll jobs.
• The training department periodically conducts operator training in Toronto and
requires new users with authorization to run a set of training jobs, and to view all
jobs running at every branch.
The following table summarizes the staff organization.
User Name Position Location Security Requirements
Andrea Administrator Toronto • Administrate and view
everything
Barry Administrator Toronto • Administrate and view
everything
Chantal Master Scheduler Toronto • Schedule all work
• Run all work
Dean Scheduler Toronto • Schedule Toronto work
• Run Toronto test work
Bob Scheduler New York • Schedule New York work
• Run New York test work
Erin Scheduler London • Schedule London work
• Run London test work
Fred Operator Toronto • Run Toronto work
• Run payroll work
• Control Toronto tape drive
Gail Operator Toronto • Run Toronto work
Hugh Operator Toronto • Run Toronto work
ESPD-5.0-AG-02 87

Ingrid Operator New York • Run New York work
• Control New York tape drive
Jerry Operator London • Run London work
• Control London tape drive
Training ID, as
needed
Operator trainee Toronto • Run training work
• Monitor all work
This scenario uses the following naming conventions for users, groups, and
permissions:
• User IDs in this scenario use the following naming convention:
• Administrator user IDs begin with A_
• Scheduler user IDs begin with S_
• Operator user IDs begin with O_
• City codes will be used for the names of most elements of ESP Server. The city
codes are as follows:
• Toronto: TOR_
• New York: NY_
• London: LON_
• ESP Agent names in the topology will use the city code. For example, all ESP
Agents at the Toronto location will start with TOR_.
• Application names will use the city code. The exception to this is payroll
Applications, which will start with PAY, and training Applications, which start
with TRN. Test Applications use the city code followed by TST.
• Events and Event prefixes will use the city code. The exceptions are payroll Event
prefixes, which start with PAY, test Events, which start with TST, and training
Event prefixes, which start with TRN.
• Calendar names, Resource names, and Alert names will use the city code.
Implementation
Creating groups
ADMIN1
Position: Administrators
To create the ADMIN1 group
1. Create a new group, ADMIN1.
2. Copy all permissions to ADMIN1 from the predefined group, ADMINGRP.
88 ESPD-5.0-AG-02

3. Add the following permissions:
• ALERT.* (Read)
• APPL.* (Read)
• CALENDAR.* (Read)
• EVENT.*.* (Read)
• Resource.*.* (Read)
TOR_SCHED1
Position: Toronto Schedulers
To create the TOR_SCHED1 group
1. Create a new group, TOR_SCHED1.
2. Copy all permissions to TOR_SCHED1 from the predefined group,
SCHEDGRP.
3. Update the following permissions
• AGENT.* (Allow)
• ALERT.* (Alter)
• APPL.* (Alter)
• APPLX.* (Allow)
• CALENDAR.* (Alter)
• EVENT.*.* (Alter)
• EVENTX.*.* (Allow)
to the following:
• AGENT.TOR_* (Allow)
• ALERT.TOR_* (Alter)
• APPL.TOR_* (Alter)
• APPLX.TOR_TST*.* (Allow)
• CALENDAR.TOR_* (Alter)
• EVENT.TOR_*.* (Alter)
• EVENTX.TOR_TST*.* (Allow)
TOR_OPGRP1
Position: Toronto Operators
To create the TOR_OPGRP1 group
1. Create a new group, TOR_OPGRP1.
2. Copy all permissions to TOR_OPGRP1 from the predefined group, OPERGRP.
ESPD-5.0-AG-02 89

3. Update the following permissions
• ALERT.* (Read)
• APPL.* (Read)
• APPLX.* (Allow)
• EVENT.*.* (Read)
to the following:
• ALERT.TOR_* (Read)
• APPL.TOR_* (Read)
• APPLX.TOR_* (Allow)
• EVENT.TOR_*.* (Read)
• EVENTX.TOR_*.* (Allow)
4. Add the following permissions:
• RESOURCE.TOR_TAPE (Alter)
• CMD.APPCMD* (Allow)
• AGENT.TOR_* (Allow)
TOR_OPRTRAIN
Position: Operator Trainee
To create the TOR_OPTRAIN group
1. Create a new group called TOR_OPTRAIN.
2. Copy all permissions to TOR_OPTRAIN from the predefined group,
OPERGRP.
3. Update the following permissions:
• APPLX.* (Allow)
to the following:
• APPLX.TRN* (Allow)
• EVENTX.TRN*.* (Allow)
4. Add the permission CMD.APPCMD* (Allow)
90 ESPD-5.0-AG-02

Creating groups for New York and London
Once groups for Toronto have been created, you can now create groups for New York
and London.
To create groups for New York and London
1. Create the following groups:
• NY_SCHED1
• LON_SCHED1
• NY_OPGRP1
• LON_OPGRP1
2. Copy the permissions for each new scheduler group from TOR_SCHED1 and
the permissions for each new operator group from TOR_OPGRP1.
3. Modify the permissions of the new groups to reflect the new city codes. For
example, in NY_OPGRP1, when you copy the permissions from
TOR_OPGRP1, you must change ALERT.TOR_* (Read) to ALERT.NY_*
(Read).
Creating users
You have now created all the groups required. You must now create users based on the
information in the job summary table. Most of the permissions the users will need are
already defined in their respective groups, but you will need to customize some users
based on some exact criteria in their security requirements.
To create users
1. Create the following users using the table below for their User IDs, user name,
passwords, and group association.
User ID User Name Password/
Confirm
Password
Groups
A_ANDREA Andrea a1 ADMIN1
A_BARRY Barry b2 ADMIN1
S_CHANTAL Chantal c3 TOR_SCHED1
NY_SCHED1
LON_SCHED1
TOR_OPGRP1
NY_OPGRP1
LON_OPGRP1
S_DEAN Dean d4 TOR_SCHED1
S_BOB Bob e5 NY_SCHED1
S_ERIN Erin f6 LON_SCHED1
O_FRED Fred g7 TOR_OPGRP1
ESPD-5.0-AG-02 91

User ID User Name Password/
Confirm
Password
Groups
O_GAIL Gail h8 TOR_OPGRP1
O_HUGH Hugh i9 TOR_OPGRP1
O_INGRID Ingrid j10 NY_OPGRP1
O_JERRY Jerry k11 LON_OPGRP1
Note: The user, S_CHANTAL belongs to all groups because, as master scheduler,
she needs access to everything.
2. Add the following permissions to O_FRED, who needs to run payroll jobs:
• APPLX.PAY* (Allow)
• EVENTX.PAY* (Allow)
3. Notify users of their user ID and password. Request that they change their
passwords immediately.
Maintenance examples
The following examples are based on changes made to the above scenario.
New employee
Kirk has joined the company as an operator. He will work in New York, but first he
will be trained in Toronto for three months.
Creating a user profile for Kirk
1. For the training period, set the user as follows.
User ID User Name Password/Confirm
Password
Groups
O_KIRK Kirk l11 TOR_OPTRAIN
2. Inform Kirk of his user ID and password and request that he change his password.
3. When he assumes his position in New York, remove him from TOR_OPTRAIN
group and add him to NY_OPGRP1.
Employee leaving
Fred is leaving the company. Delete him from the user list and, because he was the
only user allowed to run payroll Applications, you need to inquire about who will
replace him and move the APPLX.PAY* (Allow) and EVENTX.PAY* (Allow)
permissions to the new user.
92 ESPD-5.0-AG-02

Employee transfer
Gail is promoted from operator to scheduler. She will stay in New York. Create a new
user ID called S_GAIL and add it to the group NY_SCHED1. Delete the user
O_GAIL. It is possible Gail will combine her old and new duties during a transition
period. You may want to assign S_GAIL to the NY_OPGRP1 group temporarily.
New department
The company expands and opens a branch in Los Angeles. The staffing will be as
follows.
Leslie Scheduler Los Angeles • Administrate Los Angeles
Michael Operator Los Angeles • Run Los Angeles work
Helen Operator Los Angeles • Run Los Angeles work
The city code for Los Angeles is LA_.
installation
• Schedule Los Angeles
work
• Run Los Angeles test
work
• Control Los Angeles tape
drive
To set up security for the new department in Los Angeles
1. Create the groups, LA_SCHED1 and LA_OPGRP1. Copy and modify the
permissions from TOR_SCHED1 and TOR_OPGRP1, respectively.
2. Create the following users.
User ID User Name Password/Confirm
Password
Groups
S_LESLIE Leslie m12 LA_SCHED1
O_MICHAEL Michael n13 LA_OPGRP1
O_HELEN Helen o14 LA_OPGRP1
3. Add the following permissions to the user S_LESLIE, to give her access to
administrative functions:
• ADMIN.Network Topology (Alter)
• ADMIN.Security Files (Alter)
ESPD-5.0-AG-02 93

94 ESPD-5.0-AG-02

Handling Cybermation ESP Server Log
Files
• About log files
• Changing a log’s location or name
• Creating an audit log report
• Filtering messages sent to trace logs
• Summary of filter IDs
ESPD-5.0-AG-02 95

Section–About log files
About log files
ESP Server maintains three log file types that store diagnostic and auditing
information:
• Trace logs
• Automated Framework Message logs
• Audit logs
The trace log (tracelog.txt) stores communication messages between
Cybermation ESP system components and maintains debugging information used
primarily for diagnostic purposes.
The AFM log (afmlog.txt) stores communication messages between ESP Server,
ESP Agents, ESP Desktop Client and ESP Web Client.
The audit log records user input. ESP Server creates a new audit log every day. You
cannot change the frequency ESP Server creates the audit log. By default, ESP Server
names the audit log audit.YYYYMMDD.txt, where YYYYMMDD is the log date.
Unlike the other logs, the audit log is encrypted. You cannot use ESP Server to
automatically archive or clear the audit log. You can create an HTML and Comma
Separated Values (CSV) report using the auditlog export command in the
Command Console.
Log maintenance
By default, ESP Server performs an automatic archive, or rotation, of all its log files at
midnight. During the rotation, ESP Server archives the log files, creating new files in
the LogFiles directory. ESP Server includes a timestamp in the filename of the
archived log, indicating when ESP Server archived the file.
Related topics
• “Archiving server log files” on page 139
• “Clearing server log files” on page 141
• “Clearing server.log files (UNIX systems only)” on page 143
Filter IDs
Each message ESP Server sends has an associated filter ID. Filter IDs enable you to
filter the messages ESP Server writes to logs. When you apply filter IDs to a log, ESP
Server logs all messages with filter ID numbers equal to the specified filter IDs. By
default, ESP Server sets the filter IDs of the logs to 0.
Note: ESP Server logs exception messages automatically. Exception messages do not
have filter IDs associated with them.
96 ESPD-5.0-AG-02

Chapter 6–Handling Cybermation ESP Server Log Files
Changing a log’s location or name
By default, ESP Server maintains the logs in the following directory:
• On UNIX: <installDir>/Resources/LogFiles
• On Windows: <installDir>ResourcesLogFiles
You can change a log file’s location and name by editing the
espresso.properties file.
To change a log file’s location or name
1. Open the espresso.properties file located in ESP Server installation
directory.
You can edit the espresso.properties file using your operating system’s text
editor.
2. Edit the log file’s targets field.
• cybtracelog.targets — The trace log’s file location
• cybafmlog.targets — The AFM log’s file location
• cybauditlog.targets — The audit log’s file location
Example: Changing the name and location of the trace log file
A user changed the name and location of the trace log file by modifying the
cybtracelog.targets field of the espresso.properties file. The cybtracelog.filterids
field specifies the filter IDs applied to the log. The name and location changes are in
bold.
cybtracelog.filterids=0
cybtracelog.targets=/u1/Espresso/Logs/Preferredtracelog.txt
ESPD-5.0-AG-02 97

Section–Creating an audit log report
Creating an audit log report
The audit log report contains every user-initiated ESP Server command. To create an
audit log report, you use the auditlog export appcmd. This command creates an
audit log in CSV format and a report in html format.
For each command a user issues, the audit log records the following information:
• Date and time the user issued the command
• User ID that issued the command
• Command type
• Command name
• Command message (AFM)
Note: To export the audit log, you must have administrative privileges.
To generate an audit log report
4. Issue the following command:
auditlog export path(directory_path) name(name)
[startdate(YYYYMMDD)] [enddate(YYYYMMDD)]
where
• directory_path is the full directory path on the server where you want to
export the audit log and generate the report.
• name is the name you want to use for the audit log and audit report.
ESP Server names the audit log name.log (in CSV format) and the report
name.html.
Note: The name can contain any allowable filename character determined by the
operating system where ESP Server is installed.
• startdate and enddate are optional parameters.
If you omit the start and end dates, ESP Server exports the audit log of the current
day, for example auditlog export path(/export/home/usr)
name(today).
If you enter only the start date, ESP Server assumes the end date is the current day,
for example auditlog export path(/export/home/usr)
name(Mar15)startdate(20050315).
98 ESPD-5.0-AG-02

Note: If you enter an end date, you must enter a start date.
If you enter a start date and an end date, ESP Server exports the audit log between
the two dates, for example auditlog export path(/export/home/usr)
name(Mar15to31)startdate(20050315)enddate(20050331).
Filtering messages sent to trace logs
To reduce the number of messages written to logs, apply filter IDs to the logs. You can
apply temporary filter IDs or permanent filter IDs.
Applying temporary tracelog filter IDs
You can add filter IDs temporarily using the filterid command in the Command
Console. These filter IDs apply until you restart ESP Server. Use this method to
monitor specific messages for a limited time. You can temporarily add and remove a
single filter ID, multiple filter IDs, or a range of filter IDs to a log file.
To add temporary filter IDs to a trace log
tracelog filterid(nnnn)
where
nnnn is the number of a valid filter ID. For multiple filter IDs use
(nnnn, nnnn). For a range of filter IDs, use (nnnn-nnnn)
To remove temporary filter IDs from a trace log
tracelog filterid(-nnnn)
where
nnnn is the number of a valid filter ID. For multiple filter IDs use
(-nnnn, -nnnn). For a range of filter IDs, use (-nnnn-nnnn)
ESPD-5.0-AG-02 99

Section–Filtering messages sent to trace logs
Examples: Applying temporary tracelog filter IDs
• tracelog filterid(909)adds filter ID 909 to the trace log
• tracelog filterid(23,909)adds filter IDs 23 and 909 to the trace log
• tracelog filterid(955-957)adds filter IDs 955, 956, and 957 to the
trace log
Examples: Removing temporary tracelog filter IDs
• To remove filter ID 909 from the trace log, enter
tracelog filterid(-909)
• To remove filter IDs 23 and 909 from the trace log, enter
tracelog filterid(-23,-909)
• To remove filter IDs 900 to 905 from the trace log, enter
tracelog filterid(-900-905)
Applying permanent tracelog filter IDs
You can add filter IDs permanently by modifying the espresso.properties file.
These filter IDs apply after you restart ESP Server. You can permanently add and
remove a single filter ID, multiple filter IDs or a range of filter IDs to a log file.
To apply a permanent filter ID to a trace log
1. Open the espresso.properties file located in the ESP Server installation
directory.
You can edit the initialization parameter file using your operating system’s text
editor.
2. Edit the trace log file’s cybtracelog.filterids field.
Example: Applying permanent tracelog filter IDs
A user has permanently added filter IDs to the trace log by modifying the
cybtracelog.filterids field of the espresso.properties file. The
cybtracelog.targets field specifies the name and location of the trace log
affected by the filter IDs. The filter ID change is in bold.
cybtracelog.filterids=0,604
cybtracelog.flush=true
cybtracelog.targets=<installDir>/Resources/LogFiles/tracelog.txt
100 ESPD-5.0-AG-02

Summary of filter IDs
The following filter IDs apply to ESP Server.
Filter IDs Informational Messages From...
0 Lowest-level messages including exception messages
1 Common library server functions
5 Common library utilities
10 Performing synchronization
11 The publish/subscribe framework (for example, TimerPop)
13 The library database
14 The communication framework
15 Directing Events
17 Processing Email requests
18 Informational messages from administering ESP Server licenses
19 Subscriptions and publications of scheduled Events
33 The Application Registry framework (for internal use only)
37 Communication between the Command Console and ESP Server
47 Relational database actions
48 SNMP handling
501 The Configuration Server
502 Processing Configuration Server parameters
503 Common utilities used by the Configuration Server (for internal use only)
504 Ready for processing regular commands
505 Management for commands entered through the Command Console
506 The communications for the Configuration Server
510 Managing the Configuration Server data sources
511 Configuration Server tag manager (for internal use only)
512 Configuration Server event notification framework used by the tag manager
(for internal use only)
514 Messages received from ESP Desktop Client users
515 End of session
526 Input message timings
601 The Scheduler Server
602 Utilities used by the Scheduler Server
603 The Scheduler Server publish/subscribe framework (for internal use only)
604 Errors encountered by processing commands entered from the Command
Console
606 Scheduler Server management of Application definitions
(Sheet 1 of 3)
ESPD-5.0-AG-02 101

Section–Summary of filter IDs
Filter IDs Informational Messages From... (Continued)
607 Communication framework of the Scheduler Server
610 The Scheduler Server processing TDR definitions
611 Scheduler Server management of Event definitions
612 Scheduler Server management of Calendar definitions
613 Scheduler Server timer framework (for internal use only)
617 Messages accepted by an input conversation
618 Messages queued at the end of a conversation
622 Time publisher status at warm start initialization
628 Processing of Alerts
629 Scheduler Server management of scheduled activities
701 ESP Desktop Client
702 Utilities used by the Workstation Server
703 The Command Console
707 Messages exchanged between the ESP Desktop Client and the Workstation
Server
708 Informational messages from ESP Desktop Client session subscription
901 The Manager
902 Utilities used by ESP Server Manager
903 Managing the topology
904 The publish/subscribe framework (for example, TimerPop)
905 Managing jobs in the Manager
906 Manager commands entered from ESP Desktop Client
907 Processing commands entered from the Command Console
909 Processing internal commands
910 The communications for the Manager
912 Email notifications from the Manager
914 Processing publish/subscribe criteria (for internal use only)
916 Processing of resource acquisition within the Manager
919 Accepted input messages in a conversation
920 Messages queued to the input queue on exit
922 Workflow objects at warm start initialization
923 Relationship publisher manager at warm start initialization
924 Release publisher manager at warm start initialization
925 Time publisher manager at warm start initialization
926 Output message queue at initialization
927 Output message queue manager destinations
(Sheet 2 of 3)
102 ESPD-5.0-AG-02

Filter IDs Informational Messages From... (Continued)
1001 The Resource Server
1002 The Resource Server Utilities
1005 Communication framework of the Resource Server
1006 Resource Server management of resource definitions
1007 Resource Server resource acquiring/returning processing
1008 Processing commands and state changes in the resource components
1009 Storing and retrieving ESP High Availability/warm-start related status
(Sheet 3 of 3)
ESPD-5.0-AG-02 103

Section–Summary of filter IDs
104 ESPD-5.0-AG-02

Administering ESP High Availability
• ESP High Availability terminology
• The ESP High Availability process
• Configuring ESP High Availability detection
• Changing the type of failback
• Switching Primary and Standby roles
• Converting to an ESP High Availability installation
• Verifying the ESP High Availability configuration
• Preventing auto connection to the Standby
ESPD-5.0-AG-02 105

Section–ESP High Availability terminology
ESP High Availability terminology
ESP High Availability is the ESP Server failure detection and recovery process for ESP
Server. The process involves switching workflow processing from one server (the
Primary) to a backup server (the Standby) when a failure occurs on the Primary.
The following terms describe ESP High Availability terminology:
Primary
Primary refers to the ESP Server that currently controls the workflow and interacts
with ESP Agents defined in the Topology view to run jobs.
Standby
Standby refers to the ESP Server that currently runs as a backup server. When ESP
High Availability occurs, the Standby becomes the Primary.
ESP High Availability recovery
ESP High Availability recovery (failback) refers to the workflow control returning to
the preferred server.
Preferred server
You specify which server is the preferred server during the installation. With
automatic failback, the preferred server (Preferred) refers to the server peer that
becomes the Primary when it starts up. If, after ESP High Availability has occurred,
the non-preferred server is Primary and the preferred server starts up, the preferred
server becomes the Primary and the non-preferred server becomes the Standby. With
manual failback, the preferred server does not take over at start up. You must issue a
changerole command for failback to occur.
106 ESPD-5.0-AG-02

Chapter 7–Administering ESP High Availability
The ESP High Availability process
A typical ESP High Availability configuration, as shown in the diagram below,
consists of two ESP Servers installed on separate machines. Both servers use the same
relational database management system (RDBMS) and shared file system.
During ESP Server startup
When an ESP Server starts up, it always begins in Standby mode. During startup, it
monitors the other ESP Server.
• If the started ESP Server detects that the other server is unavailable, that ESP
Server runs as the Primary.
• If the started ESP Server detects that the other server is running in Primary mode,
the server
• Becomes the Primary if it is the preferred server and automatic failback is
configured.
• Remains as the Standby if it is not the preferred server or automatic failback is
not configured.
• If the started ESP Server detects that the other server is running in Standby mode
(because both servers started at the same time), a vote takes place between the
servers to decide which one will become the Primary. In this case, the preferred
server becomes the Primary.
ESPD-5.0-AG-02 107

Section–The ESP High Availability process
At any time, you can issue a changerole command from either server to have the
servers change modes. After issuing the command, the Primary becomes the Standby
and the Standby becomes the Primary.
During ESP High Availability detection
During normal processing, the Primary runs the workflow and the Standby monitors
the Primary for failure. Since the Primary and Standby share the same database, no
data replication or extra processing takes place. The Standby monitors the Primary or
monitors the database upon monitoring failure.
ESP High Availability occurs if either of the following situations occur:
• The Primary machine goes down.
• ESP Server on the Primary terminates.
To determine if failure has occurred, the ESP High Availability detection mechanism
uses a dual- stage failure detection process.
Stage 1 monitoring: Heartbeat
If both servers are running, the Standby periodically contacts the Primary based on
the configured heartbeat.
If the servers can communicate directly with each other, monitoring continues
according to the configured frequency. If the servers cannot communicate directly,
stage 2 monitoring takes place.
Stage 2 monitoring: Relational database
In stage 2 monitoring, ESP Server uses the relational database as the communication
method. Since both servers require database access to operate, ESP Server uses the
database as the final arbiter to determine whether failure has occurred on the Primary.
During stage 2 monitoring, the Primary periodically updates a table in the database.
The Standby monitors (polls) this table to verify that the Primary is still active. Before
each database poll, the Standby attempts to contact the Primary (stage 1 monitoring).
You can configure how often the Primary updates the database and how long before
the Standby monitors the database.
108 ESPD-5.0-AG-02

If the Standby detects the Primary through updates to the database, ESP High
Availability does not occur. The Standby continues to monitor. If the Standby cannot
detect the Primary after the specified polling interval, ESP High Availability occurs.
During ESP High Availability
Assuming the Standby is running at the time of failure, ESP High Availability is
automatic.
If both stage 1 and stage 2 monitoring fail, ESP High Availability occurs as follows:
• The Standby performs a warm start.
• The Standby begins running the workflow.
• The Standby contacts ESP Agents to inform them to communicate with the server
• ESP Server on the Standby sends an SNMP message and email to notify you that
the Primary has failed and that the Standby is now running workflow as the
Primary.
During ESP High Availability recovery
After ESP High Availability has occurred, processing can resume on the preferred
server once the preferred server restarts. You can configure this failback to be
automatic or manual.
In automatic failback, once the preferred server restarts, it resumes its role as the
Primary. Upon starting, the preferred server sends a changerole request to the current
Primary. Upon receiving the change request, the current Primary quiesces the server
components and returns to Standby mode. Once the server returns to Standby mode,
the preferred server runs as the Primary.
ESPD-5.0-AG-02 109

Section–Configuring ESP High Availability detection
In manual failback, once the preferred server restarts, it runs in Standby mode. You
can issue a changerole command to either server. After issuing the changerole
command, the current Primary becomes the Standby and the current Standby
becomes the Primary.
Configuring ESP High Availability detection
You can configure ESP High Availability detection using the ESP Desktop Client
Topology view. ESP Server uses the ESP High Availability detection settings at the
following times:
• Upon startup to check whether the each server is running
• During normal operation. The Primary processes the workflow and the Standby
monitors the Primary.
To configure ESP High Availability detection
4. Right-click the ESP Server node and select Configure Shared Parameters.
5. Click the ESP High Availability tab.
6. Enable ESP High Availability by setting the Enable ESP High Availability field to true.
7. Configure these mandatory ESP High Availability settings.
• Frequency (in seconds) To Poll Server — The frequency at which the Standby
monitors the Primary during stage 1 monitoring (heartbeat method).
• Primary Server Frequency (in seconds) To Update Database — The update
frequency. This value sets the frequency at which the Primary updates the
database (relational database method).
• Standby Server Factor To Poll The Database — The polling factor. ESP Server uses
this value to compute the polling interval, which is the elapsed time between
stage 1 failure and the time the Standby monitors the database.
Note: The Primary Server Frequency and the Standby Server Factor to Poll the Database
properties work together to determine the polling interval as follows:
Polling Interval = Primary Server Frequency x Standby
Server Factor to Poll the Database
Tip: The polling interval determines the ESP High Availability latency — the time
it takes ESP Server to recognize failure has occurred on the Primary and begin to
switch to the Standby. You may want to increase the polling interval to give you
110 ESPD-5.0-AG-02

time to fix the problem on the Primary. Or you may want to keep the polling
interval low to minimize the amount of time ESP Server is down (but increasing
the chance ESP High Availability occurs).
8. If desired, set the Enable Automatic Failback to Preferred Server field to true.
• With automatic failback, control of the workflow automatically fails back to
the preferred server. The non-preferred server becomes the Standby.
• With manual failback, you can force control of the workflow to fail back to
the other server by issuing a command.
9. Click OK.
Related topic
“Recycling the server” on page 20
Changing the type of failback
You can change the type of failback from manual to automatic or automatic to
manual. Failback can occur at the following times:
• When the preferred server starts (or restarts after ESP High Availability) — If
failback is automatic, control of the workflow automatically fails back to the
preferred server. The non-preferred server becomes the Standby.
• At user request — If failback is manual, you can force control of the workflow to
fail back to the other server by issuing a command.
To change the type of failback
5. Click the ESP High Availability tab.
6. In the Enable Automatic Failback to Preferred Server field, change its value.
• true — At startup, the preferred server becomes the Primary.
• false — At startup, the preferred server remains the Standby if the non-preferred
server is running.
7. Click OK.
ESPD-5.0-AG-02 111

Section–Switching Primary and Standby roles
Related topic
“Recycling the server” on page 20
Switching Primary and Standby roles
After you issue the changerole command, the current Primary becomes the
Standby and the current Standby becomes the Primary.
To change the ESP Server role from Standby to Primary
changerole
Converting to an ESP High Availability installation
This section explains how to convert your existing stand-alone ESP Server installation
to an ESP High Availability installation. The process assumes you have one ESP
Server instance installed that is not enabled for ESP High Availability, and you are
making this instance the Primary.
To determine the minimum hardware and system requirements of a Primary and
Standby, refer to the Installing Cybermation ESP: dSeries guide. Use that guide to plan
the configuration parameters that you need as you follow the steps described in this
section.
The following sections show two configuration models for ESP High Availability
installations.
112 ESPD-5.0-AG-02

ESP High Availability configuration 1
In this configuration, you install ESP Server on one machine, which you designate as
the preferred server. You install ESP Server again on a different machine. The
preferred server acts as the Primary and the second server acts as the Standby. The
Primary and Standby use a shared-file system and relational database, which you
install on a separate machine.
Failover configuration 2
In this configuration, you install ESP Server on one machine, which you designate as
the preferred server. You install ESP Server again on a different machine. The
preferred server acts as the Primary and the second server acts as the Standby. The
ESPD-5.0-AG-02 113

Section–Converting to an ESP High Availability installation
Primary and Standby use a shared-file system you install on a separate machine. You
also install a primary database on its own machine and a standby database on its own
machine.
Setting up ESP High Availability
Complete these tasks to convert your existing installation to a ESP High Availability
installation.
1. Check the ESP High Availability requirements. 114
2. Stop ESP Server. 115
3. Set up a shared-file system. 115
4. Set up your Primary. 115
5. Start the Primary. 116
6. Install the Standby. 116
7. Start the Standby. 117
Check the ESP High Availability requirements
If you are configuring ESP High Availability, install the Standby on a different
machine than the Primary. The Standby machine’s system requirements are the same
as the Primary machine’s.
114 ESPD-5.0-AG-02

The system clocks on the two machines must be within 500 milliseconds of each
other.
Note: The systems synchronize when you connect them to a time server. You can also
check if the systems are synchronized by connecting to each one and checking the
time.
If you install the Primary and Standby in different time zones, in an ESP High
Availability situation ESP Server might run workload twice or skip scheduled jobs. To
prevent this problem, ensure the Primary and Standby use the same time zone.
You can only install one pair of primary and standby servers per ESP High Availability
configuration.
Stop ESP Server
Before stopping ESP Server, ensure that no jobs are currently running or active on the
ESP Server instance you want to configure as your Primary.
Set up a shared-file system
ESP Server uses a shared file system for ESP High Availability configurations. The
shared file system stores PSE Pro Object Database files.
Have your System or Network Administrator set up the shared file system required by
the Primary and Standby. When you install, both ESP Servers require access to this
shared file system. Ensure the user accounts under which the Primary and Standby
run have access to this shared location on the network.
Note: On average, a size of 10GB should be adequate for the shared file system.
Set up your Primary
1. Start the ESP Server installation program on your Primary machine.
2. Use the following table to guide you through the installation of the Primary.
Install Section Value to use
Installation Path ESP Server installation directory of the server
you want to designate as Primary
Existing Cybermation ESP Server
Installation
Choose I want to reinstall ESP Server and preserve
my existing configuration.
Select Backup Option Select Yes to backup your existing installation.
Choose Backup Folder Enter your backup folder or accept the default.
Configure database Select No.
ESP High Availability Select Yes.
ESPD-5.0-AG-02 115

Section–Converting to an ESP High Availability installation
3. When Local Server with ESP High Availability appears, do the following:
• To designate this ESP Server as the Primary, select Preferred Server.
• Enter a port number, if different than the default, and the path to your shared
directory. Record these values to use when you install the Standby.
Field Your Value
Peer Server Manager
Port
Shared Directory
4. When Failback Type appears, choose whether to enable automatic failback.
5. When ESP High Availability Settings, specify new settings or accept the defaults.
6. Complete the remainder of the installation.
Related topics
• For more information on the installation program, refer to the Installing
Cybermation ESP: dSeries guide.
• To understand automatic failback, see “Changing the type of failback” on
page 111.
• To understand the ESP High Availability detection settings, see “Configuring ESP
High Availability detection” on page 110.
Start the Primary
The Primary and Standby share a file that stores the shared properties used by the two
servers. To transfer the shared properties to the database, you must start the Primary
before you install the Standby.
Install the Standby
Install a second instance of ESP Server to serve as the Standby in your ESP High
Availability configuration.
To install the Standby
1. Start the ESP Server installation program on your Standby machine.
2. When you are prompted to configure ESP High Availability, select Y.
3. When Local Server with ESP High Availability appears, do the following:
• To designate this ESP Server as the Standby, ensure the Standby option is
selected.
• For the Peer Server Manager Port, enter the value you set for the Primary. Refer
to the value you recorded.
• For the Shared Directory, enter the path to your shared directory.
116 ESPD-5.0-AG-02

4. Complete the remainder of the installation.
5. When the installation is complete, ensure you have replaced your temporary
license.
Start the Standby
Start the Standby. Your Primary should already be started.
Verifying the ESP High Availability configuration
This section assumes you have successfully started both the Primary and Standby and
your default ESP Agent is running.
To verify the ESP High Availability configuration, complete the following steps.
1. Trigger and monitor the VERIFY Application on the Primary. 117
2. Start the SNMP Message Viewer. 117
3. Change the Primary and Standby roles. 118
4. Trigger and monitor the VERIFY Application on the Standby
(now acting as Primary).
118
Trigger and monitor the VERIFY Application on the Primary
1. Using ESP Desktop Client, connect to the Primary.
2. Using the Services perspective, open the Event view and trigger the
CYBERMATION.VERIFY Event.
3. Using the Monitor perspective, view the generation of the VERIFY Application.
The Application should complete successfully.
Start the SNMP Message Viewer
To verify that the Primary and Standby have changed roles, you need to start the
SNMP Trap Receiver.
1. If not connected, connect to the Primary using ESP Desktop Client.
3. Open the SNMP Message Viewer.
4. Click the Start SNMP receiver icon.
The Start SNMP Trap Receiver and Set Port dialog appears.
ESPD-5.0-AG-02 117

Section–Verifying the ESP High Availability configuration
5. In the Port Number field, enter the port number and click OK.
The SNMP Message Viewer begins capturing SNMP messages.
Change the Primary and Standby roles
1. If not connected, connect to the Primary using ESP Desktop Client.
changerole
Check the SNMP messages to verify that the Standby has become the Primary.
Related topics
For more information on SNMP ESP High Availability messages, see “About SNMP
messages” on page 122.
Trigger and monitor the VERIFY Application on the Standby (now
acting as Primary)
1. After the servers complete changing roles, connect to the Standby (now acting as
Primary).
2. Using the Services perspective, open the Event view and trigger the
CYBERMATION.VERIFY Event.
3. Using the Monitor perspective, subscribe with no filter so you can see active
Applications.
If you see the two completed generations of the VERIFY Application (triggered
on the Primary and Standby machines), you have successfully enabled ESP High
Availability.
4. To revert to the Primary (now acting as the Standby), use the Command Console
to issue another changerole command.
118 ESPD-5.0-AG-02

Preventing auto connection to the Standby
When the Primary fails over in an ESP High Availability installation, by default ESP
Desktop Client will automatically connect to the Standby. ESP Desktop Client
notifies you of the switch from the Primary to Standby through a message in its
Console View; otherwise, the switch is transparent.
You can set an option that allows you to connect to a different ESP Server when the
Primary fails. This feature is useful if, for example, you are using manual failback and
want to switch to a specific server.
To prevent auto connection to the Standby
1. In the Connections view, right-click the Primary connection and select Connect.
The Connect to ESP dialog appears.
2. Select the Prevent auto-connect on failover option.
Tip: If the option isn’t visible, click Details.
3. To connect to a different server, enter the address and port number for that server.
4. Enter the password and click OK.
ESPD-5.0-AG-02 119

Section–Preventing auto connection to the Standby
120 ESPD-5.0-AG-02

Monitoring SNMP Messages
You can use the SNMP Message Viewer to view SNMP messages regarding ESP
Server, ESP Agents, ESP High Availability, and Alerts.
• About SNMP messages
• Interpreting SNMP messages
• Changing the SNMP Manager settings
• Using third-party SNMP Managers
• Enabling SNMP messages from ESP System Agents
• Receiving SNMP messages
• Stopping the SNMP trap receiver
• Working with the SNMP Message Viewer
ESPD-5.0-AG-02 121

Section–About SNMP messages
About SNMP messages
ESP Server and SNMP-enabled ESP Agents use SNMP messages to notify users of
their activity. These messages can inform you of server startups and shutdowns, ESP
Agent inactivity or shutdown, and ESP High Availability messages. To handle SNMP
messages, you can configure the ESP Server default SNMP Message Viewer or a
different SNMP Manager.
ESP Server sends an SNMP trap to the SNMP Message Viewer or SNMP Manager
you configured
• Each time ESP Server starts or stops.
• Each time an ESP Agent starts or stops.
• When the Standby reaches the maximum number of consecutive, unsuccessful
polling attempts in an ESP High Availability-enabled configuration, indicating a
possible problem with ESP Server.
ESP Server can also generate user-defined SNMPmessages. For example, when a
Cybermation ESP job meets predefined criteria (such as the job starting, ending or
ending with a specific completion code), ESP Server can send an SNMP message to
the default SNMP Message Viewer or any SNMP Manager.
Note: If you are configuring the ESP High Availability Option, Cybermation
recommends you configure SNMP. If you are using a third-party SNMP Manager,
you can import a Management Information Base (MIB) description file that defines
the format the SNMP Manager uses.
Interpreting SNMP messages
The SNMP Message Viewer displays information in the following fields:
• Host Name
• Parameter 2
• Host IP Address
• Parameter 3
• Time Stamp
• Parameter 4
• Specific
• Parameter 5
• Parameter 1
Host Name
Host Name displays the host name of the machine where the Cybermation ESP product
is installed.
122 ESPD-5.0-AG-02

Chapter 8–Monitoring SNMP Messages
Host IP Address
Host IP Address displays the IP address of the machine where the Cybermation ESP
product is installed.
Time Stamp
Time Stamp displays the date and time the SNMP Message Viewer captured the
message.
Specific
Specific indicates the type of SNMP message.
2 generally indicates a startup message. In an ESP High Availability installation, 2 can
indicate a stage 2 failure.
4 generally indicates a shutdown message or ESP Agent inactivity. In an ESP High
Availability installation, 4 can indicate a stage 1 failure or an ESP Server role change.
Parameter 1
Parameter 1 indicates the Cybermation product name.
Parameter 2
Parameter 2 indicates the Cybermation product version and build number.
Parameter 3
Parameter 3 can indicate the following:
• ESP Server ID of the server that started, shutdown, or changed role
• ESP Agent name that started, shutdown or is inactive
Parameter 4
Parameter 4 indicates the IP address of the machine where the SNMP Manager is
installed and the port number the machine uses to receive SNMP messages.
ESPD-5.0-AG-02 123

Section–Changing the SNMP Manager settings
Parameter 5
Parameter 5 can indicate the following:
• Primary, Standby, or Standalone indicates the startup of ESP Server and its role.
• Stopped indicates ESP Server has shut down.
• Started, Shutdown, or Inactive indicates the state of an ESP Agent.
• Stage 1 Failure or Stage 2 Failed indicates the ESP High Availability detection stage.
• Running as Primary or Running as Standby indicates the ESP Server role in an ESP
High Availability installation.
Changing the SNMP Manager settings
The ESP Server installation program prompts for SNMP Manager settings. If you did
not configure SNMP during installation and want to enable SNMP, you need to
update the topology by modifying the SNMP Manager settings. You can configure
the settings for third-party SNMP Managers such as HP Openview.
To modify the SNMP Manager settings
5. Click the SNMP tab.
6. Modify the SNMP settings.
• Host address of SNMP Manager — The machine the SNMP Manager is installed
on. Specify the IP address in dotted-decimal or host name format.
• *Input port of SNMP Manager — The port number the SNMP Manager uses to
capture SNMP messages. The default is 162.
• Community of SNMP Manager — The SNMP Manager you are using determines
how messages are sent through your network. Specify public or private.
• Also send emails for SNMP messages — Specifies whether you want to receive
SNMP messages in email format. The default is false.
7. When you are finished making changes, click OK.
124 ESPD-5.0-AG-02

Using third-party SNMP Managers
If you use a third-party SNMP Manager, for example HP Openview, you can import
a Management Information Base (MIB) description file that defines the format the
SNMP Manager uses. The name of this file is cybermib.txt. On UNIX, for
example, you will find this file in the following directory: <installDir>/Shared/
Resources/snmp
where
• <installDir> represents your ESP Server installation directory
• <sharedDir> represents your ESP Server directory on the shared file system
The directory path on Windows is the same.
If you want to change the SNMP settings you entered during installation, such as to
use a different SNMP Manager or port number, you need to update the topology by
modifying the SNMP Manager settings. If you plan to use a Release 5 ESP System
Agent or higher to relay SNMP data, you also need to update the ESP Agent’s
agentparm.txt file to reflect the changes.
Enabling SNMP messages from ESP System Agents
This section only applies to Release 5 and higher ESP System Agents that have not
been configured for SNMP during their installation.
If you plan to use an ESP System Agent to relay SNMP data, you must complete the
following steps:
1. Enable ESP Agent to send SNMP traps and notifications.
a. Connect to ESP Server using ESP Desktop Client.
b. Open the Admin perspective.
c. Open the Topology view.
d. Right-click the ESP Agent you want to configure and select View Properties.
e. On the Properties tab, set the SNMP Enabled parameter value to true.
f. To save your changes, click Update.
2. Edit the ESP Agent’s agentparm.txt file to provide values for the following
parameters:
plugins.start_internal_N=management
management.snmp.mibfile=
management.snmp.host=
management.snmp.port=
management.snmp.community=
ESPD-5.0-AG-02 125

Section–Receiving SNMP messages
For more detailed instructions on changing a parameter to enable ESP Agent to send
SNMP traps, see “Modifying ESP Agent configuration parameters” on page 55.
For more information about ESP System Agent parameters in the agentparm.txt
file
• For Release 5 ESP System Agents, see Installing Release 5 ESP System Agents.
• For Release 6 ESP System Agents and higher versions, see the ESP System Agent
Administrator’s Guide for the respective release.
Receiving SNMP messages
To start receiving SNMP messages
4. Click the Start SNMP receiver icon.
The Start SNMP message receiver and set port dialog appears.
5. Enter the port number for the SNMP Manager and click OK.
Tip: To find the SNMP Manager’s port number, open the Topology view, click the
Server Shared Parameters > SNMP tab, and check the Input port of SNMP Manager field.
Stopping the SNMP trap receiver
Stopping the SNMP trap receiver disables the SNMP Message Viewer’s ability to
capture SNMP messages. Once stopped, however, you can still view and edit saved
messages.
To stop the SNMP trap receiver, click the Stop SNMP receiver icon.
126 ESPD-5.0-AG-02

Working with the SNMP Message Viewer
Use the icons on the SNMP Message Viewer’s toolbar to save, open, clear and print
messages.
Saving SNMP messages
You can save SNMP messages and work with them later. You can save the messages in
SNMP Message Viewer (.msg) format or in text (.txt) format.
Opening SNMP messages
If the SNMP trap receiver is running, you cannot open saved SNMP messages. You
must stop the receiver before you can open a file. Using the SNMP Message Viewer,
you can only open SNMP message files saved in the .msg format.
Clearing messages from the SNMP Message Viewer
You can remove selected messages from the SNMP Message Viewer or clear all
messages from it.
• To clear selected messages, use the Remove message icon.
• To clear all messages, use the Clear table icon.
Tip: You can hold down the Shift key to select a range of messages, or hold down the
Ctrl key to select several different messages at once.
Printing SNMP messages
You can print SNMP messages as they appear on your screen or you can preview and
modify the messages in text format before printing them.
To view the SNMP messages in text format before printing them
2. Click the Print Preview icon.
The messages display in text format. In text format, you can
• Use the Ctrl+C shortcut to copy the text from the log. For example, you may
want to paste the text into another document.
• Edit the displayed text. Any changes will not be saved and do not affect the
information in the SNMP message log itself.
ESPD-5.0-AG-02 127

Section–Working with the SNMP Message Viewer
128 ESPD-5.0-AG-02

Working with the ESP Server Database
• About your ESP Server database
• Changing the database connectivity properties
ESPD-5.0-AG-02 129

Section–About your ESP Server database
About your ESP Server database
ESP Server uses the database for ESP High Availability, history reporting, and
resource management.
Note: For configuration and administration instructions, refer to the product
documentation supplied by your database vendor.
ESP High Availability
In an ESP High Availability installation, both the Primary and Standby share the same
database. If the Primary goes down, the Standby takes over using the same database. If
the Primary database goes down, you can connect ESP Server to a different database.
History reporting
The database stores workflow information in its tables. You can use the database to
inspect the workflow information and produce detailed reports on workflow.
Resource management
The database stores the state of all defined resources, such as availability and activation
states. ESP Server uses this information to initialize the state of these resources during
a warm start.
• For more information about ESP High Availability, refer to chapter 7.
• For more information about history reporting and resource management, refer to
the Cybermation ESP: dSeries User’s Guide.
130 ESPD-5.0-AG-02

Chapter 9–Working with the ESP Server Database
Changing the database connectivity properties
You can change the following database connectivity properties using the setdbparm
utility.
Property name Description
database.maxconnections.allowed The maximum number of database connections
(connection pool) available to Espresso. Applications
request a connection, perform a database operation,
and then return the connection back to the pool. If
no connection is available, the application waits until
another a connection gets returned to the pool.
Oracle can accept up to 300 connections. The default
is 50.
database.minconnection The number of database connections (connection
pool) available to ESP Server when it starts. Based on
demand, ESP Server will add new connections to the
connection pool, up to the maximum specified by the
database.maxconnections.allowed
property.
jdbc.Driver The name of the JDBC driver ESP Server is using to
access the RDBMS
jdbc.URL The database URL, for example
jdbc:oracle:thin:@<host>:<port1521>:<sid>
rdbms.password The password of the user ESP Server uses to access the
ESP database
Note: If your ESP Server database password and
Oracle user password don’t match, ESP Server won’t
be able to connect to the database.
rdbms.type The type of relational database ESP Server uses
rdbms.userid The user ID ESP Server uses to access the ESP
database
relational.database.retry.attempts The number of times the ESP Server attempts to
connect to the relational database
relational.database.retry.interval The frequency in seconds at which the Espresso
Server attempts to connect to the relational database.
The default is 60 seconds.
Note: You should coordinate changes to your database with your database
administrator.
ESPD-5.0-AG-02 131

Section–Changing the database connectivity properties
To change the database connectivity properties
1. Run the setdbparm utility, which is located in the <installDir>/
Utilities directory.
• On UNIX: enter the following command at the prompt:
setdbparm property
• On Windows, enter the following command at the prompt:
setdbparm.bat property
where property specifies the database property you want to change.
2. At the prompt, enter the new value for the parameter you want to change.
132 ESPD-5.0-AG-02

Cybermation ESP: dSeries Maintenance
Procedures
This chapter provides maintenance procedures for ESP Server and ESP Agents. The
procedures are grouped into the following sections:
• Setting up a housekeeping Application
• ESP Server maintenance
• ESP Agent maintenance
ESPD-5.0-AG-02 133

Section–Setting up a housekeeping Application
Setting up a housekeeping Application
ESP Desktop Client is packaged with a sample Application, named housekeeping,
that contains the following jobs:
• CLEANUP removes log files, spool files, and .odb files that accumulate over time
• PURGE_COMPLETED clears completed jobs from the ESP Server completed jobs
repository
If you are working in a UNIX environment, you can modify and schedule this
Application to perform routine maintenance of your ESP Server.
Note: For Windows environments, use the housekeeping Application as a model and
change the job types to Windows.
To use the housekeeping Application
2. Use the Define perspective to open the housekeeping Application, located in
the ESP Desktop Client <installDir>/SampleApplications directory.
3. Edit the details for each job as follows.
134 ESPD-5.0-AG-02

Chapter 10–Cybermation ESP: dSeries Maintenance Procedures
Note: You can also add new jobs to run your own scripts.
• CLEANUP
Agent name — Enter the name of your default ESP Agent installed with ESP
Server.
Run frequency — Enter your schedule criteria. The default is run anyday.
Script/command name — Enter the path to the cleanup utility provided with
ESP Server. This utility is located in the <installDir>/Utilities
directory.
Arguments to pass — Enter the maximum age of the files you want to delete in
days. For example if you enter 7, the cleanup utility deletes files that are older
than 7 days.
For more information about the cleanup utility, see “Performing an
automated cleanup of ESP Server” on page 136.
• PURGE_COMPLETED
Agent name — Enter the name of your default ESP Agent installed with ESP
Server.
Run frequency — Enter your schedule criteria. The default is run anyday.
Script/command name — Enter the path to the appcmd utility provided with
ESP Server. This utility is located in the <installDir>/Utilities
directory.
Arguments to pass — Enter the following parameters separated by a space: host,
port, username, password, and the completedjobs purge appcmd. For example
espressop 7500 CLUSER cluser -appcmd "completedjobs
purge olderthan(now less 4 days)"
For more information about the appcmd utility, see “Clearing the ESP Server
completed jobs repository” on page 152.
4. To schedule the Application, open the default Date-Time/Manual Event and edit
the run frequency.
5. Upload the Application to the server.
ESPD-5.0-AG-02 135

Section–ESP Server maintenance
ESP Server maintenance
Related topics
The following maintenance procedures apply to ESP Server:
• “Performing an automated cleanup of ESP Server” on page 136
• “Resetting Application generations” on page 137
• “Clearing the ESP Server completed jobs repository” on page 138
• “Archiving server log files” on page 139
• “Clearing console.txt backup files” on page 140
• “Clearing server log files” on page 141
• “Clearing server.log files (UNIX systems only)” on page 143
Performing an automated cleanup of ESP Server
You can run the cleanup utility to remove the following files and folders that
accumulate over time:
• Default ESP Agent log files and spool files
• ESP Server log files located in the <installDir>/Resources/LogFiles
directory
• On UNIX installations, the ESP Server log files located in the <installDir>/
MonitorAndStatus directory
• On stand-alone ESP Server installations, the time-stamped object databases (.odb)
files located in the <installDir>/Shared/Resources/Database
directory, for example the script deletes dmmain.200509081013909.odb but
not dmmain.odb
To perform an automated cleanup of ESP Server
Run the cleanup utility, which is located in the <installDir>/Utilities
directory.
• On UNIX: enter the following command at the prompt:
cleanup.sh n
• On Windows, enter the following command at the prompt:
cleanup.bat n
where n specifies the maximum age of the files in days. For example, if you enter
cleanup.bat 9, the cleanup utility deletes files that are older than 9 days.
The cleanup process may take some time depending on the number of files it must
remove.
136 ESPD-5.0-AG-02

Resetting Application generations
As ESP Server processes workflow, Application generations continue to increase.
You can reset a single Application generation or all Application generations by issuing
the resetgen application command using the Command Console.
To reset Application generations
resetgen application(app_name)
app_name is the name of the Application you want to reset, such as
application(PAYROLL). Use * to reset all Application generations to 0.
ESP Server returns an error if the Application is active (not completed). Complete
the Application and re-enter the command.
If the Application is complete, ESP Server purges all completed generations and
resets the generation count to 0.
ESPD-5.0-AG-02 137

Clearing the ESP Server completed jobs repository
As ESP Server runs, it collects information about active and completed jobs. Your ESP
Server relational database stores this information in two tables: ESP_WSS_APPL and
ESP_WSS_JOB. To maintain performance, you must periodically clear these tables.
The following describes the options for clearing completed jobs:
completedjobs purge [olderthan(schedule_expression)]
[application(app_name[.gen_num])]
Keyword Description
none ESP Server purges all completed jobs.
olderthan
(schedule_expression)
Optional. Purges all jobs older than the schedule
expression. The schedule expression resolves to a single
time. For example, the expression "now less 24 hours"
resolves to a time 24 hours before the time you issue
this command. This command is only active at the
time you issue it. If you specify a future time, you
purge all completed jobs.
Note: If the schedule expression resolves to a day, ESP
Server uses the implicit time of midnight.
application
(app_name[.gen_num])
Optional. Purges all completed jobs or specified
generations of the named Application. For example, if
you specify 5, you purge the completed jobs in
generations 1, 2, 3, 4, and 5 of the named Application.
If you use the keyword olderthan with the
keyword application, you purge only those
completed jobs in the Application generations that
meet the schedule criteria.
For example, if you specify the Application name
VERIFY and a schedule expression of "now less than
24 hours", you purge all completed jobs in all
generations of the Application VERIFY that are 24
hours old or older.
Recommended frequency
Clear the ESP Server completed jobs repository after 10,000 jobs have completed.
Example: Clearing the ESP Server completed jobs repository
This example purges all applications older than 24 hours.
138 ESPD-5.0-AG-02

completedjobs purge olderthan(now less 24 hours)
Archiving server log files
By default, ESP Server automatically archives the trace and AFM logs. If you run
extremely heavy workflow, you might consider changing the default frequency for the
automatic archive, or you might want to perform a manual archive.
Note: ESP Server creates a new audit log every day. You cannot change this behavior.
Log files constantly increase in size because ESP Server continually writes to them. To
reduce the amount of information stored in these files, ESP Server performs an
automatic archive, or rotation, of all its log files. This automatic-archive process
reduces clutter in the active log files by creating a new log file on a frequent basis. ESP
Server stores the new file in the <installDir>/Resources/LogFiles (UNIX)
or <installDir>ResourcesLogFiles (Windows) directory, with a
timestamp indicating when ESP Server archived the file. ESP Server then clears the
active log file and continues logging new information to this file. You can also archive
active trace and AFM log files manually using the Command Console.
Automatically archiving log files
ESP Server uses the Log rotation frequency parameter to control the automatic-archive
frequency of the trace and AFM log files. By default, ESP Server uses "midnight",
which means that ESP Server automatically archives all log files every day at midnight.
To change the automatic-archive frequency, reset the Log rotation frequency parameter
using simple scheduling statements, for example, "12 am monday" or "every 3 hours".
To change the automatic-archive frequency
4. In the tree view, right-click the ESP Server node and select
Configuration Parameters > Shared Parameters.
5. In the Log rotation frequency field, enter a new frequency, for example, "every 3
hours".
6. Click OK.
7. Recycle the ESP Server.
ESPD-5.0-AG-02 139

Manually archiving active log files
The spin command archives the contents of an active trace or AFM log file into a new
file.
To archive an active log file
logname spin
where logname is the type of a valid log file (tracelog or afmlog).
For example, if you want to archive the active trace log, enter the following
command:
tracelog spin
Clearing console.txt backup files
If you use the Command Utilities packaged with ESP Server, each console command
creates a console.txt backup file that is date- and time-stamped, for example,
console.20040919163018.txt. ESP Server stores these console.txt files in the
directory you issue the command from. Over time, these files accumulate and you will
need to clear them.
To clear the console.txt backup files
• On UNIX, at the command prompt, type
rm console.*.txt
where the asterisk (*) is a timestamp wildcard.
• On Windows, delete the console.*.txt files.
140 ESPD-5.0-AG-02

Clearing server log files
In addition to archiving log files, you can permanently delete or clear trace or AFM
log files. You can set a parameter in ESP Server to automatically clear log files at a
specific archive frequency. You can also clear active log files manually using the
Command Console.
Automatically clearing log files
ESP Server uses the Clear logs after rotation parameter to control the clearing, or
deleting, of server log files. The default for clearing log files is false, which means ESP
Server does not delete logs after rotation; ESP Server backs up each log file using the
name of the log file and the current time.
To automatically clear log files
4. In the tree view, right-click the ESP Server node and select
Initialization Parameters > Shared Parameters.
5. Set the value of the Clear logs after rotation parameter to true.
After a warm start, ESP Server deletes the server log files at the frequency specified
by the Log rotation frequency parameter.
6. Click OK.
Manually clearing log files
The purge command clears the contents of the active or archived trace or AFM log
file.
The following describes the options for manually clearing a log file.
logname purge[(archived|all)]
Keyword Description
logname Name of the log
• tracelog — trace log
• afmlog — AFM log
ESPD-5.0-AG-02 141

Keyword Description
purge Clears the active log file
purge(archived) Removes the archived log files
Note: If you change the log file name after archiving,
this command only removes the files archived after the
name change.
purge(all) Clears the active log file and removes the archived log
files
Note: If you change the log file name after archiving,
this command removes the files archived after the
name change.
To clear the active log file
logname purge
For example, if you want to clear the active trace log file, enter the following
command:
tracelog purge
To clear the archived log files
logname purge(archived)
For example, if you want to clear the archived AFM log file, enter the following
command:
afmlog purge(archived)
To clear the active log file and its archived log files
142 ESPD-5.0-AG-02

logname purge(all)
For example, if you want to clear the active AFM log file, enter the following
command:
afmlog purge(all)
Clearing server.log files (UNIX systems only)
Each time you recycle ESP Server, the server backs up its server.log file. Recycling
the server routinely causes server.log files to accumulate. You need to clear these
files manually.
To clear server.log files
1. Change to your ESP Server installation directory.
2. Change to the MonitorAndStatus directory
cd MonitorAndStatus
3. At the command prompt, type
rm server.*.log
where the asterisk (*) is a timestamp wildcard.
ESP Agent maintenance
Related topics
The following maintenance procedures apply to ESP Agents:
• “Clearing ESP Agent log files manually” on page 144
• “Configuring ESP Agent to clear spool files automatically” on page 144
• “Clearing UNIX spool files using scripts” on page 145
• “Clearing Windows spool files using the clearspool command” on page 147
• “Clearing Agent nohup files (V2 UNIX Agents only)” on page 147
ESP Agent keeps a set of logs that you must clear periodically to maintain disk space
availability. The log files contain records of all messages between ESP Agent and the
Cybermation Host as well as internal messages. These files are located in the log
directory by default and are updated continually while ESP Agent is running. The
types and number of logs that are generated depend on the log.level parameter set
in the agentparm.txt file.
ESPD-5.0-AG-02 143

Section–ESP Agent maintenance
You can clear the log files automatically or manually.
Clearing ESP Agent log files manually
Use the agentmsg control command to manually clear all log files on ESP Agent, both
active and archived, with the extension .log.
agentmsg control agentname(agentname) clrfiles
agentname is the name of the ESP Agent whose log files you want to clear.
Configuring ESP Agent to clear spool files automatically
By default, ESP Agent does not clear the spool files. You can configure ESP Agent to
automatically clear the spool files regularly by modifying the agentparm.txt file.
1. Enable the spool file cleaner (off by default).
runnerplugin.spool.clean.enable=true
2. Specify the file expiration time. ESP Agent deletes spool files that are older than
this value. The default is 10D (10 days).
runnerplugin.spool.expire=<n><D|H|M|S>
where n is the time period and
• D — Days
• H — Hours
• M — Minutes
• S — Seconds
You cannot specify combinations of time periods. For example, 12D3H is not
valid. If you specify a number only, ESP Agent assumes days by default.
144 ESPD-5.0-AG-02

3. Specify the sleep interval. At every interval, ESP Agent checks for spool files that
meet the expiration time and deletes them. The default is 1D (1 day).
runnerplugin.spool.sleep=<n><D|H|M|S>
where n is the time period and
• D — Days
• H — Hours
• M — Minutes
• S — Seconds
You cannot specify combinations of time periods. For example, 12D3H is not
valid. If you specify a number only, ESP Agent assumes days by default.
Note: If this value is greater than the runnerplugin.spool.expire value,
ESP Agent ignores this value and checks the spool files at intervals specified by the
runnerplugin.spool.expire value.
Example: Deleting spool files older than 10 days
The following ESP Agent parameters configure ESP Agent to check the spool files
every 36 hours and delete spool files that are older than 10 days.
runnerplugin.spool.expire=10D
runnerplugin.spool.sleep=36H
Example: Checking spool files when the sleep interval is greater than the file
expiration time
Given the following parameters, ESP Agent ignores the two hour sleep interval set by
runnerplugin.spool.sleep. ESP Agent checks the spool files every 50 minutes
and deletes spool files that are older than 50 minutes as specified by
runnerplugin.spool.expire.
runnerplugin.spool.expire=50M
runnerplugin.spool.sleep=2H
Clearing UNIX spool files using scripts
You can clear UNIX spool files periodically using the clearspool and
deldirifempty (delete directory if empty) scripts.
1. Create the clearspool and deldirifempty scripts.
2. Schedule the clearspool script using Cybermation ESP, or run it manually.
The clearspool script deletes files that meet certain modification time criteria.
If the spool files are completely cleared, the clearspool script calls
ESPD-5.0-AG-02 145

deldirifempty. The deldirifempty script deletes empty directories within
the spool directory.
If you run clearspool from a Telnet session, ensure you switch to the directory
containing the spool files.
If you used the defaults when installing ESP Agent, the spool directory is called
spool.
The clearspool script assumes the spool directory is called spool in the
current directory. If not, supply the full directory path name in the environment
variable SPOOL.
Creating the clearspool and deldirifempty scripts
The following are sample scripts. You can have other file maintenance procedures.
1. Create a script called clearspool that contains the following code:
#! /bin/ksh
if [[ -z $SPOOL ]]
then
SPOOL=./spool
fi
find $SPOOL -type f -mtime +n -exec rm {} ;
find $SPOOL -depth -type d -exec /bin/ksh /script_path/
deldirifempty {} ;
• mtime n specifies the age of the files to be deleted, where
• +n — deletes files last modified more than n days.
• n — deletes file last modified exactly n days ago.
• -n — deletes files last modified less than n days ago.
Note: Put this script in the same directory as the cybAgent binary. Otherwise,
specify the full path for SPOOL. You cannot specify a symbolic-linked directory
for the SPOOL path.
2. Create the script called deldirifempty that contains the following code:
#!/bin/ksh
Dir=$(ls -A $1)
if [[ -z $Dir ]]
then
echo "deleting directory $1"
rmdir $1
else
echo "$1 is not empty"
fi
146 ESPD-5.0-AG-02

Example: Deleting files modified yesterday or earlier
In the following example, mtime is specified as +1 to delete files that were last
modified at least one day ago. The clearspool script then calls the
deldirifempty script, which deletes any empty spool subdirectories.
#!/bin/ksh
if [[ -z $SPOOL ]]
then
SPOOL=/AgentDirectory/spool
fi
find $SPOOL –type f –mtime +1 –exec rm {} ;
find $SPOOL –depth –type d -exec /bin/ksh /script_path/
deldirifempty {} ;
Note: $SPOOL cannot be symbolic-linked directories.
Clearing Windows spool files using the clearspool command
You can clear Windows spool files with the clearspool command. Use
clearspool in one of two ways:
• Schedule clearspool to run periodically in a Cybermation ESP Application
• Run clearspool manually by issuing the clearspool command from the
Windows command prompt
Running the clearspool command manually
1. Define the ESPAGENTDIR environment variable with the path to the ESP
Agent directory.
The ESP Agent directory must contain a valid agentparm.txt file.
2. At the command prompt, enter the clearspool command.
Example: Clearing spool files older than five days
This command deletes all files older than five days.
clearspool 5
Example: Displaying debugging messages
This command deletes all files older than 10 days and displays debugging messages to
the command prompt as it runs.
clearspool 10 debug
Clearing Agent nohup files (V2 UNIX Agents only)
This procedure applies to Version 2 UNIX Agents. When you use nohup as part of
the command to start the V2 Agent, the Agent creates a timestamped nohup file to
ESPD-5.0-AG-02 147

back up its console messages. If you recycle the Agents routinely, nohup files will
accumulate in the Agent directory. You will need to clear the Agent nohup files
manually.
Note: In newer versions of the UNIX Agent, the Agent stores the console messages in
its log files. When you use nohup as part of the command to start the Agent, the
Agent creates one nohup file. However, this nohup is empty, so there is no need to
clear it.
To clear UNIX Agent nohup files
1. Change to the Agent directory you want to clear.
2. At the command prompt, type
rm nohup.*.out
where * is a timestamp wildcard.
3. Repeat steps 1 and 2 for each Agent.
148 ESPD-5.0-AG-02

ESPD-5.0-AG-02 149

150 ESPD-5.0-AG-02

ESPD-5.0-AG-02 151

152 ESPD-5.0-AG-02

ESPD-5.0-AG-02 153

154 ESPD-5.0-AG-02

Command Console Commands
This chapter describes the commands you can enter from the Command Console and
how to issue appcmds using the Command Utility.
• Command definitions and syntax
• Issuing appcmd commands using the Command Utility
ESPD-5.0-AG-02 155

Section–Command definitions and syntax
Command definitions and syntax
The Command Console commands are grouped into four categories: ESP Agent
commands, log commands, ESP Server commands, and workflow commands.
ESP Agent commands
Note: In an ESP High Availability configuration, you can only issue the following
commands on the Primary.
Command Description Syntax Related Topics
agent Issues an ESP Agent
control command
agent
agentname(agentname)
flush|restart|quiesce
• “Clearing ESP Agent
receiver messages” on
page 59
• “Resuming message sending
to an ESP Agent” on
page 59
• “Holding ESP Agent
page 59
agentmsg control Issues an ESP Agent
control command
agentmsg control
agentname(agentname)
shutdown|refresh|clrfiles
• “Shutting down an ESP
Agent” on page 58
• “Clearing ESP Agent
page 59
• “Clearing ESP Agent log
files manually” on page 144
In the syntax column
• Italic indicates a variable.
• A vertical bar "|" indicates that you must specify either the keyword to the left of
the bar or the keyword to the right of the bar.
Log commands
afmlog filterid Applies filter ID numbers
to the ESP Server active
AFM log
afmlog filterid(nnn) “Applying temporary tracelog
filter IDs” on page 99
afmlog purge Clears the ESP Server
AFM logs
afmlog
purge[(archived|all)]
“Clearing server log files” on
page 141
afmlog spin Archives the ESP Server
active AFM log
afmlog spin “Archiving server log files” on
page 139
156 ESPD-5.0-AG-02

Chapter 11–Command Console Commands
auditlog export Creates an audit log in
Comma Separated Values
(CSF) format and a report
in html format
auditlog export
path(directory_path)
name(name)
[startdate(yyyyMMdd)]
[enddate(yyyyMMdd)]
“Creating an audit log report”
on page 98
display afmlog Displays the location and
file name of the ESP
Server AFM log
display afmlog
display auditlog Displays the location and
Server audit log
display auditlog
display tracelog Displays the location and
Server trace log
display tracelog
tracelog filterid Applies filter ID numbers
to the ESP Server active
trace log
tracelog filterid(nnn) “Applying temporary tracelog
filter IDs” on page 99
tracelog purge Clears the ESP Server
trace log
tracelog
purge[(archived|all)]
“Clearing server log files” on
page 141
tracelog spin Archives the ESP Server
active trace log
tracelog spin “Archiving server log files” on
page 139
• A pair of square brackets "[ ]" enclosing a keyword indicates that the keyword is
optional.
ESPD-5.0-AG-02 157

Section–Command definitions and syntax
ESP Server commands
about Shows the ESP Server version
and build number, as well as a
list of users connected to ESP
Server
about “Viewing a list of users
changerole Changes the ESP Server ESP
High Availability role
changerole “Switching Primary and
countlist Lists the total number of each
ESP artifact type in your system.
ESP artifact types are Agents,
Alerts, Applications, Calendars,
Events, Forecasts, Groups,
JavaScripts, Resources, and
Users.
countlist “Viewing a list of artifacts in the
licensestatus Displays the total number of
licenses available, the number of
licenses in use, and the
temporary licenses’ expiry date
licensestatus “Viewing your license status” on
memcheck Displays the total free memory
and maximum heap size
memcheck “Checking the server memory
stop Stops the ESP Server stop “Stopping ESP Server using the
In the syntax column, italic indicates a variable.
connected to the server” on
page 12
Standby roles” on page 112
system” on page 25
page 26
usage” on page 25
Command Console” on page 21
158 ESPD-5.0-AG-02

workflow commands
Note: In an ESP High Availability configuration, you can only issue the following
commands on the Primary.
completedjobs
purge
Purges completed jobs
• All jobs
• Those job older than
a scheduled time
• A particular
generation and its
predecessors
completedjobs purge
[olderthan(schedule_expres
sion)]
[application(app_name.[ge
n_num])]
“Clearing the ESP Server
completed jobs repository” on
page 138
Displays information
about a job running in
ESP Server
display
workloadobject(applname
.gen.
wobname.qualifier)
resetgen application Purges all completed
generations of the
specified application and
resets the generation
number to 0
resetgen
application(*|applname)
“Resetting Application
generations” on page 137
• A pair of square brackets "[ ]" enclosing a keyword indicates that the keyword is
optional.
display
workloadobject
Issuing appcmd commands using the Command Utility
You can use the Command Utility to issue appcmd commands one at a time or as
multiple commands in a single statement.
Note: The Command Utility is a separate, stand-alone utility that is not related to the
ESP Desktop Client’s Admin perspective.
ESPD-5.0-AG-02 159

Section–Issuing appcmd commands using the Command Utility
Syntax
Note: On Windows, replace appcmd.sh with appcmd.bat.
appcmd.sh
host
port
username
password
[file to execute]
[Wait before close]
Note: You must write this statement on a single line. On UNIX, the command is case
sensitive.
The following table defines the parameter values you must specify.
Value Definition
host The ESP Server IP address or DNS name
port The ESP Server console port. The default value is 7500.
username Name of the user issuing the appcmd command
password Password of the user issuing the appcmd command
file to
File containing the appcmd commands
execute
Wait before
close
Specifies whether you want the system to wait for each appcmd
command to complete before the next one is sent
• T — Command Utility will wait for each appcmd to complete
(default).
• F — Command Utility will exit before receiving a response to
each appcmd command.
Issuing appcmd commands interactively
You require an active session to carry out this procedure.
1. From the command prompt, enter the following on one line, substituting values
for host, port, username, and password:
Note: On Windows, replace appcmd.sh with appcmd.bat.
appcmd.sh host port username password
2. Press Enter.
If your network connection is established, the command prompt changes to the
name of the server, for example, Manager:
MANAGER>
3. At the prompt, enter the appcmd command, for example, about.
about
160 ESPD-5.0-AG-02

4. Once you finish issuing appcmd commands, type @exit and press Enter.
Your system disconnects from the server and returns to the command prompt.
Example
The following example shows the syntax to start the Command Utility in interactive
mode on a host called myesp. This host uses the default console port of 7500 for the
ESP Server.
UNIX
appcmd.sh myEspresso 7500 Admin admin
Windows
appcmd.bat myEspresso 7500 Admin admin
Issuing appcmd commands in batch mode
You can write a text file that has multiple appcmd commands in it. When you run the
Command Utility to issue the appcmd commands, the Command Utility iterates over
each appcmd command in the file, sending each one to the server.
Specify a command file for the file you want to execute using one line for each
command. The command file is a text file that contains the appcmd commands you
wish to run.
Example: Using batch mode
The following example shows the syntax to start the Command Utility in batch mode
on a host called myEspresso. This host uses the default console port of 7500 for the
ESP Server. Your file purgelog.txt contains commands to purge the trace log and
AFM log.
UNIX
appcmd.sh myEspresso 7500 Admin admin purgelog.txt
Windows
appcmd.bat myEspresso 7500 Admin admin purgelog.txt
Here is the content of your purgelog.txt file:
tracelog purge(all)
afmlog purge(all)
ESPD-5.0-AG-02 161

Section–Issuing appcmd commands using the Command Utility
162 ESPD-5.0-AG-02

Integrating Cybermation ESP: dSeries
Servers
This chapter covers the procedures for integrating two Cybermation ESP: dSeries
Servers. It contains the following topics:
• Integrating your ESP Servers
• Verifying your integration
ESPD-5.0-AG-02 163

Section–Integrating your ESP Servers
Integrating your ESP Servers
ESP Server is packaged with a default ESP Agent, which you use to route information
between two Cybermation ESP: dSeries Servers. You can use either of the default ESP
Agents as the router. Before you begin your setup, identify which default ESP Agent
you are going to use.
In the following diagram, and in the example used in this section, the ESP Server1
default ESP Agent is used to route data between the two ESP Servers.
As you work through the steps in this chapter, refer to the Integrating ESP Servers
diagram diagram below.
Integrating ESP Servers diagram
Information you need
ESP Server2
Collect the following information about your ESP Server2 system.
Information Required Default Value Value Used
Manager name MANAGER2
IP address of the machine where
—
ESP Server is installed
Port number through which the
Manager component receives
requests
7507
This information is in the ESP Server topology. You need this information to update
the default ESP Agent for ESP Server1.
164 ESPD-5.0-AG-02

Chapter 12–Integrating Cybermation ESP: dSeries Servers
Default ESP Agent
Collect the following information about the ESP Server1 default ESP Agent.
Information Required Value Used
ESP Agent name (default name is
AGENT)
ESP Agent type (for example, UNIX)
IP address of the machine where ESP
Agent is installed
Port number on which ESP Agent
communicates with ESP Server
Encryption key
You need this information to define the ESP Server1 default ESP Agent in the
topology for ESP Server2.
Setup tasks
This section describes the high level tasks you complete to integrate your two ESP
Servers.
To set up communication between your two ESP Servers, complete two tasks:
1. Update the ESP Server1 default ESP Agent to communicate with ESP Server2.
2. Define the ESP Server1 default ESP Agent in the ESP Server2 topology.
Update the ESP Server1 default ESP Agent to communicate with ESP
Server2
You need to update the ESP Server1 default ESP Agent parameter file so the ESP
Agent can communicate with ESP Server2. You use the information you collected for
ESP Server 2.
To update the ESP Server1 default ESP Agent to communicate with ESP Server2
Note: These steps assume you are using the ESP Server1 default ESP Agent.
1. Open the agentparm.txt for the ESP Server1 default ESP Agent. The default
location for the file is <installDir>/ESPSystemAgent
where <installDir> represents the installation directory for ESP Server1
ESPD-5.0-AG-02 165

Section–Integrating your ESP Servers
2. Refer to the information you collected for “ESP Server2” on page 164. Under the
Communications section of the agentparm.txt file, make changes to the
following three parameters:
• communication.managerid_2=manager2I
Replace manager2I with the Manager name.
• communication.manageraddress_2=manager2A
Replace manager2A with the IP address of the machine on which ESP Server2
is installed.
• communication.managerport_2=manager2P
Replace manager2P with the Manager port number for ESP Server2.
3. For all three parameters, remove the comment character (#) at the beginning of
the line to activate these lines.
4. Save and close the file.
5. Restart ESP Server1 default ESP Agent.
The following is an example of the agentparm.txt file. The bold text in the
example defines the ESP Server2 parameters. The values shown correspond to the
values shown in the “Integrating ESP Servers diagram” on page 164.
agentname=AGENT
#
# Communications
communication.managerid_1=MANAGER
communication.manageraddress_1=CYBER1
communication.managerport_1=7507
#communication.monitorobject_1=AGENT/AGENTMON1.0/MAIN
communication.managerid_2=MANAGER2
communication.manageraddress_2=CYBER2
communication.managerport_2=7507
#communication.monitorobject_2=AGENT/AGENTMON2.0/MAIN
...
communication.inputport=7520
communication.prefixlevel=2
...
security.cryptkey=0x313233343563738
166 ESPD-5.0-AG-02

Define the ESP Server1 default ESP Agent in ESP Server2 topology
You need to define the ESP Server1 default ESP Agent in the ESP Server2 topology so
ESP Server2 can communicate with ESP Agent. The ESP Server1 default ESP Agent
was defined in the ESP Server1 topology during the ESP Server1 installation. How
you complete this task will depend on the naming of the default ESP Agents. Refer to
Scenarios 1 or 2 below for the appropriate steps to follow.
Scenario 1: The two default ESP Agents have the same name
It is likely that the default ESP Agents for your two ESP Servers will have the same
name. If your ESP Server2 default ESP Agent has the same name as the
ESP_ Server_1 default ESP Agent, you need to do the following:
1. Change the name of the ESP Server2 default ESP Agent in the ESP Server2
topology.
2. Change the ESP Agent parameter file of the ESP Server2 default ESP Agent to
reflect the new name.
3. Update all Applications that use the ESP Server2 default ESP Agent to reflect the
new ESP Agent name.
4. Add the ESP Server1 default ESP Agent to the ESP Server2 topology using the
ESP Desktop Client Admin perspective. Refer to the information you collected
for the “Default ESP Agent” on page 165. Make sure the parameter values for the
new ESP Server2 ESP Agent match those defined for the ESP Server1 default ESP
Agent.
Scenario 2: The two default ESP Agents have different names
If the ESP Server1 default ESP Agent has a different name than the ESP Server2 ESP
Agent, then you simply need to add the ESP Server1 default ESP Agent to the ESP
Server2 topology.
Refer to the information you collected for the “Default ESP Agent” on page 165. Add
the ESP Server1 default ESP Agent to the ESP Server2 topology using ESP Desktop
Client’s Admin perspective. Make sure the parameter values for the new ESP Server2
ESP Agent match those defined for the ESP Server1 default ESP Agent.
ESPD-5.0-AG-02 167

Section–Verifying your integration
Verifying your integration
To verify that your ESP Server1 and ESP Server2 environments are set up correctly,
complete these steps:
1. Create a home Application (APPL1) on one ESP Server system and a distant
Application (APPL2) on the other.
2. In your distant Application, define an External Other Scheduler job.
3. Create and trigger Events for both Applications (APPL1 and APPL2).
Note: We recommend you create and trigger the Event for the distant Application
first.
4. Monitor the jobs running in the distant Application.
In the following example, the External Other Scheduler job is defined in the distant
Application using ESP Server2. ESP Server1 runs the home Application to submit job
B.
Note: This section chapter only provides the procedural steps for defining an External
Other Scheduler job. For other procedures required to verify the setup (steps 1, 3, and
4), refer to the Getting Started with Cybermation ESP: dSeries guide.
Define an External Other Scheduler job
1. Use the ESP Desktop Client Define perspective to open an Application.
2. In the Workflow Objects tree, select External-Other Scheduler.
3. Place an External-Other Scheduler icon onto the workspace.
4. Right-click the job icon and select Edit.
5. On the Basic tab, enter the Job name and qualifier.
The name and qualifier you assign to your External job must be the same as the
name and qualifier of the job in the home Application.
168 ESPD-5.0-AG-02

6. Complete the following fields:
• Specify External Scheduler Name — Enter the name of the other scheduler. This
scheduler is running the home Application that submits the job which the
External job you are defining depends on.
• Specify Agent Name — Enter the name of the Espresso default ESP Agent that
you are using to route information between the schedulers.
• Specify Application Name — (Optional) To override the default, specify the name
of the home Application that submits the job.
• Specify Scheduled Parameter — (Optional) To override the default, specify the
scheduled time of the Event that submits the job, or the trigger time for non-scheduled
Events.
7. Complete the details on the other tabs, as required, and click OK.
ESPD-5.0-AG-02 169

Section–Verifying your integration
170 ESPD-5.0-AG-02

Using the Import/Export Utility
You can use the import/export utility in batch or interactive mode to import and
export artifact definitions such as Alerts, Applications, calendars, Events, forecasts,
JavaScript scripts, and resources. For example, you may want to export your
Application definitions to a directory, update the Applications outside of the ESP
database, and import the changed definitions back into the ESP database.
All artifact definitions, except javascript, config and sundry, are stored as XML files.
Syntax
The import/export utility uses the following command syntax:
UNIX
imexutil.sh [-h host] [-p port] [-u user] [-w password] [-c cmd] [-help]
Windows
imexutil.bat [-h host] [-p port] [-u user] [-w password] [-c cmd] [-help]
Operand Description
host ESP Server IP address or DNS name
port ESP Server port
user The client user ID
ESPD-5.0-UG-02 171

Section–Commands
Operand Description
password The client user ID password
cmd The command(s) or file containing commands to issue in batch mode. If not
help Displays help. If specified, other options are ignored.
Commands
specified, interactive mode is invoked. You can specify a list of commands
separated by semi-colons or a file containing the commands, indicated by
prefixing the file name with an @ sign. For example:
-c "exportapplication -outdir c:applications"
-c "exportapplication -outdir c:applications;
exportevent -outdir c:events"
-c @C:commands.txt
Note: If the argument contains a space, enclose the argument within
quotes, for example -c "@input file.txt".
Importing definitions
Use the import command to import artifact definitions from files and directories.
Files are processed before directories. If an error is encountered processing an artifact,
processing continues with the next artifact.
The import command uses the following syntax:
importartifact [-file filenames] [-dir dirnames]
Operand Description
artifact The artifact name. Use any of the following artifact names:
• agent — ESP Agent definitions from the ESP Server topology
• alert — ESP Alert definitions
• application — ESP Application definitions
• calendar — ESP calendar definitions
• config — ESP Server configuration parameters
• event — ESP Event definitions
• forecast — definitions used for forecast reports
• javascript — JavaScript scripts stored in the JavaScript repository
• resource — resource definitions
• sundry — artifacts not covered in other artifact categories, such as global
system-level symbolic variables
filenames A list of file names separated by spaces. Name masking is not supported.
Files are loaded before directories.
dirnames A list of directory names separated by spaces. Name masking is not
supported. Directories are loaded after files.
172 ESPD-5.0-UG-02

Appendix 13–Using the Import/Export Utility
Exporting definitions
Use the export command to export artifact definitions to a directory. If an error is
encountered processing an artifact, processing continues with the next artifact.
The export command uses the following syntax:
exportartifact [-outdir outputdir]
Operand Description
artifact The artifact name.
• agent — ESP Agent definitions from the ESP Server topology
• alert — ESP Alert definitions
• application — ESP Application definitions
• calendar — ESP calendar definitions
• config — ESP Server configuration parameters
• event — ESP Event definitions
• forecast — forecast definitions used for forecast reports
• group — group definitions used for security
• javascript — JavaScript scripts stored in the JavaScript repository
• resource — resource definitions
• sundry — artifacts not covered in other artifact categories, such as global
system-level symbolic variables
outputdir The directory the artifact definitions are exported to. If not specified, the
artifacts are exported to the current working directory.
Authenticating a user
Use the user command to authenticate a user.
The user command uses the following syntax:
user userid password
Operand Description
userid The user ID to be authenticated
password The password for the user ID
Terminating a session
Use the end command terminates a session.
The end command uses the following syntax.
end
Examples
The following examples export all Applications to c:applications and all
calendars to c:calendars.
ESPD-5.0-UG-02 173

Section–Examples
Batch commands
imexutil.bat -h esp -p 7500 -u schedmaster -w schedmaster -c
"exportapplication -outdir c:applications; exportcalendar -outdir
c:calendars"
Batch command file
imexutil.bat -h esp -p 7500 -c @c:commandfile.txt
The commandfile.txt file contains the following:
user schedmaster schedmaster
exportapplication -outdir c:applications
exportcalendar -outdir c:calendars
Interactive
imexutil.bat -h esp -p 7500
-->user schedmaster schedmaster
Logged on successfully to application server.
-->exportapplication -outdir c:applications
Attempting to export application VERIFY
Exported application definition VERIFY version 1
-->exportcalendar -outdir c:calendars
Attempting to export calendar SYSTEM
Exported calendar definition SYSTEM version 1
-->end
Session terminated
174 ESPD-5.0-UG-02

Index
A
about command, 158
ADMIN default user, 62
ADMIN permission, 72, 76
Admin perspective
admin user, 10
views, 10
ADMIN.Network Topology permission, 72
ADMIN.Security Files permission, 73
ADMINGRP group, 63
afmlog filterid command, 156
afmlog purge command, 156
afmlog spin command, 156
agent command, 156
AGENT permission, 73
agentmsg control command, 156
AGENTMSG permission, 74
AGENTUSER permission, 75
ALERT permission, 76
appcmd commands
description, 156
ESP Agent, 156
ESP Server commands, 158
log commands, 156
APPL permission, 76
Application generations, resetting, 137
Applications that fail to generate, setting up
notifications, 24
APPLX permission, 78
artifact definitions
exporting, 173
importing, 172
artifacts in the system, viewing a list, 25
audit log
creating report, 98
information, 98
auditlog export command, 157
automatic failback, 106, 109
C
CALENDAR permission, 79
changerole command, 158
CMD permission, 80
cold start
definition, 17
performing, 17
Command Utility, 159
batch, 161
ESPD-5.0-AG-02 175

interactive, 160
syntax, 160
completed jobs, clearing, 138
completedjobs purge command, 159
configuration parameters
ESP Agent, 55
Espresso Server, 22
instance, 22
shared, 22
console.txt backup files, clearing, 140
countlist command
description, 158
using, 26
D
database
see also relational database
disk monitoring ESP Agent, 27
disk space availability, shared directory, 27
display afmlog command, 157
display auditlog command, 157
display tracelog command, 157
display workloadobject command, 159
E
email addresses, changing, 23
ESP Agent
changing user’s password, 57
clearing log files, 143
clearing spool files, 144
controlling, 58
defining users, 56
description, 7
modifying configuration parameters, 55
reloading security file, 59
stopping, 58
ESP Agent for z/OS, configuring, 57
ESP Agent receiver messages
holding and resuming, 59
ESP Agent receiver messages, clearing, 59
ESP artifact types, 25
ESP Desktop Client
administrator’s component, 10
applying software updates, 13
description, 6
passwords, 11
server connections, 11
viewing users connected, 12
ESP High Availability
configuration models, 113
detection, 108
process, 107
requirements, 114
terminology, 106
verifying the configuration, 117
ESP High Security
installation steps, 30
ESP Server
archiving log files, 139
changing port numbers, 23
changing the Windows service name, 30
checking status, 16
clearing completed jobs repository, 138
configuring, 22
description, 6
filter IDs, 101
instance and shared parameters, 22
log files, 96
recycling, 20
start type, 17
starting, 18
startup in failover configuration, 107
stopping, 20
ESP Server log files
see log files
ESP Server roles, switching, 112
EVENT permission, 81
EVENTX permission, 82
EVERYONE group, 63
exception messages, 96
exporting audit log, 98
F
failback
automatic, 106, 109
changing the type, 111
manual, 106, 110
failover
configuring detection, 110
filter IDs
about, 96
applying permanent, 100
applying temporary, 99
summary, 101
filtering messages, 99
176 ESPD-5.0-AG-02

Index
G
group description, changing, 70
group permissions, adding, changing or removing, 69
groups
ADMINGRP, 63
creating, 69
description, 62
EVERYONE, 63
OPERGRP, 64
predefined, 63
removing from the ESP Server topology, 70
SCHEDGRP, 64
H
heap size, checking, 25
I
import/export utility, syntax, 171
J
jobs forced to complete, setting up notifications, 24
L
license status, 26
licensestatus command, 158
log files, 96
applying permanent filter IDs, 100
applying temporary filter IDs, 99
archiving, 139
archiving automatically, 139
archiving manually, 140
changing location/name, 97
clearing, 141
manually, 141
clearing automatically, 141
exception messages, 96
filter IDs, 96
filtering messages, 99
maintenance, 96
rotation, 139
types, 96
M
manual failback, 106, 110
memcheck command, 158
memcheck command, using, 25
memory usage, checking, 25
Micro Focus
security rule, 41
N
nohup files
clearing, 147
description, 147
notifications
setting up for Applications that fail to
generate, 24
setting up for jobs forced to complete, 24
O
OPERGRP group, 64
P
passwords
changing, 11
resetting, 12
permissions
adding, changing or removing, 67
ADMIN, 72, 76
ADMIN.Network Topology, 72
ADMIN.Security Files, 73
AGENT, 73
AGENTMSG, 74
AGENTUSER, 75
ALERT, 76
APPLX, 78
CALENDAR, 79
CMD, 80
conventions, 65
description, 64
summary, 72
user vs group, 65
R
relational database
changing connectivity properties, 131
description, 130
ESP High Availability, 130
history reporting, 130
resource management, 130
resetgen application command, 159
ESPD-5.0-AG-02 177

RESOURCE permission, 83
S
SCHEDGRP group, 64
SCHEDMASTER default user, 62
security
creating groups, 69
creating users, 66
deleting users, 68
description, 62
groups, 62
permissions, 64
permissions summary, 72
setting up, 84
users, 62
security file, reloading, 59
security rules
Micro Focus, 41
server.log files
clearing, 143
description, 143
shared directory
monitoring, 26
monitoring availability, 28
shared-file system, 115
SMTP server name, changing, 23
SNMP Manager
changing settings, 124
third-party configuration, 125
SNMP Manager, using third-party, 122
SNMP Message Viewer
removing messages, 127
SNMP messages
description, 122
opening, 127
printing, 127
receiving, 126
removing, 127
saving, 127
understanding, 122
viewing in text format, 127
SNMP trap receiver
stopping, 126
software updates for ESP Desktop Client, 13
start type, ESP Server, 17
stop command, 158
T
tracelog filterid command, 157
tracelog purge command, 157
tracelog spin command, 157
U
users
adding to a group, 67
ADMIN default user, 62
changing names, 68
creating, 66
deleting, 68
description, 62
removing from a group, 68
removing from the ESP Server topology, 68
SCHEDMASTER default user, 62
V
virtual Agent
removing parent, 55
W
warm start, definition, 17
Windows service name for ESP Server, changing, 30
178 ESPD-5.0-AG-02

Q000241e admin guide

More Related Content

What's hot (19)

Viewers also liked (9)

Similar to Q000241e admin guide (20)

Recently uploaded (20)

Q000241e admin guide