PEGA 7 PLATFORM. Pega Platform INSTALLATION GUIDE 7.3. IBM DB2 for z/os. IBM WebSphere

Transcription

1 PEGA 7 PLATFORM Pega Platform INSTALLATION GUIDE 7.3 IBM DB2 for z/os IBM WebSphere

2 Copyright 2017 Pegasystems Inc., Cambridge, MA All rights reserved. Trademarks For Pegasystems Inc. trademarks and registered trademarks, all rights reserved. All other trademarks or service marks are property of their respective holders. For information about the third-party software that is delivered with the product, refer to the third-party license file on your installation media that is specific to your release. Notices This publication describes and/or represents products and services of Pegasystems Inc. It may contain trade secrets and proprietary information that are protected by various federal, state, and international laws, and distributed under licenses restricting their use, copying, modification, distribution, or transmittal in any form without prior written authorization of Pegasystems Inc. This publication is current as of the date of publication only. Changes to the publication may be made from time to time at the discretion of Pegasystems Inc. This publication remains the property of Pegasystems Inc. and must be returned to it upon request. This publication does not imply any commitment to offer or deliver the products or services described herein. This publication may include references to Pegasystems Inc. product features that have not been licensed by you or your company. If you have questions about whether a particular capability is included in your installation, please consult your Pegasystems Inc. services consultant. Although Pegasystems Inc. strives for accuracy in its publications, any publication may contain inaccuracies or typographical errors, as well as technical inaccuracies. Pegasystems Inc. shall not be liable for technical or editorial errors or omissions contained herein. Pegasystems Inc. may make improvements and/or changes to the publication at any time without notice. Any references in this publication to non-pegasystems websites are provided for convenience only and do not serve as an endorsement of these websites. The materials at these websites are not part of the material for Pegasystems products, and use of those websites is at your own risk. Information concerning non-pegasystems products was obtained from the suppliers of those products, their publications, or other publicly available sources. Address questions about non-pegasystems products to the suppliers of those products. This publication may contain examples used in daily business operations that include the names of people, companies, products, and other third-party publications. Such examples are fictitious and any similarity to the names or other data used by an actual business enterprise or individual is coincidental. This document is the property of: Pegasystems Inc. One Rogers Street Cambridge, MA USA Phone: Fax: (617) DOCUMENT: Pega Platform Installation Guide SOFTWARE VERSION: 7.3 PUBLISHED: Friday, June 30, 2017

3 CONTENTS Installation 7 Related information 7 Pega Platform architecture 8 Planning your deployment 8 Split-schema and single-schema configurations 9 Apache Ignite client-server clustering topology 10 Deployment methods 11 System requirements 11 UI-based installation tool (Installation and Upgrade Assistant) 12 Application server 12 Application server memory requirements 12 Database server 13 Pre-installation tasks 13 Reviewing the documentation 13 Selecting a transport-layer encryption method 14 Configuring the Java Platform 14 Configuring storage and logging 14 Synchronizing time zones, character encoding, and regional settings 14 Setting up the database server 15 Verifying the database configuration 15 Enabling support for stored procedures 15 Enabling support for user-defined functions 15 ZPARM settings 16 Managing code page translations 17 Database users 17 Deployment user 17 Runtime users 18 Configuring site-dependent properties 18 Allocating space to storage groups 20 Configuring your IBM DB2 for z/os database 21 Database users 21 Pega Platform Installation Guide 3

4 Creating an empty database 21 Installing the Pega Platform 23 Preparing to install 23 Running the Installation and Upgrade Assistant (IUA) 24 Editing the setupdatabase.properties file 27 Database connection properties 28 Optional: Enabling Kerberos authentication 29 Installing from the command line 30 Using JCL 31 JCL Procedure 32 Setting up the application server 34 Preparing to configure the application server 34 EAR file and WAR file considerations 35 Data source resources, data source entries, and default schema entries 35 Optional: Enabling Apache Ignite client-server mode 36 Deploying and starting the Apache Ignite servers 36 Configuring the application server 38 Creating binding identifiers 39 Configuring IBM WebSphere for IBM DB2 for z/os 40 Using the IBM WebSphere Administrative Console 41 Setting JVM properties 41 Creating URL providers and setting the temporary directory 42 Creating a JDBC provider 43 Creating a data source 44 Defining database authentication credentials 46 Configuring the IBM WebSphere WorkManager 48 Setting the HTTP transport channel custom property 49 Configuring pass-by-reference 50 Deploying the Pega Platform application archives 50 Deploying the System Management Application and on-line help 53 Assigning the PegaDiagnosticUser Role to your System Management Application users 54 Post-deployment configuration 57 Pega Platform Installation Guide 4

5 Starting the Pega Platform applications 57 Logging in to the Pega Platform and changing the administrator password 57 Setting the database name for schema import 58 Enabling online help and the System Management Application 59 Configuring Directed Web Access 60 Configuring search index host node settings 60 Resizing the Pega Platform log files 61 Resizing the database 61 Installing Industry applications 62 Enabling server-side screen captures for application documents 62 Configuring PhantomJS REST server security for including screen captures in an application document 63 Enabling operators 64 Appendix A Properties files 66 IBM DB2 for z/os 66 Appendix B Troubleshooting installations 67 Recovering from a failed installation 67 PEGA0055 alert clocks not synchronized between nodes 68 ClassNotFoundException error session persistence 68 System hangs with no error message insufficient memory 68 Obtaining database connection information 69 Appendix C Optional: Generating and applying DDL 70 Generating the DDL file 70 Applying the DDL file 71 Editing the setupdatabase.properties file to bypass DDL generation 71 Appendix D Installing user-defined functions 72 Appendix E Secured mode 74 Pega Platform Installation Guide 5

6 Pega Platform Installation Guide 6

7 Installation This guide describes how to install a new instance of the Pega Platform on a system with IBM DB2 for z/os and IBM WebSphere. See the Platform Support Guide on the PDN for a list of supported platforms. To upgrade, see the Pega Platform Upgrade Guide. To update from Pega 7.1.x, see the Pega Platform Update Guide. Installing the Pega Platform is a multiple step process that involves configuring your database and application server, loading rules into the database, and then deploying application archives to the application server. The Pega Platform supports different deployment topologies and configuration options that affect how the supporting infrastructure is configured and managed after installation. Engage your database administrator and any other infrastructure resources as soon as possible in the planning process. Related information The Pega Discovery Network (PDN) at is Pegasystems' online documentation and information site. To access the latest documentation, use the Support menu. Pega 7 Platform Support Guide The Platform Support Guide lists the databases, drivers and application servers supported for this release. Deployment guides The PDN includes the latest installation, upgrade, and update guides. Pega Platform release notes The release notes include information about deploying the Pega Platform that supplement the instructions in this guide. Review the release notes before you continue. Pega Platform Updated help files Pegasystems provides updated help on the PDN. To obtain these updates, download the current prhelp.war file from the PDN. Pega Platform Business Intelligence Exchange User Guide The Business Intelligence Exchange User Guide describes how to install the Business Intelligence Exchange (BIX) product. BIX is included in the full distribution image, but has a separate installer.

8 Installation System Management Application Reference Guide The optional System Management Application monitors and controls caches, agents, requesters, listeners, and other processing. Pega Platform architecture The Pega Platform is a Java EE-compliant enterprise application that requires an application server and a database server: The application server hosts the Pega Platform application archives and also provides interconnectivity to other systems through various protocols. The database server stores the rules, data, and work objects used and generated by the Pega Platform. Application users and developers typically access the Pega Platform through a web browser. Applications can also expose HTTP-based services (for example, SOAP, REST, or HTTP) for administration or process automation in a headless environment. Planning your deployment The Pega Platform supports several configuration options that can affect the choices that you make during the deployment. Before beginning, read this section thoroughly. Do not change your environment while you are deploying the Pega Platform. For example, if you are making changes to your application server, or database server, do so before you deploy the Pega Platform. Choose a configuration type: single-schema or split-schema configuration. Pegasystems recommends a split-schema configuration. See Split-schema and single-schema configurations. Choose a clustering topology: Hazelcast or Apache Ignite; standard embedded mode or clientserver mode. Embedded Hazelcast is the default clustering topology. If you want to use Apache Ignite clustering topology, you need to enable Apache Ignite cluster protocol in prconfig.xml file. You can use Apache Ignite embedded mode only for small clusters. If you want to use Apache Ignite client-server mode, you need to additionally force the Pega Platform node to start in client mode and open ports for Apache Ignite. See Apache Ignite client-server clustering topology. Verify the Business Intelligence Exchange (BIX) and Pega Platform product versions. Release versions of the Business Intelligence Exchange (BIX) are synchronized with release versions of the Pega Platform Installation Guide 8

9 Installation Pega Platform. BIX is included in the full distribution image, but has a separate installer. Verify that the version of BIX is the same as the version of the Pega Platform. For information about installing BIX, see the Pega Platform BIX User Guide. Choose a deployment type: UI tool or command line. See Deployment methods. Choose whether to use Kerberos functionality. Kerberos is a computer network authentication protocol that allows nodes communicating over a non-secure network to prove their identity to one another in a secure manner. If you enable Kerberos authentication, you must use the command line to deploy the Pega Platform. Choose whether to have the deployment process make changes directly to the database. You can either have the Pega Platform apply changes directly to your database, or generate DDL files of changes for your database administrator to apply. For information about manually generating and applying DDL, see Appendix C Optional: Generating and applying DDL. Choose whether to cluster the Pega Platform nodes. The Pega Platform supports clustered nodes without special configuration, but you will make different choices about ports, indexes, and clock synchronization depending on your node configuration. Determine the best configuration for your database. Involve your database administrator in these decisions. For more information, see PDN > Support. Choose either dual-user or single-user configuration. In a dual-user configuration, an Admin user is granted full privileges, and a Base user is granted a smaller subset of privileges. In the singleuser configuration, a single Base user is granted full privileges. For more information about user configuration, see Database server setup. Split-schema and single-schema configurations There are two configuration types: single schema and split-schema. Pegasystems recommends splitschema configurations, particularly in critical development environments such as quality assurance, staging, and production. Single-schema configuration One schema contains all rules and data objects. Split-schema configuration The rules and data objects reside on separate schemas: A Rules schema contains rules tables and associated data and objects. A Data schema contains transaction data, including work objects. Pega Platform Installation Guide 9

10 Installation With a split-schema configuration, you can upgrade one environment, and then migrate the upgraded objects to other environments. In a split-schema configuration, the Pega Platform uses the Java Naming and Directory Interface (JNDI) standard to identify and access the appropriate schema. One of the benefits of using JNDI is that it allows the Pega Platform to access different schemas while using only a single data source. The following diagram illustrates the difference between a single-schema configuration and a splitschema configuration. Apache Ignite client-server clustering topology You can deploy Pega Platform in client-server mode that uses Apache Ignite. Client-server mode provides greater cluster stability in large clusters and supports the ability for servers and clients to be separately scaled up. Use this mode for large production environments that consist of more than five cluster nodes or if you experience cluster instability even in clusters that contain fewer nodes. The number of nodes in the cluster that can lead to cluster instability depends on your environment, and switching to client-server mode should be determined individually. Client-server mode is a clustering topology that separates Pega Platform processes from cluster communication and distributed features. Clustering technology has separate resources and uses a different JVM from Pega Platform. Pega Platform Installation Guide 10

11 Installation Client nodes - Pega Platform nodes that perform application jobs and call the Apache Ignite client to facilitate communication between Pega Platform and the Apache Ignite servers. Servers - The stand-alone Apache Ignite servers that provide base clustering capabilities, including communication between the nodes and distributed features. You must have at least three Apache Ignite servers for one cluster. For more information about enabling client-server mode, see Optional: Enabling Apache Ignite client-server mode. Deployment methods You can deploy the Pega Platform either with the UI tool or from the command line. This guide includes instructions for both methods. UI tool Use the UI-based Installation and Upgrade Assistant to install either the rulebase or the rulebase and the schema. Command line Run scripts to deploy the Pega Platform. Regardless of whether you use the UI tool or the command-line scripts, you might need to edit the setupdatabase.properties file that controls the behavior of the following scripts: The generateddl.bat or generateddl.sh script generates an SQL file that your database administrator can use to apply schema changes to the database. You can run this script regardless of whether you use the IUA or the command-line script. The install.bat or install.sh script performs the following functions: Deploys the most recent version of the Pega Platform. Specifies whether to generate a DDL file of changes to the database. Enables Kerberos authentication. If you use the IUA to install, you do not use the install.bat or install.sh script. System requirements Ensure that your system meets the minimum requirements. Pega Platform Installation Guide 11

12 Installation UI-based installation tool (Installation and Upgrade Assistant) If you plan to use the UI-based Installation and Upgrade Assistant ensure that the system on which you will install meets these minimum system requirements in addition to all other requirements: Windows or Linux operating system 1.25 GB minimum available memory 10 GB minimum disk space plus at least 8 GB available space in the temporary directory of the root file system Java Platform, Standard Edition Development Kit (JDK) Application server The application server requires: A supported 64-bit JDK. See the Platform Support Guide on the PDN for a list of supported versions. IBM WebSphere Network Deployment requires that the deployment manager, the node agent, and the application servers are all on the same JDK version: either JDK or JDK GB minimum free disk space. You might need additional storage space for debugging and logging. Install only the Pega Platform be installed on the application server. Application server memory requirements The Pega Platform runs in memory (heap) on Java Virtual Machines (JVMs). In general, all activity is distributed over multiple JVMs (nodes) on the application server. Standard suggested system heap size is 4-8 GB based on monitoring of memory usage and garbage collection frequency. Larger heaps are advisable if your applications allow a high number of concurrent open tasks per session or cache a large collection of transaction or reference data. Pega Platform Installation Guide 12

13 Installation Do not deploy the Pega Platform in an environment where the heap size exceeds the vendorspecific effectiveness limit. IBM JDKs use compression to minimize the cost of large heaps. The compression option is labeled CompressedRefs and is effective up to 28 GB. In current 64-bit JVMs, compression is enabled by default. The host application server memory size must be at least 4 GB larger than the Pega Platform heap size to allow space for the operating system, monitoring tools, operating system network file buffering, and JVM memory size (-XMX option). The minimum host application server memory size is 8 GB: 4 GB heap + 4 GB for native memory, operating system, and buffering If the server does not have enough memory allocated to run the Pega Platform, the system can hang without an error message. The correct memory settings depend on your server hardware, the number of other applications, and the number of users on the server, and might be larger than these recommendations. Database server Confirm that your database server meets the requirements in the Pega Platform Support Guide on the PDN. Pre-installation tasks Complete the tasks in this section before you begin the installation. Reviewing the documentation Before you begin the installation, review the related information available on the PDN: Platform Support Guide Review the Platform Support Guide before you install the Pega Platform to verify that your database and application servers are supported. Pega 7 Release notes Review the important information in the release notes before you continue. Pega Platform Installation Guide 13

14 Installation Selecting a transport-layer encryption method Pegasystems recommends that you use a strong transport-layer encryption method (for example, Transport Layer Security 1.2) to secure Pega Platform web applications. This encryption requires that you create and install transport-layer security and secure socket layer digital certificates on your application server for the Pega Platform. Before you continue, determine what transport-layer encryption method you will use. For more information, see the documentation for your application server. Configuring the Java Platform 1. Set JAVA_HOME to the root directory of the JDK. 2. For Java 8, remove from the PATH any references to a Java shortcut. Configuring storage and logging 1. Allocate enough storage to accommodate debugging and other logging requirements. 2. Configure logging to avoid writing logs to the directory that contains the application server runtime components. Synchronizing time zones, character encoding, and regional settings Verify that your database server, application server, and the system on which you are running the installation use the same: Time zone Character encoding (UNICODE or EBCDIC) Regional settings/locale Pega Platform Installation Guide 14

15 Setting up the database server This section describes how to prepare and configure your database server: Configure the database users. Create an empty database. Verifying the database configuration Before you begin preparing your database, confirm that your database server is installed and running. Verify that your database meets the requirements described below. Your system includes a supported version of the JDBC4 driver and IBM DB2 for z/os license jar for your version of the database from IBM. Operating system-level users are defined with the appropriate authorizations. The LOGFILSIZ parameter is at least 4096 pages. The default logfile size is 1000 pages. Note: If you change the LOGFILSIZ parameter, restart the database to make sure the settings are loaded into the database correctly. If you plan to use user-defined functions (UDF), Java is enabled in the database and there is a Javaenabled workload manager configured. Enabling support for stored procedures Pega Platform uses native stored procedures, not external stored procedures. Verify that your site supports SQL-based stored procedures. Enabling support for user-defined functions To support user-defined functions (UDF) installed by the Pega Platform, provide a dedicated Javaenabled Work Load Manager (WLM). Define the WLM application for the Pega Platform to the system WLM with the MVS WLM utility tool.

16 Setting up the database server Ensure that the new MVS WLM application is part of the MVS WLM Policy that is in effect on the z/os LPAR. You will specify this WLM as the #WLMUDF property in the DB2SiteDependent.properties file found in the directory Pega-image/scripts/config/db2zos. You must refresh this WLM application after the UDFs have been loaded. You can do this from the z/os console or from a tool like SDSF. ZPARM settings Review the following ZPARM settings with your z/os system programmer before you continue: CACHEDYN=YES CMTSTAT MAY BE INACTIVE OR ACTIVE DESCSTAT=YES. (Mandatory) IDBACK=200 (Minimum) IDFORE=200 (Minimum) IDTHION=300 (Minimum if CMTSTAT=INACTIVE) LOBVALA=10240 (minimum) LOBVALS=2048 (minimum) NUMLKTS=5000 (Minimum) NUMLKUS=30000 (Minimum) OPTIOWGT=ENABLE OPTIXOPREF=OFF OPTXQB=OFF (TEMPORARY A/O 5/09 DUE TO IBM APARS) STATCLUS=ENHANCED SKIPUNCI=YES Pega Platform Installation Guide 16

17 Setting up the database server Managing code page translations If you are installing to a UNICODE database, ensure that the appropriate code page translation is configured across all tools used on the platform, including FTP, TSO, IBM Data Studio, and SPUFI. Database users This guide refers to the following database users: Deployment user The user who runs the installation. After the installation, you can remove this user. Run-time users: These users perform actions on the Pega Platform after the installation. In a dualuser configuration, an Admin user is granted full privileges, and a Base user is granted a smaller subset. Pegasystems recommends the dual-user configuration : Base user The user who will run the Pega Platform. For most run-time operations, the Pega Platform uses the Base user and associated data source. Admin user An optional user provided to the Pega Platform that is preferentially used by certain features that require creating, modifying, or dropping database schema objects including System Management facilities and certain decisioning operations. Pegasystems recommends that you create the Admin user separate from the Base user, however, you can create a single Base user with both sets of privileges. If there is no separate Admin user, the Pega Platform attempts to use the Base user. Note: The user names must be in all capital letters in the DB2SiteDependent.properties file. Deployment user The Pega Platform requires IBM DB2 for z/os credentials to create the database and to access it once created. You provide the Deployment user name in the DB2SiteDependent.properties file. You need both the Deployment user name and associated password to configure data access for the Pega Platform in your application server. These credentials need to have permissions to perform the following actions: Log onto IBM s Time Sharing Option (TSO) Run z/os batch jobs Pega Platform Installation Guide 17

18 Setting up the database server Allocate Datasets (both z/os and zfs) Log onto IBM s UNIX System Services (USS) Update OMVS (USS) memory size to 2 GB (RACF example ASSIZEMAX ) Grant database CREATE, DROP and ALTER authority (at the database level and for all objects within the database) Grant database INSERT, UPDATE and DELETE authority. Grant database access to create and execute stored procedures and user-defined functions. Runtime users For split-user configurations, you have two users, Base and Admin, with different permissions. Admin user The database owner, #DBOWNR, with permissions to issue SQL CREATE, DROP and ALTER commands against the Pega Platform database instance. Base user The database user, #DBUSER, with permissions to issue SQL INSERT, DELETE, UPDATE, and SELECT statements. Configuring site-dependent properties Using the table of recommended values below as guidance, update the DB2SiteDependent.properties file with the correct values for your site. This file is located in the following folder: Pega-image/scripts/config/db2zos Note the following: #DBNAME is the database name assigned by your database administrator. The value you select here will be substituted everywhere in the target libraries that the database expects a valid database name. There are no additional special requirements for this name other than that it must be acceptable to DB2. The entire database must be able to be dropped and recreated. Carefully consider placing any non-pegasystems related database objects in this schema. #DBOWNR will be the database owner for the libraries copy of the Pega Platform database. Pega Platform Installation Guide 18

19 Setting up the database server This installation procedure assumes that #DBOWNR has DBADM on #DBNAME either directly through a grant or indirectly by processing a Secondary Authorization ID. The application servers can log on to this database using #DBOWNR. The installation procedure described here will create a PLAN_TABLE owned by #DBOWNR. #DBUSER will be the ID of the user who accesses the Pega Platform database. If your site strictly enforces segregation of duties, this userid can be used to run the applications. #DBUSER can only issue DML (select, insert, delete, update) commands while #DBOWNR can issue DDL as well as DML. By default, the Pega Platform installer takes the following actions: If you prefer to enable lock escalation, configure #BLBLCM and #TSPLCM to a non-zero positive integer before tailoring the libraries. Refer to your IBM DB2 for z/os manuals for details on setting these properties. Assign separate storage groups for table spaces, index spaces, and LOB table spaces. To keep all three object types in a single storage group, set #BLBSTG, #IDXSTG, and #TSPSTG to the same value. Segregate each object type into its own buffer pool. For the LOB buffer pools, set Deferred Write Threshold DWQT to zero. By default, the installation defines all LOB table spaces as LOG YES. Use the #DBOWNR userid to connect to the database. Variable with default value LOB parameters #BLBBFP=BP32K1 #BLBLCK=LOB #BLBLCM=0 #BLBLOG=YES #BLBPRI=14400 #BLBSEC=7200 #BLBSTG=Blob.Storage.Group.Name Your choice Description Blob 32 K Blob buffer pool. This must be different from the table space. Blob lock size Blob lock maximum Blob logging Blob primary allocation in pages Blob secondary allocation in pages Blob database storage group Pega Platform Installation Guide 19

20 Setting up the database server Variable with default value Index parameters #IDXBP=BP2 #IDXPRI=7200 #IDXSEC=7200 #IDXSTG=Index.Storage.Group.Name Tablespace parameters #TSPLCK=PAGE #TSPLCM=0 #TSPPRI=14000 #TSPSEC=7200 #TSPSTG=Table.Storage.Group.Name #TS32BP=BP32K Database access parameters #CCSID=EBCDIC #DBNAME=PEGDB #DBOWNR=PEGDBDBO #DBUSER=PEGDB #WLMUDF Your choice Description Index buffer pool Index primary allocation in pages Index secondary allocation in pages Index database storage group Table space lock size Table space lock maximum Table space primary allocation in pages Table space secondary allocation in pages Table space storage group Table space 32K buffer pool. This must be different from the Blob buffer pool. EBCDIC or UNICODE Database name Database owner Pega Platform database user Name of the dedicated Java-enabled Work Load Manager (WLM) for UDFs Allocating space to storage groups Identify the database space requirements for an initial install. Ensure that the Storage Groups and Buffer pools selected for use by the Pega Platform are created, and permission is granted to the #DBOWNR userid to use them. Allocate a minimum of 5 GB to the database and allow the database to grow. This minimum size allows you to load the initial Pega Platform rulebase and do simple development. Pega Platform Installation Guide 20

21 Setting up the database server Configuring your IBM DB2 for z/os database To prepare your IBM DB2 for z/os database server for use with the Pega Platform, complete the following steps: 1. Create database user accounts. 2. Create an empty database. 3. Create the database schema. Database users This guide refers to the following database users: Deployment user The user who runs the installation. After the installation, you can remove this user. Run-time users These users perform actions on the Pega Platform after the installation. In a dual-user configuration, an Admin user is granted full privileges, and a Base user is granted a smaller subset. Pegasystems recommends the dual-user configuration: Base user The user who will run the Pega Platform. Most run-time operations use the Base user and associated data source. Admin user An optional user provided to the Pega Platform that is preferentially used by certain features that require creating, modifying, or dropping database schema objects; for example, System Management facilities and certain decisioning operations. Pegasystems recommends that you use the dual-user configuration with separate Admin and Base users; however, you can create a single Base user with both sets of privileges. If there is no separate Admin user, the Pega Platform uses the Base user for all run-time operations. Creating an empty database Create a database with a minimum of 5 GB for the user tablespace. This minimum size allows you to load the initial rulebase and do simple development. Monitor the database use carefully. As development begins, the size of the database will need to increase significantly, depending on your use of the Pega 7 Platform and the number of users. Pega Platform Installation Guide 21

22 Setting up the database server For each schema that contains Pega Platform tables, allocate a 32K bufferpool, a 32K user regular tablespace, and a 32K user temporary tablespace. Pega Platform Installation Guide 22

23 Installing the Pega Platform Use one of these methods to install the Pega Platform: UI tool The Installation and Upgrade Assistant is a Java-based UI tool that sets up the Pega Platform rules schema in the database and loads the Pega Platform rules. Command-line script A command-line script automates the installation of the Pega Platform in headless environments. JCL JCL member scripts that generate the schema and apply the schema on the z/os system. Preparing to install Follow these steps to extract and validate the installation files: 1. Copy the compressed distribution image to the computer that you will use to run the installation. Extract the contents of the compressed file into an empty directory. If you are installing the software from a DVD, copy the contents of the DVD to an empty directory. 2. Verify the contents of the extracted distribution image. The Pega-image\checksum directory provides an MD5 checksum for each the file in the distribution image. To verify that the files downloaded and uncompressed correctly, calculate a checksum using the Jacksum tool at For example, if you uncompressed the distribution image to Pega-image, enter the following command: java -jar jacksum.jar -m -a md5 -r -p -O outputfile.md5 Pega-image Compare outputfile.md5 to the md5 file located in Pega-image\.checksum. The checksum values should be identical. 3. Choose the installation method: IUA or command line.

24 Installing the Pega Platform Running the Installation and Upgrade Assistant (IUA) Because of the large volume of data, run the IUA on the same network as the database server. If this is not possible, run the tool on a system with fast, direct access to the database server. The Deployment user performs these steps. Note: The Pega Platform writes command-line output to a file in the Pega-image\scripts\logs directory. The installation can last for several hours and the time can vary widely based on network proximity to the database server. To run the IUA: 1. Double-click the PRPC_Setup.jar file to start the IUA. Note: If JAR files are not associated with Java commands on your system, start the IUA from the command line. Navigate to the directory containing the PRPC_Setup.jar file, and type java -jar PRPC_Setup.jar. The IUA loads and the Pega icon is displayed in your task bar. 2. Click Next to display the license agreement. 3. Review the license agreement and click Accept. 4. On the Installer Mode screen, choose Installation and click Next. 5. Choose your database type and click Next. 6. Choose Standard Edition and click Next. 7. Configure the database connection. The JDBC drivers allow the Pega Platform application to communicate with the database. Pega Platform Installation Guide 24

25 Installing the Pega Platform Note: Some of the fields on the Database Connection screen are pre-populated based on the type of database you selected. If you edit these or any other fields on this screen, and then later decide to change the database type, the IUA might not populate the fields correctly. If this occurs, enter the correct field values as documented below, or exit and rerun the IUA to select the intended database type. JDBC Driver Class Name Verify that the pre-populated value is accurate: com.ibm.db2.jcc.db2driver JDBC Driver JAR Files Click Select Jar to browse to the appropriate driver files for your database type and version. For a list of supported drivers, see the Pega Platform Support Guide. IBM DB2 for z/os requires two JDBC JAR files to establish a connection: db2jcc4.jar and db2jcc_license_cisuz.jar. Site Dependent Properties File Enter the full path of the site-dependent properties file Pega Platform Installation Guide 25

26 Installing the Pega Platform or click Select File to browse and select the file. Database JDBC URL Verify that the pre-populated value is accurate. For information about URLs, see Obtaining database connection information. Replace items in italics with the values for your system: jdbc:db2:// server:50000/database:fullymaterializelobdata=true;fullymaterializeinputstreams=true; progressivestreaming=2; usejdbc4columnnameandlabelsemantics=2; Database Username and Password Enter the user name and password that you created for the Deployment user on your database. Rules Schema Name Enter the name of the rules schema in the database. Data Schema Name Enter the name of the data schema in the database. For singleschema configurations the data schema name is identical to the rules schema name. 8. Click Test Connection. If the connection is not successful, review your connection information, correct any errors, and retest. When the connection is successful, click Next. Note: On IBM DB2 for Linux, UNIX, and Windows, and IBM DB2 for z/os, Test Connection does not verify that the schemas exist. Instead, the schemas are automatically generated when the first CREATE TABLE statement executes after the installation is complete. 9. Optional: Specify whether you will have your database administrator manually apply the DDL changes to the schema. These changes include the user-defined functions (UDF) supplied by Pegasystems. By default, the IUA generates and applies the schema changes to your database. To generate and apply the DDL outside the IUA, select Bypass Automatic DDL Application and continue the deployment. After you complete the installation, manually generate and apply the DDL and UDF. For more information, see Optional: Generating and applying DDL and Appendix D Installing user-defined functions on page 72. To have the Installation and Upgrade Assistant automatically apply the DDL changes and the UDF, clear Bypass Automatic DDL Application. 10. Optional. Specify whether to install in secured mode. Deploying the Pega 7 Platform in secured mode requires an administrator to enable new out-of-the-box operators. The administrator and Pega Platform Installation Guide 26

27 Installing the Pega Platform new out-of-the-box operators must change their passwords when they first log in. For more information, see Appendix E Secured mode on page 74. Verify that Secure installed User IDs is checked and click Next. 11. Enter the system name and production level and click Next: System Name Enter a name for your Pega Platform system. To find the system name, navigate to System > Settings > System Name. Production Level Enter a production level. The production level affects many security features of your system. Both the system name and production level can be changed after the system is running. Depending on the type of installation, choose: 5 for a system that will be used in production 4 for a preproduction system 3 for a test system 2 for a development system 1 for an experimental system The production level can be updated from the App Explorer. Enter Data-Admin-System in the search field and select SysAdmin > Class > Data-Admin-System to open your system. 12. Click Start to begin loading the rulebase. Installation logs display in the log window and are also stored in the Pega-image\scripts\logs directory. During the installation, the log window might appear inactive when the IUA is processing larger files. 13. Click Back to return to the previous screen, and then click Exit to close the IUA. Editing the setupdatabase.properties file Skip this section if your installation meets all of the following criteria: Pega Platform Installation Guide 27

28 Installing the Pega Platform You will use the Installation and Upgrade Assistant to install. You will allow the installation to automatically apply the schema changes and do not need to create a DDL file. You will not enable Kerberos authentication. If your installation does not meet all of these criteria, follow the steps in this section to edit the setupdatabase.properties file to configure scripts to do any or all of the following tasks: Install the Pega Platform. Use the install.bat or install.sh script. Enable Kerberos authentication. Use the install.bat or install.sh script. Generate a DDL file of schema changes. Use the generateddl.bat or generateddl.sh script. You can use the generateddl.bat or generateddl.sh script regardless of whether you use the IUA or the command-line script to install. Generate user-defined functions. Use the generateudf.bat or generateudf.sh script. Migrate schemas. Use the migrate.bat or migrate.sh script. To edit the setupdatabase.properties file: 1. Open the setupdatabase.properties file in the scripts directory of your distribution image: Pega-image\scripts\setupDatabase.properties 2. Specify the properties for your system. For each property, add the appropriate value after the equal sign. See Database connection properties. 3. Save and close the file. Database connection properties These properties specify the settings needed to connect to the database: The script arguments column lists the arguments for the command-line scripts. The Property column lists the corresponding property in the setupdatabase.properties file. Pega Platform Installation Guide 28

29 Installing the Pega Platform Script argument Property Description --driverjar pega.jdbc.driver.jar Path and file name of the following JAR files: db2jcc4.jar and db2jcc_license_cisuz.jar --driverclass pega.jdbc.driver.class Class of the JDBC driver --dbtype pega.database.type Database vendor type. Enter: db2zos --dburl pega.jdbc.url The database JDBC URL. For more information, see Obtaining database connection information. --dbuser pega.jdbc.username User name of the Deployment user. --dbpassword pega.jdbc.password Password of the Deployment user. For encrypted passwords, leave this blank. no script argument available pega.platform.userids.issecure Specifies whether the Pega Platform is installed in secured mode. The default is true. For more information, see Appendix E Secured mode on page 74. Set to true to install in secured mode. Deploying the Pega 7 Platform in secured mode requires an administrator to enable new out-of-the-box operators. The administrator and new out-of-the-box operators must change their passwords when they first log in Set to false to disable secured mode. If you disable secured mode, unauthorized users might use the default passwords to gain administrator access to your system. --dbschema rules.schema.name In a single schema environment, sets rules schema and data schema. In a split-schema configuration, sets the rules schema only. --dbdataschema data.schema.name For split-schema configurations only, sets the data schema name. --tempdir user.temp.dir Optional: The location of the temp directory. Set this location to any accessible location. --mtsystem multitenant.system Specifies whether this a multitenant system. IBM DB2 for z/os does not support multitenant systems. pega.zos.properties z/os site specific properties file. The full path and file name to the pega.zos.properties file. --connproperties jdbc.custom.connection.properties Optional: Semicolon-delimited list of custom JDBC properties. (for example: prop1=value;prop2=value;prop3=value) Optional: Enabling Kerberos authentication Kerberos is a computer network authentication protocol that allows nodes communicating over a non-secure network to prove their identity to one another in a secure manner. Pega Platform Installation Guide 29

30 Installing the Pega Platform To enable Kerberos for authentication, you must use the command line to install the Pega Platform: 1. Edit the setupdatabase.properties file. a. Open the setupdatabase.properties file in the scripts directory of your distribution image: Pega-image\scripts\setupDatabase.properties b. In the Uncomment this property section of the file, uncomment the custom property: jdbc.custom.connection.properties c. Provide the correct parameters as semicolon-delimited name/value pairs. The specific parameters depend on your security infrastructure, for example: jdbc.custom.connection.properties= parameter1=value1;parameter2=value2;parameter3=value3; jdbc.custom.connection.properties=integratedsecurity=true; d. Comment out all the user name and password properties so that they appear as follows: # pega.jdbc.username db username # pega.jdbc.password db password [lines removed here] # pega.jdbc.username=admin # pega.jdbc.password=admin e. Save and close the file. 2. Configure your database to enable Kerberos functionality. This might include additional vendorspecific JDBC driver configuration, or other setup procedures. See the IBM DB2 for z/os documentation for details. 3. Continue at Installing from the command line. Installing from the command line Because of the large volume of data, run the command-line script on the same network as the database server. If this is not possible, run the script on a system with fast, direct access to the database server. To use the install.bat or install.sh script, first configure the setupdatabase.properties file. Note: If no additional arguments are passed to the script, the script defaults to the values of the properties set in the setupdatabase.properties file. See Editing the setupdatabase.properties file. Pega Platform Installation Guide 30

31 Installing the Pega Platform 1. If you have not done so already, edit the setupdatabase.properties file. a. Open the setupdatabase.properties file in the scripts directory of your distribution image: Pega-image\scripts\setupDatabase.properties b. Configure the connection properties. For more information about parameter values, see Properties file parameters. # Connection Information pega.jdbc.driver.jar=/path-to-the-database-jar-file/driver.jar pega.jdbc.driver.class=database driver class pega.database.type=database vendor type pega.jdbc.url=url of the database pega.jdbc.username=deployment username pega.jdbc.password=password rules.schema.name=rules-schema-name data.schema.name=data-schema-name c. Save and close the file. 2. Open a command prompt and navigate to the scripts directory. 3. Type install.bat or./install.sh to run the script. Installing the rulebase can take several hours, depending on the proximity of the database to the system running the installation script. When the installation is complete, you see a BUILD SUCCESSFUL message. Note: The Pega Platform writes command-line output to a file in the Pega-image\scripts\logs directory. Using JCL Skip this section if you plan to use the Installation and Upgrade Assistant or the command line scripts to install. The Pega Platform includes JCL scripts to setup the z/os environment to run the shell scripts and java programs packaged with the Pega Platform. The JCL scripts use IBM batch z/os launchers to run UNIX System Services in z/os and JZOS (Java on z/os). The JCL scripts are in the library PEGA.DB2.JCLLIB: Pega-image/scripts/config/db2zos/libraries/PEGA.DB2.JCLLIB The library includes the following members: Pega Platform Installation Guide 31

32 Installing the Pega Platform SETUPZOS - This member includes: Shell script set statements to establish the fully-qualified directory paths for the Java 64 Bit System JDBC Jar members IBM s JZOS system JDBC connection properties Path to the Pega Platform distribution image SITEDIRS Contains the JCL set statements used to establish the fully qualified zfs working directory, the fully qualified zfs directory to the Pega root directory and the MVS fully qualified library name of the Pega Platform JCL library that contains these members. PU01EXP This job expands the Pega Platform distribution image into the zfs directory specified by the SITEDIRS script. PI01DDL This job creates the SQL DDL statements required to install the database objects. PI01ENV This is the environment script for the job PI01DDL. Do not modify this script. PI02SQL This job applies the SQL DLL statements generated by PI01DDL creating the necessary tables, triggers, views, indexes and stored procedures required to install the Pega Platform system. PI02ENV This is the environment script for the job PI02SQL. Do not modify this script. JCL Procedure The JCL procedure uses a combination of both MVS libraries and zfs members. To follow this procedure, you need a user id with OMVS access, and 5 GB of available storage. 1. If you have not already done so, update the DB2SiteDependent.properties file in the directory Pega-image/scripts/config/db2zos. Add these values: #WLMUDF The dedicated Java-enabled Work Load Manager (WLM) database user name The name of the user with z/os credentials. Enter this value in all capital letters, or the installation fails. database password Pega Platform Installation Guide 32

33 Installing the Pega Platform 2. Upload the Pega 7.3 distribution image to the z/os server. 3. Sign into the z/os server from an OMVS terminal. 4. Use either USS services or the ISPF panel to expand the distribution image. 5. Make your current directory the directory that contains the distribution image and run PU01EXP. 6. Allocate an MVS library to hold the library members: Pega-image/scripts/config/db2zos/libraries/PEGA.DB2.JCLLIB Note: Name the library PEGA.DB2.JCLLIB with the DCB attributes of FB/80/4000. Then, use ISPF 3.3 to copy the file into the library as members. If you use another library name, change the library name in each member to the new name. 7. Using the ISPF editor, review and edit the members SETUPZOS and SITEDIRS one at a time, updating the file paths. The instructions for editing these members are included in the comments. Remember to save the member each time before you submit the change. Note: SETUPZOS contains DSN statements for the JCL. SITEDIRS contains pointers to members that the shell scripts require. These are provided as a common place to set these values. 8. Using the ISPF editor, review and edit the members PI01DDL and PI02SQL one at a time, updating the comments by the JCL. Remember to save the member each time before you submit the change. 9. Run PI01DDL. Note: This member generates the database DDL statements that create the database. Review the output for accuracy. 10. Run PI02SQL to apply the DDL. Note: The Pega Platform writes command-line output to a file in the Pega-image\scripts\logs directory. Pega Platform Installation Guide 33

34 Setting up the application server This section describes how to configure your IBM WebSphere application server: Ensure that your application server meets the prerequisites. Configure the application server. Deploy the Pega Platform applications. Preparing to configure the application server Complete these steps before you configure the application server: 1. Ensure that your operating system references a common time standard such as the one available at On UNIX, this is the Network Time Protocol daemon, ntpd. On Windows, you can set a similar service through the clock settings in the Windows Control Panel or task bar. See the documentation for your specific hardware operating system for information about setting this critical service. 2. Ensure that the following ports are open and available: Search One TCP port in the range (the default is 9300). This port is used for internal node-to-node communication only, and should not be externally accessible. Cluster communication Leave open the port range By default, the system begins with port 5701, and then looks for the next port in the sequence (5702, followed by 5703 and so on). To override the default port range, set a different value for the initialization/cluster/ports setting in the prconfig.xml file. If you switch to Apache Ignite client-server clustering topology, you must additionally open ports in the range of for Apache Ignite stand-alone servers communication.