Maintaining the eLink Business Process Option

 

The following sections describe routine maintenance procedures for the Business Process Option:

• Overview of Administrative Procedures

• Starting, Stopping, and Configuring eLink Business Process Option

• Using Business Process Option Administration Tools

• Using Database Tools

• Setting Configuration Options

• Managing Status and Audit Logs

• Maintaining the Repository

• Optimizing the Business Process Option Database

• Moving Work Between eLink Business Process Option Servers

Overview of Administrative Procedures

Once the eLink Business Process Option is running, perform the following administrative procedures (using the icadmin user account):

• Add and remove new users and pools.

• Grant access privileges to users.

• Create triggers for event notification, policy enforcement, or process control.

• Export and import processes to move work between servers.

As the Administrator, you are also responsible for the following routine maintenance procedures:

• Configuring and booting the eLink Business Process Option

• Managing the Business Process Option Server

• Monitoring the status of the Repository Server

• Managing the status and audit logs

• Performing troubleshooting

• Configuring security levels for eLink Business Process Option users and actions

Starting, Stopping, and Configuring eLink Business Process Option

Most eLink Business Process Option operations can be performed using Tuxedo utilities, such as tmadmin, tmloadcf, tmboot, tmshutdown, and/or the BEA Web Administration Console. For further information, see your eLink platform documentation.

Using Business Process Option Administration Tools

In addition to the standard Tuxedo utilities, eLink Business Process Option provides administration utilities to help you perform maintenance tasks on the database and the Repository Server. These utilities are:

• Batch Registry

• IcAuditManage

• IcStatusManage

• IcRepManage

• IcRepCheck

• IcRecreateAttrViews

Using the Batch Registry Utility

The Batch Registry utility is an application that lets you manage the business process environment. It provides management functions that let you grant privileges to users, add users to the system, and create documents, pools, repositories, and other objects.

Note: In eLink Business Process Option, the Batch Registry accommodates whatever Tuxedo security settings you have. Depending on the security level you have set, you may be prompted for one or two user name/password combinations when you launch the Batch Registry.

Using eLink Business Process Option Maintenance Utilities

Several maintenance routines should be performed using the following utilities:

Utility	Usage
IcAuditManage	A utility that enables you to view audit log information unconditionally or conditionally based on a category, time period, or combination of these. Delete audit log entries unconditionally or conditionally.
IcStatusManage	A utility that enables you to view status log information unconditionally, or conditionally based on facility, severity, time period, or a combination of these. Delete status log entries unconditionally or conditionally.
IcRepManage	A utility that enables you to view and delete unused files in the eLink Business Process Option Repository.
IcRepCheck	A utility that enables you to check the integrity of repositories against the database, check the integrity of the database against repositories, check the integrity of a document, and check the integrity of a content file.

Using Database Tools

You can get information about the system by examining eLink Business Process Option database views with your database query language. You can use the standard views supplied, extend the standard views with additional information, or create new views.

If you add attributes to object classes, you can update the corresponding database view to include these new attributes with the IcRecreateAttrViews utility.

Setting Configuration Options

The eLink Business Process Option has several configuration options that are independent of Tuxedo configuration information. These options relate to the database and status audit logs.

IcEnvFile is a text file located in $IC_HOME/config.

IcEnvFile contains a series of lines in the following format:

CONFIGURATION_OPTION_NAME=VALUE 

The following table lists the configuration options in IcEnvFile

Configuration option	Description
IC_ACTION_POLL_INTERVAL	Polling interval for processing triggered actions, from 1 to 300 seconds. The default is 60.
IC_ACTION_RPC_RETRY_INTERVAL	Retry interval for registered trigger actions, from 900 to 86400 seconds. The default is 10800.
IC_ACTION_RPC_TIMEOUT	Timeout value for registered trigger actions, from 15 to 300 seconds. The default is 60.
IC_AUDIT_LOG	If an optional Audit Log File exists in addition to the Audit Log table, this variable is set to the full path name of the audit log file. The Audit Log File is in $IC_HOME/logs on the host machine. Default value is NOT_USED.
IC_AUDIT_MODE	Default is IC_EVENT_AUDIT_DATABASE. Do not change the value of this option.
IC_EVENT_POLL_INTERVAL	Polling interval for checking temporal events (for example, TASK_LATE_START, TASK_OVERDUE), from 60 to 86400 seconds. The default is 3600.
IC_HOST_MACHINE	The host system on which the eLink Business Process Option server is running.
IC_RDBMS	Type of database for this installation (for example, ORACLE).
IC_SERVER_NAME	Logical name of the eLink Business Process Option server instance (established during installation).
IC_STATUS_LOG	Full path name of the file containing the Process Option status output. The log file is in $IC_HOME/logs on the host machine.

Managing Status and Audit Logs

This section explains how to examine and interpret log entries and manage log file size on an eLink Business Process Option server.

• The Business Process Option Status Log reports errors or other significant events encountered by the eLink Business Process Option server.

• The Business Process Option Audit Log lists every event processed by the eLink Business Process Option server.

You can use the Business Process Option Status and Audit logs to:

• View audit log information unconditionally or conditionally based on a category, time period, or combination of these.

• View status log information unconditionally or conditionally based on facility, severity, time period, or a combination of these.

• Delete audit and status log entries unconditionally or conditionally.

eLink Business Process Option maintains the following log files in the $IC_HOME/logs directory on the eLink Business Process Option host machine:

Log File	Description
audit_manage.log	Audit log file
ic_batch_registry.log	Batch Registry log file
IcCliMgr.err	Error log for Daemon Manager
CliMgr.log	Client Manager log file
IcEvtAct.err	Error log for EventAction daemon
IcGenWorker.err	Error log for IcGen_tag services
IcJobWorker.err	Error log for IcJob_tag service
IcRepCheck.log	Log file for IcRepCheck utility
IcRepManage.log	Log file for IcRepManage utility
status.log	The Status log file
ULOG.mmddyy	Log file for eLink administrative information

Managing Status Information with IcStatusManage

eLink Business Process Option records status information to the Status log on an ongoing basis.

This status information provides:

• Verification that the installation is running smoothly

• Notification of problem areas or server startup failures

• Feedback in the event of a system failure

Status information increases in accordance with user activity. If left unchecked, this information can use up file system space. Examine the Status Log regularly with the IcStatusManage utility.

IcStatusManage has two operating modes:

Interactive mode	Lets you examine and remove log entries with a menu-based interface.
Command mode	Bypasses the menu interface and lets you examine and remove log entries with command line options.

This utility cannot be used to examine and maintain eLink Business Process Option audit information. You must use the IcAuditManage utility and standard UNIX file system commands to manage audit information.

Using IcStatusManage in Interactive Mode

IcStatusManage lets you list or remove log file entries by date, severity, or facility (application component).

During interactive processing, you specify the kind of operation you want to perform and respond to a series of menus to further qualify the operation. Every menu includes a Quit option that returns you to the previous menu. To exit IcStatusManage, select Quit from the main menu.

To use IcStatusManage in interactive mode

1. At the prompt, enter the following command:

   IcStatusManage

2. At the log file prompt, enter the full path name of the log file to be examined and press RETURN. This displays the IcStatusManage main menu shown below:

   Main Menu

   1. List Status Log Entries

   2. Remove Status Log Entries

   3. Quit

3. To examine log entries, choose List Status Log Entries. To remove entries from the log file, choose Remove Status Log Entries. IcStatusManage displays the first of a series of submenus where you specify:

   Log entry severity

   Facility from which the log entry originated

   Date of log entries

   After you enter your selections, IcStatusManage either displays or removes the specified log entries and returns to the Date menu.

4. Enter a different date to list or remove additional entries or select Quit to return to the previous menu.

Using IcStatusManage in Command Mode

The command interface for IcStatusManage lets you examine or remove log file entries with a series of command line options.

Syntax

IcStatusManage [ -s log_pathname ] [ -l | -r ] 
[ -warn | -error | -fatal ]
[ -before date_time | -after date_time ] 
[ -fac facility_name ]

Parameters

-s log_pathname

Full path name of the status log file to be examined. You can specify just the log file name if the file resides in $IC_HOME/logs. If you omit this parameter, IcStatusManage executes in interactive mode.

-l | -r

Determines the operation to be performed.

-l lists log file entries; this is the default.

-r removes log file entries.

-warn | -error | -fatal

In combination with the -l and -r parameters, further narrows the selection of status log entries to those marked WARNING, ERROR, or FATAL. The default is to operate on all status records.

-before date_time |
-after date_time

In combination with the -l and -r parameters, list or remove status log entries dated earlier than (-before) or later than (-after) date_time. The date_time value must be entered in quotes, in the format:

"mm/dd/yy hh:mm:ss"

-fac facility_name

In combination with the -l and -r parameters, lists or removes status log entries originating from the specified facility. The facility_name can be any of the facilities listed in the following table. The default is to operate on entries originating from all facilities

The following table displays the facility names.

Status Log Facility	Description
IC_ADMIN	eLink utility software errors
IC_CLIENT	User application errors
IC_DBMS	InConcert database errors
IC_FILE_SYSTEM	File system errors
IC_GUI	Graphical user interface errors
IC_IC	Process Option or general errors
IC_NETWORK	Network-related errors
IC_OS	Operating system errors
IC_TUXEDO	Tuxedo errors
IC_WINDOW_SYSTEM	Window system errors

Example

IcStatusManage -s status_log -r -warn

Managing Audit Information with IcAuditManage

The eLink Business Process Option captures audit (event) information to provide a tracking mechanism and history of process activity. Process activity is stored in the Audit Log Table in the Business Process Option database. An optional Audit Log file contains the same information in ASCII format.

Event information grows in direct proportion to user activity. If left unchecked, this information will continue to grow, using up file system space and possibly degrading system performance. As a result, you should examine the Audit Log regularly and clean it up using the IcAuditManage utility.

Note: The Audit Log Table stores iteration information about active eLink processes. Therefore, deleting table entries may cause a loss of iteration data. Use caution when deleting entries.

Like IcStatusManage, IcAuditManage has two modes:

Interactive mode	Lets you examine and remove event records with a menu-based interface.
Command mode	Bypasses the menu interface and lets you examine and remove event records with command line options.

Note: The IcAuditManage utility places a heavy load on the server and can degrade system performance when it is run while the system is in active use. If this is a concern, we recommend running IcAuditManage during off hours.

The eLink Business Process Option must be running when using IcAuditManage.

Note: Output written to the audit log reflects Greenwich Mean Time (GMT). All date and time input from users should be specified for the individual user's time zone.

Using IcAuditManage in Interactive Mode

IcAuditManage can list or remove event records by event type, user, or process. During interactive processing, you specify the kind of operation you want to perform (list or remove) and respond to a series of menus to further qualify the operation.

Every menu includes a Quit option that returns you to the previous menu. To exit IcAuditManage, select Quit from the main menu.

To use IcAuditManage in interactive mode

1. At the prompt, enter the following command:

   IcAuditManage -icclient user/password@server

   For example:

   icdba/icdba@manatee.

2. The IcAuditManage main menu is displayed:

   Main Menu

   1. List Audit Table Entries

   2. Remove Audit Table Entries

   3. Quit

3. To examine Audit Table entries, choose List Audit Table Entries. To remove entries from the Audit Table, choose Remove Audit Table Entries. IcAuditManage displays the first of a series of submenus where you specify one or more of the following:

   Kind of event

   User name

   Process name

   Date of entries

4. After you make your selections, IcAuditManage either displays or removes the specified event records and returns to the Date menu. Enter a different date to list or remove additional entries or select Quit to return to the previous menu.

Using IcAuditManage in Command Mode

The command interface for IcAuditManage lets you examine or remove Audit Log Table entries with a series of command line options.

Syntax

IcAuditManage -icclient client_data [ -ictimeout seconds ] 
[ -r | -l ] [ -before date_time | -after date_time ]
[ -event event_type | -user user_name | -job job_name ]

Parameters

-icclient client_data

Client data of the form:

user/password@server

For example: icdba/icdba@manatee.

-ictimeout seconds

Timeout interval, in seconds. The default timeout is 120 seconds.

-r | -l

-r removes entries from the Audit Log Table. -l lists entries in the Audit Log Table; this is the default.

-before date_time | -after date_time

In combination with the -l and -r parameters, list or remove event records dated earlier than (-before) or later than (-after) date_time. The -after parameter cannot be specified if you also specify -r. The date_time value must be entered in quotes, in the format:

"mm/dd/yy hh:mm:ss"

-event event_type | -user user_name | -job job_name

In combination with the -l and -r parameters, list or remove event records by event type, user, or process.

-event

Narrows the operation to events of a particular kind.

-user

Narrows the operation to events produced by a particular Business Process Option user.

-job

Narrows the operation to events produced by a particular process.

In combination with the -l and -r parameters, list or remove event records by event type, user, or process.

-event	Narrows the operation to events of a particular kind.
-user	Narrows the operation to events produced by a particular user.
-job	Narrows the operation to events produced by a particular process.

Managing the Optional Audit Log file

The optional Audit Log file is created during Process Option startup. The Audit Log file is created if the IC_AUDIT_LOG parameter is set to a full path name in IcEnvFile.

The Audit Log file contains the text equivalent of the Audit Log table entries in the Business Process database. The Audit Log file grows in direct proportion to user activity and needs to be maintained on a regular basis.

To examine the contents of the Audit Log file

Use one of these commands:

cat filename

more filename

You can also open the file using an ASCII editor, such as vi or emacs.

To delete the contents of the Audit Log file, but not the file itself

Use this command:

cat /dev/null > filename

To delete the Audit Log file and its contents

Use this command:

rm filename

Note: Do not delete the Audit Log file unless the eLink Business Process Option is down. When the eLink Business Process Option is not running, deleting the log file has no effect on the system. When you restart the eLink Business Process Option, a new Audit Log file is created automatically.

Maintaining the Repository

The IcRepCheck and IcRepManage repository utilities - valid for both NFS and Repository Server repositories - let you manage unused content files and ensure the integrity of the InConcert database:

• IcRepCheck examines repository information in the database and compares it to the actual repository contents and vice-versa.

  Note: IcRepCheck lists files that have no document objects in the database. Run this utility when unexpected errors occur, such as after restoring the system from backup.

• IcRepManage lists and removes content files with no references in the database - including all versions of documents other than the latest version. IcRepManage lists and removes files for documents that are not being referenced in the database. Run this utility routinely to clean up unused content files.

  Notes: If you want old versions (versions other than the latest version) of your documents, do not run IcRepManage. IcRepManage will delete all the old versions of your documents.

  All write activity involving repository directories should be performed through Business Process Option. Writing directly to a repository location (without Business Process Option) can result in the loss or corruption of content files.

Using IcRepCheck to Check Repository Information

To check the condition of a repository, use the IcRepCheck utility. IcRepCheck lets you perform the following checks:

• Verify all paths from each repository content file back to the Business Process Option database.

• Verify the path from a specified Business Process document to the corresponding repository content file.

• Check for the existence of a particular content file specified by the user.

• List repository content files not referenced by the Business Process Option database.

• List all Business Process Option documents that contain no reference to any content file.

You can run the IcRepCheck utility to examine the integrity of existing repositories, repository content files, and information about repositories in the Business Process Option database. The Business Process Option must be running when using IcRepCheck.

Note: You can only run the IcRepCheck utility if you have Administrator privilege.

IcRepCheck has the following operating modes:

Interactive mode

Lets you examine repository information with a menu-based interface. Interactive mode lets you check all Business Process Option document objects for references to a specific repository content file and check all repository content files for references to a specific Business Process Option document object.

Command mode

Bypasses the menu interface and lets you check repository-to-database associations with a series of command line options. It does not provide all of the capabilities of the menu interface.

Note: The Business Process Option server must be running when using IcRepCheck.

Using IcRepCheck in Interactive mode

During Interactive mode, you specify the kind of check you want to make, such as: check repository, check a single file in a repository, or check a single document in the database. You must respond to a series of menus to further qualify the operation. Every menu includes a Quit option that returns you to the previous menu; selecting Quit from the main menu exits IcRepCheck.

Verifying Server Information

To verify server information before running IcRepCheck

1. Log into the Business Process Option on the machine hosting the server. Be sure you are logged in as a user that has write access to the repository directory (for example, icadmin). IcRepCheck behaves differently, depending on the user who starts it.

2. Be sure your $IC_CLIENT environment variable is set to:

   icdba/password@server

3. Go on to Running IcRepCheck.

Running IcRepCheck

To run IcRepCheck in interactive mode:

IcRepCheck -icclient user/password@server

1. The IcRepCheck main menu is displayed:

   Main Menu

   1. Check Integrity of Repository

   2. Check Integrity of Individual Content File

   3. Check Integrity of Individual Document

   4. Quit

2. To check all files in one or more repositories, choose Check Integrity of Repository. To check a specific content file, choose Check Integrity of Individual Content File. To check a specific document in the database, choose Check Integrity of Individual Document.

3. IcRepCheck displays the first of a series of submenus where you specify one or more of the following:

   • Repository

   • Kind of check such as content file against database or database against repository or file

   • Kind of file or document listing (long or short).

4. After making your selections, IcRepCheck displays the results of the check and returns to the latest menu. You can make another selection in that menu, or select Quit to return to the previous menu.

Using IcRepCheck in Command Mode

The command interface for IcRepCheck lets you check repository-to-database associations with a series of command line options. It does not provide all of the capabilities of the menu interface.

Syntax

IcRepCheck [ -icclient client_data ] [ -ictimeout seconds ] 

IcRepCheck -icclient client_data [ -ictimeout seconds ]
{ -cont | -dbms } { -ll | -ls } [ -rep repository_pathname ]

Parameters

-icclient client_data

Client data in the form:

user/password@server

See Using the Batch Registry, for details on this parameter.

-ictimeout seconds

Timeout interval, in seconds. The default timeout is 120 seconds.

-cont | -dbms

These two parameters determine the kind of check made by IcRepCheck:

-cont

Checks for repository content files that are not referenced in the Business Process Option database.

-dbms

Checks for Business Process Option documents in the database that are not associated with any repository content file.

-ls

Produces a short listing (file name only) of content files. With
-cont, the listing includes content files which are not referenced in the database. With -dbms, the listing includes content files that are referenced in the database but do not exist.

-ll

Produces a long listing (file name, date, time stamp) of content files. With -cont, the listing includes content files that are not referenced in the database. With -dbms, the listing includes content files that are referenced in the database but do not exist.

Note: When multiple versions of a document are listed, all but the most recent version include the following information: the associated Business Process Option process and task, and name of the user who created the document.

-rep repository_pathname

Checks only the repository specified by repository_pathname. If you omit this parameter, all repository content files are examined.

Using IcRepManage to Delete Unused Files from Repositories

The IcRepManage utility lets you list or remove document content files in a repository that are not referenced by the Business Process Option database. These files are considered "unused" files. The Business Process Option server must be running when using IcRepManage.

Note: The first time IcRepManage is run on a system that has had heavy PC GUI usage, it may take some time to complete this operation. You may wish to run it during off-hours. IcRepManage will output a series of dots while the operation is in progress. If IcRepManage fails to complete in the time allotted, you may need to increase the environmental variable IC_TIMEOUT to 99,999. This represents the number of seconds that IcRepManage will wait for a response from the server before timing out.

IcRepManage lets you:

• List all unused content files, in an individual repository or all repositories.

• Remove all unused content files, in an individual repository or all repositories.

In addition, IcRepManage deletes obsolete Task User Interface documents from the database and repository. Note that the TUI documents are not deleted unless the process they are related to has first been deleted by the process owner. To do this, open the "Completed Processes" folder in the Process Manager and choose Process > Delete.

Note: IcRepManage can be run only by users with Administrator privilege.

IcRepManage has an Interactive mode and Command mode. The interactive mode allows you to examine and remove files with a menu-based interface. The command mode bypasses the menu interface and lets you examine and remove files with command line options.

Upon completion, IcRepManage creates the log file IcRepManage.log in $IC_HOME/logs.

Using IcRepManage in Interactive Mode

In Interactive mode, you specify the repository (or repositories) you want to process and respond to a series of menus to further qualify the operation. Every menu includes a Quit option that returns you to the previous menu; selecting Quit from the main menu exits IcRepManage.

To process repositories in interactive mode:

1. At a shell prompt, enter the following command:

   IcRepManage

2. InConcert displays the IcRepManage main menu shown below.

   Main Menu

   1. Process All Repositories

   2. Process Specific Repositories

   3. Quit

3. To process all repositories, choose Process All Repositories. To process specific repositories, choose Process Specific Repositories.

4. IcRepManage displays the first of a series of submenus where you specify:

   • Type of operation you want to perform: list or remove

   • Type of file listing: long or short

5. After making your selections, IcRepManage either displays or removes the specified repository files, then returns to the latest menu. You can make another selection in that menu, or select Quit to return to the previous menu.

Using IcRepManage in Command Mode

The command interface for IcRepManage lets you examine or remove unused document content files with a series of command line options.

Syntax

IcRepManage [ -icclient client_data ] [ -ictimeout seconds ] 
[ -ls | -ll ] [ -r ] [ repository_pathname ]

Parameters

-icclient client_data

The following items are client data in the form:

user/password@server

See Using the Batch Registry, for details on this parameter.

-ictimeout seconds

Timeout interval, in seconds. The default timeout is 120 seconds.

-ls | -ll

These two parameters determine the kind of listing produced by IcRepManage:

-ls

Produces a short listing (file name only) of the unused content files in repository_pathname. If you omit repository_pathname, all unused content files in all repositories are listed.

-ll

Produces a long listing (file name, date, time stamp) of the unused content files in repository_pathname. If you omit repository_pathname, all unused content files in all repositories are listed.

-r

Removes unused content files from repository_pathname.

repository_pathname

Specifies the repository to be examined by IcRepManage. If you omit this parameter, all repository content files are examined.

Optimizing the Business Process Option Database

You should execute the appropriate database optimization procedures on a weekly or monthly basis, or whenever there is a significant increase in the size of the Business Process database.

Moving Work Between eLink Business Process Option Servers

Using the Batch Registry utility, you can copy process definitions from one Process Option to another. This procedure lets you move work between eLink Business Process Option servers.

To copy a document or process from one server to another

1. In the source eLink Business Process Option server's Batch Registry, export the process with the Export Job command.

2. In the destination eLink Business Process Option server's Batch Registry, import the process with the Import Job command.