Deploying an Application

After an application is developed, it is typically deployed on a test system or on a production system. To help you with the deployment process, Process Commander provides application rules and utilities to help you package an application and import it to the another system.

About Roles and Responsibilities

Application deployment typically involves several roles that are responsible for performing key tasks. These roles and responsibilities include: System architect and technical lead Acts as lead developer on project Assists in defining rules and RuleSets to be exported Ensures that other developers have checked in all the rules Completes development test cases prior to deployment to QA Release engineer Receives export files that are imported into the deployment system Imports rules and data into the deployment system Installs other necessary components (external to Process Commander) Runs verification test programs developed by the technical lead Administrator Runs reports to plan for rules move Oversees creation of export files Verifies version numbers of exported RuleSets Coordinates transfer of rules with release engineering Performs additional system configuration, if necessary, according to technical lead requirements

Note: These roles are functional descriptions; specific job and role titles in your organization may be different. For example, one individual may perform tasks for several roles, or more than one individual may perform a single role.

Before You Begin

Before you move an application to another Process Commander system, consider the following guidelines: You must have administrator privileges on both the source and destination systems. It is best if the versions of Process Commander are the same on both systems. The version of Process Commander on the destination system must be the same or higher than that of the source system. For example, you cannot move a RuleSet created in version 05-03-06 to a system based on version 05-03-01. Determine the RuleSet prerequisites of the RuleSet(s) you want to move. Determine whether the dependencies are already present on the destination system or whether you must move them,

too. If you do need to move them, be sure to do so in the order that matches the dependency relationship. Also, ensure that these dependencies are maintained after uploading the application. Note: See "Step 6: Upload and Import Rules and Data" on page 4-31 for more information.
[HowTo]

Step 4: Create a Product Rule

A product rule (Rule-Admin-Product rule type) identifies all the RuleSets, versions, data objects, and other parts of an application, such as an organizational hierarchy, workbaskets, access groups, and operators. When you define a product rule instance, you specify the following information: The intended name and version of the product. The name must start with a letter and contain only alphanumeric characters. The version can include only alphanumeric characters, periods (.), and hyphens (-); it need not match a RuleSet version. The RuleSets and versions to include. The data instances used in the application.

Perform these steps to create a product rule instance.

Step 1: Open the form and create a new instance

1. 2. 3. 4. 5. From the Rules by Type explorer, select SysAdmin > Product. Click New. The New form appears. Enter the name and version of the product. The .zip extension is not required. Select your RuleSet name and version. Click Create. The Product form appears.

Step 2: Specify the RuleSets and Versions

On the Contents tab of the form, specify the RuleSets and versions. 1. 2. Enter the RuleSets and versions that together define the application or product. Specify the RuleSet version to export. You can choose only RuleSet versions that are direct or indirect prerequisites of the RuleSet and version of this rule.

Here is an example of a completed RuleSet and Version array (Figure 4-10):

Figure 4-10. Order of RuleSets The versions you enter designate the highest version within a revision level you want to export; the value you enter includes all lower revisions. For example, in Figure 4-10, the entries have the following meaning: ALL - Export all the versions belonging to the MyCo RuleSet. 02 - Export all versions equal to and lower than major version 02 of MyCoIns. 01-03 - Export all versions equal to or lower than minor version 01-03 of MyCoUtilities. 05-03-10 - Export all versions equal to or lower than 05-03-10 of Pega-ProCom.

When to use a product patch rule

Use a product patch rule instance (Rule-Admin-Product-Patch rule type) to package a single minor version identified by a full 6-digit version number in the form NN-NN-NN. For example, if you enter version 01-0110 in the Product form, the ZIP file can include rules from versions 01-01-01 through 01-01-10. If you enter 01-01-10 in this field of the Product Patch form, only rules from a single exact version 01-01-10 are placed in the ZIP file. Creating a product patch rule is like creating a product rule (as described in this section), with the following exceptions: The New form requires a revision number as a third key part. You must identify the data instances with a when rule. The patch rule does not contain a Query Data Instances section.

Step 3: Specify the data classes and instances

For an application to run correctly on the destination system, you must specify the data classes and instances that you are exporting, including all the data classes that are part of the product. The technical lead should specify these class names for you, because they vary for each installation. The classes include instances for the organization structure, security (access groups), connections to databases, external systems, and other Process Commander system-related instances. You specify the data classes and instances in the Data Instances to Include section, as shown in Figure 411.

Figure 4-11. Data Instances to Include Section

To include data classes:

You must include the following: Database table names (see Chapter 5, "Managing the Data") Class groups and database table maps (see Chapter 5) Access groups (see Chapter 6, "Configuring Access Rights")

Operator IDs (see Chapter 6) Organization (see Chapter 3, "Setting up the System") Divisions (see Chapter 3) Organization units (see Chapter 3) Workbaskets (see Chapter 3) Work groups (see Chapter 3)

Include other configuration and system-related classes used by the application, such as: Connector configurations (database, SOAP, JMS, and so on) Service configurations (SOAP, e-mail, and so on) Spellchecker properties Agents, nodes, and requestors

Caution: Ensure that any necessary database table maps are exported. If they are missing, data objects saved during application processing will be assigned by default to the pr_other table. Also, include Class Group records (Data-Admin-DB-ClassGroup), which can be used to help diagnose application-processing issues. See Chapter 5, "Managing the Data," for more information on table mapping.

To specify the data instances:

You identify the data instances to include in the ZIP file on the Product rule form. You can use either of these methods: When rules (Rule-Obj-When) Query Data Instances feature

Carefully consider any dependencies between data instances or between data instances and your rules. During uploading, data instances that are already present are not overwritten unless you specify that they should be.
[HowTo]

To specify when rules:

The easiest way to identify data instances is to create a when rule that applies to the Data- base class and that evaluates for the property value of the pxInsName property for your application, sometimes called the "visible key." The new when rule appears in the Smart Prompt list under the When Filter heading. The pxInsName property of a rule or class is defined in the top-level class of your application, so it is present in every class and rule that applies to that class or inherits from it. For example, if the top-level class of your application is named MyCo-, you can create a when rule that evaluates for the condition in which pxInsName is MyCo, as shown in Figure 4-12.

Figure 4-12. When Rule for a Product Archive The entire string in the Value field is: @(Pega-RULES:String).contains(.pxInsName, MYCO) You could also use this when rule for each data class that has instances you want to include in your product rule, as shown in Figure 4-13.

Figure 4-13. Using One When Rule in a Product Rule

[HowTo]

To use the Query Data Instances feature:

The Query Data Instances feature allows you to pick a set of instances from a list. Pegasystems suggests that you use Query Data Instances only when specifying a small number of instances, because the when rule method can more efficiently handle large numbers of instances and is less prone to error. 1. 2. 3. Click the top field in the Query Data Instances section and select the data class of the instance you want to include. Click Query. Select the instance you want from the list that appears, and then click OK in the list.

Information about the instance is set in the InsKey, Label, and ObjClass fields. You can edit the value of the Label field, but do not change the values in the InsKey or ObjClass fields. For example, Figure 414 shows the entry for an operator named sampleuser@samples.com:

Figure 4-14. Example of a Queried Data Instance Listed in a Product Rule

Step 4: Complete and save the rule

1. 2. On the History tab, enter a full description of the rule and information on its use. Save the rule.

Step 5: Create an Archive ZIP File

You package product or product patch rules in archive ZIP files to move applications from one Process Commander server to another. A product or product patch ZIP archive contains the following elements: All the RuleSets specified, including the product or patch rule, the RuleSet rules, the RuleSet version rules, versions, and the application rules associated with RuleSets. All the data instances identified by the queries or when rules (Rule-Obj-When) used by the product or patch rule, such as data objects, and other parts of an application, including an organizational hierarchy, workbaskets, access groups, and operators.

To create an archive ZIP file from the rule form:

1. Select View > Rules > Checkouts to reconfirm that all the rules are checked in, including the product rule. An error is reported identifying each checked-out rule. Neither the original version nor the checked-out version of the rule is included in the ZIP archive. On the Contents tab in the Product or Product Rule form, click Create Zip File. Enter a file name and click OK.

2. 3.

The system displays the message "Getting records from the database. Please wait.", and then an inprogress display appears. (This step can take several minutes to finish.) 4. 5. 6. If there are errors, click on the Total Number of Errors link to display a list of them. Correct the errors and retry the export process. When the export process is successful (0 errors), click on the Zip File Created link to save the file to a local directory. To confirm that the operation was successful, use the Class explorer to examine the most recent instance of Log-PegaRULESMove.

Note: See "Using the Export Rules/Data Tool" on page 4-34 for more information.

Step 6: Upload and Import Rules and Data

After you have created an archive ZIP file, you upload it to the ServiceDirectory directory in the destination Process Commander server. You then import the file by extracting its contents and inserting them in the PegaRULES database as rules and data instances.
[HowTo]

To upload and import the ZIP archive file:

1. 2. Select File > Import Archive to open the Import Rules/Data tool. In the Select Import Mode field, do either of the following: Select Local Zip File if the file is located on a local directory. Click the Browse button next to the File Name field to select the file. Click Upload File. The wizard uploads the file to the Process Commander ServiceDirectory directory and displays the message "File Uploaded Successfully." Select Zip File on Server if the file is already on the server directory (typically the ServiceDirectory).

3.

Select one or more of the following options as appropriate: Compile Libraries - Select this option when the RuleSet contains utility function or utility library rules, and you want the wizard to compile the libraries as soon as the rules are loaded. You can recompile all the libraries later by using the Extract Files option in the System Management application. Overwrite Existing Data - Select this option to overwrite with the data instance in the archive ZIP file any existing data instances with the same ID (pzInsKey) that are already present in this destination Process Commander database. Overwrite Existing Rules - Select this option to overwrite with the rule instance from the archive ZIP file any rule instances with the same RuleSet name, RuleSet version, and ID (pzInsKey) that are already present in the destination Process Commander database.

Note: See "About the Import Process" on page 4-37 for more information about using the Overwrite Existing Rules/Data options. 4. 5. Click Import. The import process may take several minutes. If there are errors, click Total Number of Errors in the lower-right corner of the display form to see the error message(s). Correct the errors and create a new ZIP archive file for import.

Step 7: Verify the Import

After the import is complete, perform the following actions: 1. 2. Adjust your access group, if necessary, to give yourself access to the uploaded rules, data, work pools, and application rules. Log out and then log in again with the adjusted access group to review the results.

(Optional) Step 8: Rebuild Libraries

If the product rule, patch rule, or a RuleSet ZIP included library rules and you did not select the Compile Libraries option when you imported the ZIP, you must rebuild the libraries now.
[HowTo]

To rebuild the libraries:

1. 2. From the menu, select Tools > System Management Application. In the System Management application, select Administration > Rule Utility Library Extractor.

3. 4.

Enter the name of the RuleSet and the name of the library rule. Click Extract Libraries. Process Commander extracts the rule, generates Java source files for the rule, and compiles the source file into a Java class.

Using the Export Rules/Data Tool

In addition to using the product or product patch rule forms, you can create an archive ZIP file using the Export Rules/Data tool. The ZIP file can contain: All rules in a RuleSet and Version (or all versions). The archive contains all the rules from the RuleSet specified, including the RuleSet rule, the RuleSet version rule, and the application rule associated with the RuleSet (if any). Data is not included in the file. A class instance is not created. Rules and data defined by an existing product rule (Rule-Admin-Product rule type). Rules and data defined by an existing product patch rules (Rule-Admin-Product-Patch rule type).

You can also use the tool to copy a previously created ZIP file from the Process Commander server to a local directory.
[HowTo]

To create a ZIP archive file:

1. 2. 3. Verify that the rules designated for the archive are checked out. From the menu, select File > Export Archive to open the Export Rules/Data tool. In the Select Export Mode field, select a mode to determine the scope of the contents of the ZIP file: -

By RuleSet/Version - To create a ZIP archive containing all rules in a RuleSet and Version (or all versions). By Product - To create a ZIP archive containing rules and data defined by an existing product rule (Rule-Admin-Product rule type). By Patch - To create a ZIP archive containing rules and data defined by an existing product page rules (Rule-Admin-Product-Patch rule type).
If you selected By RuleSet/Version, select a RuleSet and version from the lists in the RuleSet and RuleSet Version fields. Select a single version for that RuleSet, or All Versions. If you selected By Product, or By Patch, select the name and version from the field lists. Note that the product and patch rule version is not necessarily related to RuleSet Versions.

4.

Do one of the following: -

5.

Enter a filename for your ZIP file in the File Name field. Use a file name that is valid for both the destination server and the current server; they may be hosted on different Windows or UNIX platforms. The ".zip" suffix is optional. Do not include spaces or an equals sign character (=) in the file name. Click Create ZIP File. The system displays the progress of the extraction, which may require one to several minutes. A progress bar shows the count of rules extracted.

6.

7.

If errors are reported, click the Total Number of Errors link in the lower right corner of the display form to see the error messages. You can print the list for later analysis. Errors are logged as instances of Log-PegaRULESMove-Error. To save the file to a local directly, click the Zip file created link. Choose Save in the pop-up window. (You can download the file later using the ZIP File on Server option.) Click Close.

8. 9.

[HowTo]

To download a previously zipped file from the ServiceExport directory:

1. 2. 3. From the menu, select File > Export Archive. In the Select Export Mode field, select Zip File on Server. Select the file to download and click Download Zip File. The standard Windows File Download window appears.

Note: The tool locates only files with the .zip extension in lowercase letters. 4. Specify a name and location for the downloaded file and click Save. The ZIP file is saved to your system.

About the Import Rules/Data Tool

The Import Rules/Data tool lets you import into a Process Commander system the contents of an archive ZIP files produced by the following Process Commander features: Export Rules/Data tool. See page 4-34. Purge/Archive wizard. See chapter 5, Purging and Archiving Work Objects. Product Package wizard. See page 4-44. Product or Product Patch rule forms. See pages 4-30.

See Step 6: Upload and Import Rules and Data on page 4-31 for a description of how to use the tool.

Application Deployment: Walking Through the Steps

The application deployment process comprises the following steps (Figure 4-9):

Step
1 2 3 4 5 6 7 8

Description
Check in rules to be deployed Run rule reports to confirm that the appropriate rules are checked in Lock the RuleSet versions Create a product rule Create a product archive ZIP file Upload and import the archive file to the system Verify the import (Optional) Rebuild libraries

Page
4-22 4-22 4-23 4-23 4-30 4-31 4-32 4-33

Figure 4-9. Application Deployment Steps The procedures on the indicated pages describe product rule deployment. Product patch rule deployment is similar, with the exceptions described on page 4-25.

Step 1: Check In Rules

As the system administrator, work with the technical lead to ensure that all the rules are checked in to their respective RuleSets before you lock them for export. Checked-out rules will not be included in the export file and, therefore, will not be moved from the source system.

Step 2: Run Rule Reports

Run rule reports to ensure that all the rules are checked in and to ascertain the number of rules to be moved. To see all the rules that are checked out, select View > Rules > All Checkouts from the menu. This report also indicates the developer who has the rule checked out. You can view the checked-out rules organized by RuleSet and version or by version and RuleSet.

Step 3: Lock the RuleSet Versions

As a best practice, lock the RuleSets and the application rules to prevent unexpected changes. For RuleSet versions, the locking fields are on the Security tab. For application rules, the locking fields are on the Publish tab. Lock each RuleSet version and supply a password. Note the password in a safe location. Caution: Do not unlock and make changes to a RuleSet after deploying it to a new location. Doing so will likely invalidate the versioning process.

About Deployment Steps

There are four overall steps for deploying a Process Commander application. It is important to note that verification testing occurs at each step of the process. Such testing involves a technical lead who provides an activity or process to ensure that the system is functionally correctly. Typically, you use archive ZIP files to implement your deployment strategy as follows: Product archives to build the initial implementation or deploy an application that contains a large number of rule updates. Product patch archives to deploy bug-fix versions on subsequent production releases. If there are a large number of patch versions, it is suggested that you skim them to the next major or minor version. See "Skimming to a New Version on the Same System" on page 4-56.

Step 1: First Deployment to Acceptance Testing

The first deployment to a new acceptance test server involves creating a new product rule, which captures the locked application RuleSets and data elements in a product archive (.zip). The ZIP file is imported to the destination server and verification is performed to ensure that the application is performing correctly. This step involves three tasks: 1. 2. 3. Follow the application deployment steps to create a new product archive. Import the product archive to acceptance test. Add the RuleSets/Versions to the acceptance test profiles.

Step 2: Development Continues

Because the RuleSets sent to testing are locked, development increments them to the next version and continues work on the development server. This step involves four tasks: 1. 2. 3. 4. Create a new RuleSet Version on the development server. Enter the correct prerequisites. Adjust the Access Groups to reflect the new RuleSet Version. Save the new rules (or changes) in a higher revision (performed by the developer).

Figure 4-22 illustrates the tasks involved in the first deployment and continuation of development. Note that the product archive also contains application data.

Figure 4-22. First Deployment to Acceptance Testing

Step 3: Rule Revisions Deployed to Testing

When subsequent rules and fixes need to be deployed to acceptance testing, create a product patch archive that stores all the rules of the new locked RuleSet (for example, APPRuleSet:01-01-02). A product patch contains only the rules from a single version of a RuleSet. You also need to adjust any data configurations and access to the new RuleSet Versions. Note: Access is discussed in Chapter 6 "Configuring Access Rights." This step involves four tasks: 1. 2. 3. 4. Lock the RuleSet to be deployed (APPRuleSet:01-01-02). Deploy a product patch ZIP file to capture only APPRuleSet:01-01-02 and any additional data. Upload and import the product patch for an acceptance test. Continue development.

Figure 4-23 illustrates the tasks involved in rule revision deployments and continuation of development. Note that the product patch archive also contains application data.

Figure 4-23. Rule Revision Deployments to Acceptance Testing Note: If there are large numbers of rule updates, you can choose to migrate the application in a product archive.

Step 4: Production Deployment

When an application goes into production, all the RuleSets that make up the application are locked (including all the prerequisite RuleSets if the production system is empty). The product archive is initially moved to the production system. Use product patches for subsequent updates. Note: See Chapter 6 "Configuring Access Rights," for information on configuring access rights. Figure 4-24 illustrates the tasks involved in deploying the final application to the production system. Note that the product archive also contains necessary application data.

Figure 4-24. Final Deployment to Production Note: This example assumes that no previous applications are deployed on the production server.