Chapter 5   Managing Applications

Applications that handle business processes are at the heart of the Process Manager. Process Manager provides several forms for managing applications. You can change an application's state, view its logs, and export and delete its data.

This chapter describes these topics:

• About Applications



• Stopping & Starting Applications



• Closing Applications



• Uninstalling Applications



• Viewing the Application Logs



• Exporting and Deleting Data

About Applications

---

Designers use Process Builder to define a Process Manager application. When the application is complete, the designer can deploy it to a cluster for final testing or for normal production use by Process Express end users.

A deployed application consists of a process definition that is stored in the configuration directory and a set of user data stored in the cluster's database.

Once an application is deployed, Process Administrator maintains information about its state. As the administrator, you can change this information, and as you do so, Process Administrator keeps the application information up to date in the configuration directory.

Figure 5-1    The Deployed Applications page

Application states include both their status and their stage. An application's status indicates whether it is currently running or not. An application's stage indicates whether it is in development or production, and whether it is available to end users.

Application statuses are:

• Started (On): End users and administrators can access the application to initiate and manage process instances and work items.



• Stopped (Off): End users cannot initiate new process instances for the application and cannot execute actions on existing process instances.

Administrators can stop started applications or start a stopped application.

Designers deploy to Development or Production. If they deploy to Development, they can still change almost all aspects of the application. If they deploy to Production, they are very limited in what changes they can make.

Application stages are:

• Open: This is the initial stage after a designer has deployed the application.



• Closed: The administrator has closed down the application. End users can complete existing process instances but cannot initiate any new process instances. The Process Manager administrator can reopen closed applications at any time.



• Obsolete: The administrator has uninstalled a closed application, and may have removed the application's user data. End users can no longer work on process instances for this application. Only closed applications can be uninstalled. Once an application has been uninstalled, you cannot resurrect it.

Another stage, Design, is only visible and accessible from Process Builder. This stage means that the application is not yet fully deployed, but its definition is stored in the configuration directory to provide a centralized repository so that multiple designers can always obtain the most current standard version of the application definition. The designer puts an application into this stage by deploying it as "Stored Only" from the Deploy Applications dialog box.

Finally, an application can also be in testing mode. The designer has deployed the application, but all work items are set as assigned to their initiator (which is typically the designer or the administrator) to permit further testing of all aspects of the process definition. Once an application is deployed to production, it can no longer return to the testing stage.

When the administrator changes an application's stage, Process Administrator updates the application definition in the configuration directory.

---

Note	If a designer deploys a locally saved version of an already deployed application, and the two applications do not have the same stage value, the local version does not overwrite the stage of the application already in the cluster.

---

Stopping & Starting Applications

---

Among the actions that an administrator can perform on an application are stopping and starting it. These change its status, which is maintained in the configuration directory as part of the persistent application data that describes all instances of the application across the cluster.

Figure 5-2    Application administration actions

If an application is started and the administrator stops it, this shuts it down everywhere across the cluster. This sets the application's status to Stopped, which does not allow access to process instance detail by end users

If an application is stopped and the administrator starts it, this sets the application's status to Started, which allows full access to process instances and work items by end users and administrators.

When it starts an application, either as part of an autostart or as part of a manual start, Process Administrator performs these operations:

• Retrieves the application's definition from the configuration directory.



• Establishes a connection with the database.

Autostart

Whenever an end user accesses an application in the Process Express, Process Manager checks the application's status. If the application's status is Started but it isn't running, Process Manager does an autostart. This can occur in two situations:

• The application has just been newly deployed.



• The server through which an end user is accessing the application was unavailable and has now been restarted.

Because Process Administrator has to perform several operations when it starts an application, there can be a time delay for the first end user who accesses an application in these situations. As a result, some administrators may prefer to force initializing of an application immediately after it is newly deployed or to force initialization of all applications after restarting a server.

Initializing an Application

An application is initialized when someone such as an end user or the administrator invokes it as a web browser URL. As part of the initialization operation, an application checks the configuration directory to make sure it has the latest definition. If the configuration directory's definition is more up to date, the application downloads that definition to server.

To initialize an application, use this URL:

http://malta.mcom.com:4080/NASApp/pae/ContentStoreTest .npm?eventId=OnListEntryNodes

The result is that the application is already up and running when the first user accesses it. To initialize all the applications on a server requires you to repeat this type of URL for each application. You may choose to only initialize the most time-critical applications.

Stop

You can use Process Administrator on a given iPlanet Application Server to stop an application. For example, you may want to stop an application when you do not want end users to be able to access it. Stopping an application sets its status to Stopped in Process Administrator.

If an administrator stops an application, users are prevented from creating new process instances, work items, or otherwise accessing that application. Database transactions running when the administrator stops the application are allowed to complete.

To stop an application, follow these steps:

1. Go to Process Administrator's home page at http://yourServer/Administrator.apm.



2. Click the Applications tab. This displays the list of applications in the cluster.



3. For the application you want to stop, choose the Stop Application command from the drop-down list for that application.



4. Click Apply.

Now you and your end users cannot access the process instance detail for the application. End users cannot initiate new process instances or continue working on existing work items.

Start

You can start a stopped application. When you start an application, you are setting its status to Started in Process Administrator.

To start an application, follow these steps:

1. Go to Process Administrator's home page at http://yourServer/Administrator.apm.



2. Click the Applications tab. This displays the list of applications in the cluster.



3. For the application you want to start, choose the Start Application command from the drop-down list for that application.



4. Click Apply.

Now you and your end users can access the process instance detail for the application from any server in the cluster. End users can once again initiate new process instances and continue working on existing work items.

Closing Applications

---

Closing an application means that end users cannot initiate any new process instances, but they can continue to complete existing process instances. Closing an application sets its stage to Closed.

When you no longer need an application, you can close it. When you uninstall an application, you cannot "reinstall" it.

End users can continue to work on work items until there are no open work items for the application, at which time you can uninstall the application.

To close an application, follow these steps:

1. Go to Process Administrator's home page at http://yourServer/Administrator.apm.



2. Click the Applications tab. This displays the list of applications in the cluster.



3. For the application you want to close, choose the Close Application command from the drop-down list for that application.



4. Click Apply.

End users cannot initiate new process instances but they can continue working on existing work items.

Uninstalling Applications

---

If you have an application that you no longer need, you can manually uninstall it. The application must already be in a closed stage without any remaining open process instances.

Typically, a Process Manager administrator follows this sequence of operations:

1. Leaves an application in the closed stage for a while.



2. Manually terminates any open process instances that do not complete within a certain period of time.



3. Exports the application's process instances (that is, the user data) and may choose to delete it from the database.



4. Uninstalls the application from the cluster.








---

Note	If you are planning to delete a cluster, it is strongly recommended that you first uninstall each of its applications to avoid additional manual clean-up tasks after you delete the cluster.

---

Occasionally, you may have applications that you no longer want to use, and that you want to remove from the end user interface. You can uninstall a closed application, which marks it as Obsolete. Designers can delete obsolete applications from the Process Builder, but they cannot redeploy them. When you uninstall an application, you stop end users from initiating any new process instances from the New Process page.

When you choose the Uninstall command, you are asked if you want to delete the application-specific database tables. If you confirm the deletion, the application's user data is removed. If not, the data is left intact.

You cannot uninstall an application that has any open process instances. You need change the state of any open process instances to terminated if you want to continue with uninstalling the application.

To uninstall a closed application, follow these steps:

1. Go to Process Administrator's home page at http://yourServer/Administrator.apm.



2. Click the Applications tab. This displays the list of applications in the cluster.



3. For the application you want to uninstall, choose the Uninstall Application command from the drop-down list for that application.



4. Click Apply.




This displays the Uninstall Application dialog box.



5. Check the radio button to leave the application's database table intact or to delete it, depending on your situation.



6. Click Uninstall Application to mark the application as obsolete.

Figure 5-3    The Uninstall Application dialog box

Now you and your end users cannot access the process instance detail for the application. End users cannot initiate new process instances or continue working on existing work items.

Viewing the Application Logs

---

Process Manager applications use several log files, with each iPlanet Application Server in a cluster having its own set of log files. Process Manager administrators can view these application logs that are maintained for each application on a per-server basis:

• warning log (warningLog.html) -- shows warnings that affect the application.



• error log (errorLog.html) -- shows the errors that have occurred with the application.

These files are located at serverRoot/builder/support/log.

To view an application's logs, follow these steps:

1. Go to Process Administrator's home page at http://yourServer/Administrator.apm.



2. Click the Applications tab. This displays the list of applications in the cluster.



3. For the application whose logs you want to view, choose the View Logs command from the drop-down list for that application.



4. Click Apply.



5. Click View Log File.



6. If a dialog box prompts you to enter a user ID and password, enter the ones that you defined for your Administration Server. For example, admin/admin. When they are authenticated, the View Application Logs page is displayed.



7. From the View Application Logs page, choose the log you want to view from the drop-down list.



8. Indicate how many log records you want to view. The log file display starts at the end of the file, so indicating "12" would show the last 12 records in the file.



9. Click View Log to see the log file.

Exporting and Deleting Data

---

As Process Manager administrator, you can export or delete application user data that's no longer in use. You can only export and delete data from closed process instances. You cannot delete or export work items separately from the process instances that they are part of.

You can choose to export only, export and then delete, or delete only. You can perform the action for a single application or for all applications at once.

You can access this function through the Export and Delete Data button at the bottom of the main Applications page.

To export or delete user data, follow these steps:

1. Go to Process Administrator's home page at http://yourServer/Administrator.apm.



2. Click the Applications tab.



3. Click the Export and Delete Data button at the bottom of the page below the list of applications.




The window pictured in Figure 5-4 appears:

Figure 5-4    The Export and Delete Data page

4. Select a specific application or "Any Applications" from the drop-down list.



5. Enter any search criteria.




You search for process instances based on one or more of the following criteria:



• process instance IDs



• time the process instance was created



• time the process instance was completed or terminated



6. Check "Save export to local disk at path" to export the data.

---

Note	On Windows NT, the disk must be local. You cannot use an NFS-mounted drive.

---

7. Enter the absolute physical path to the folder in your local file system that you want to use for archiving. If you checked the "Save export..." checkbox, you must enter a path or you get an error when you try to perform the operation.



8. Check "Delete data" to delete the data. You will lose any data that you haven't exported previously or as part of this operation.



9. You should export all data before deleting it.



10. Click Submit to export (and also delete if you checked the delete box) all the application data that meets your criteria.

---

Note	You can delete data without archiving it, although this is a very risky action to take. This action is not recoverable.

---

Exported process instance data is written to flat files in a directory the administrator specifies. Each process instance's data is exported to a separate file. The file name for each process instance is generated automatically in the following format:

process_instance_applicationName_processInstanceID_year_month_day_h our_minute_second

For example:

c:\tmp\process_instance_CreditHistory_10_1999_10_11_10_31_51.xml

Here, the archival file was written to the directory c:\tmp\, the application name is CreditHistory, the process instance ID is 10, and the archival was done on October 11, 1999 at 10:31 and 51 seconds.

Exported data is stored in an xml file with the following format:

<PROCESS_INSTANCE> <INSTANCE_DATA>

This section contains data from the process_instance table.

</INSTANCE_DATA> <HISTORY_EVENT_LIST> <HISTORY_EVENT>

This section contains data from one history event in the history table. There may be more than one history event listed here.

</HISTORY_EVENT> </HISTORY_EVENT_LIST> <DATA_ELEMENT_LIST>

This section contains a list of all data elements and their corresponding values. This section also contains custom field data.

</DATA_ELEMENT_LIST> </PROCESS_INSTANCE>