Pega Co-Browse Installation Guide 7.4
2018 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 02142-1209 USA Phone: 617-374-9600 Fax: 617-374-9620 www.pega.com Document: ii
Software version: 7.4 Feedback If you have suggestions or comments for how we can improve our materials, send an email to AppDocBug@pega.com. iii
Contents Prerequisites...5 Hardware requirements...5 Software requirements...5 Application requirements...5 Parameters to install Pega Co-Browse... 7 Installing Co-Browse... 10 Installing and starting the server... 10 Installing and starting the log server...10 Registering the company...10 Optional: Deploying content on a content delivery network... 11 Testing the installation...12
Prerequisites Prerequisites Ensure that your environment meets the following specifications before you start the. Hardware requirements Software requirements Application requirements Hardware requirements The Node.js application server requires the following resources: 10 GB disk 5 GB RAM 2.5 GHz dual core CPU The PostgreSQL database requires the following resources: 200 GB disk 10 GB RAM 2.5 GHz Dual Core CPU The Redis server requires the following resources: 30 GB disk 10 GB RAM 2.5 GHz Dual Core CPU Software requirements Install the following software before you install. You can download them from their respective websites. Linux-based operating system based on Kernel version 3.16.0-31-generic or Red Hat Enterprise Linux version 3.10.0-327.36.3 el7.x86_64 Node.js v8.9 application server Note: Any version of the Node Package Manager that comes along with the Node.js application server is supported. Redis v3.2 server PostgreSQL v9.5 database Application requirements 1. Install and start the PostgreSQL database that is used for hosting the Pega Co-Browse data. 2. Create the user credentials that are needed to access the PostgreSQL database as per your business requirements. 5
3. Set the database schema name to cobrowse_schema. 4. Run the postgre.sql and postgre_recording_schema.sql scripts for the PostgreSQL database. 5. Start the Redis server for fast data retrieval from cache memory. Note: If you are upgrading from the Pega Co-Browse version 7.31 to the latest version, then run the v7.31-v7.41.sql command.
Parameters to install Pega Co-Browse Parameters to install Pega Co-Browse By using Pega Co-Browse, a customer service representative can connect to customers' browsers and show them sections of the website by highlighting different elements of the web page. The customer service representative can also click links or fill out forms remotely without additional plug-ins or software. To use Pega Co-Browse, configure the environment key values. The environment key values are stored in the config.json file that is provided on the installation media. For more information on Pega Co-Browse, see the Pega Co-Browse Implementation Guide on the Pega Customer Service product page. Configuring the environment key values The top-level objects in the config.json file correspond to your environment in which the Co-Browse server is deployed. Configure these settings so that you can use the Pega Co-Browse application in your environment, for example, set the server_port object to indicate the Co-Browse server port. 1. Open the config.json file. 2. Modify the configuration key value for each environment object as described in the following table. 3. Save the file. Configuration key Configuration value description Required Example value server_port The port number on which the Co- Browse server listens. 80 redis redis.master redis.master.host redis.master.port This object holds the Redis server configuration details. It contains the master and slave child keys. This object holds the configuration details for the Redis master. It contains the host, port, slave, and password child keys. The host address that is accessible over the network. This can be the IP address of the machine or the domain name in which Redis is running or the machine name. The port number on which Redis is running. redis.master.password The Redis password. It must be the password that you specified at the time of redis requirepass configuration. redis.slave database This object holds the configuration for the Redis slave. The configuration values are the same as those for the Redis Master. Delete this object if you use a single Redis server. This object contains the host, port, and password child. No (Defaults to 6379) 6379 No No The database server configuration values used for the Pega Co-Browse database. This object contains the host, port, db, user, and password child keys. 10.123.233.0 Enter the mypassword. Enter the 7
Parameters to install Pega Co-Browse Configuration key Configuration value description Required Example value database.name database.host database.port database.db database.user database.password enable_ssl_server ssl_server_config ssl_server_config. ssl_certificate_path This is the configuration from where you configure a database. The host address that is accessible over a network. This can be the IP address of the machine or the domain on which the database is running. The port number on which the database is running. The database that stores the Pega Co-Browse. The user name to log in to the database server. The password of the user to log in to the database server. postgres. Enter the value in quotation marks. 10.124.200.0, www.example.com No 5432 The SSL server to run the Co-Browse No (Defaults to false) server. This should run as a HTTPS server, not as a HTTP server. This object holds the path to the SSL server access credentials that are needed to start a Co-Browse HTTPS server. It contains the ssl_certificate_path, ssl_key_path, ssk_key_passphrase, and ca_certificate_path child keys. No, if enable_ssl_server is set to true. Co-Browse. Enter the value in quotation marks. admin. Enter the value in quotation marks. dbpassword. Enter the true or false The path to the SSL certificate file.../ssl/host.com.crt. Enter the ; ; ; ; ssl_server_config. ssl_key_path ssl_server_config. ssl_key_passphrase ssl_server_config. ca_certificate_path host_urls The path to the SSL key file.../ssl/host.key. Enter the The path to the SSL key passphrase. The path to the certification authority certificate file. This object holds the URLs that are used by the browser client for establishing co-browse sessions and logging. This object contains the server_host_url, asset_host_url, and log_server_url child keys. host_urls.server_host_url The public URL of the server. When you use a load balancer, this URL must be the load balancer URL that route requests to the Co-Browse server. host_urls.asset_host_urlthe public URL from where the presenter's static content is retrieved from a content delivery network. For more information on deploying content on a content delivery network, see Optional: Deploying content on a content delivery network. No (defaults to server_host_url)../ssl/passphrase. Enter the../ssl/bundle.crt. Enter the https:// pega.cobrowse.com:8080. Enter the value in quotation marks. https://cdn.host.com. Enter the value in quotation marks. host_urls.log_server_urlthe public URL of the log server. http:// log.pega.cobrowse.com:8080 8
Parameters to install Pega Co-Browse Configuration key Configuration value description Required Example value cobrowse_file_path The public URL of the presenter's file, when the file is deployed and retrieved from a content delivery network. When the file is not deployed on a content delivery network and is served from the Co-Browse server, the path is <host_urls.server_host_url>/scripts/ final/customer.js. https:// example.s3.amazonaws.com/ scripts/final/customer.js mail_server_config This object holds configuration details of the mail server. It contains the service, host, and from_address child keys. mail_server_config.service This is the mail server protocol. Pega Co-Browse supports only SMTP. SMTP. Enter the value in quotation marks. mail_server_config.hostthe host name of the mail server. mailhost.org. Enter the mail_server_config. from_address admin_credentials The from address in mails. team@mailservice.com. Enter the value in quotation marks. HTTP Basic Auth credentials to be used for accessing the Administration area of the Co- Browse Server. This object holds the user and password child keys. admin_credentials.userthe HTTP Basic Auth administrator user credentials that are used for accessing the Administration area of the Co-Browse Server. Username. Enter the value in quotation marks. admin_credentials. password The HTTP Basic Auth administrator password that are used for accessing the Administration area of the Co-Browse Server. Password. Enter the value in quotation marks. logger_settings This enables logs for the Co-Browse No server. It contains the level child key. logger_settings.level This enables the log level. No 10 (trace), 20 (debug), 30 (info), 40 (warn), 50 (error), and 60 (fatal) 9
Installing Co-Browse Installing Co-Browse To have customer service representatives interact with customers, install the application. The installation includes the following tasks: Installing and starting the server Installing and starting the log server Registering the company Optional: Deploying content on a content delivery network Installing and starting the server is a screen-sharing application using which, a remote viewer can connect to a presenter s browser and show a website by highlighting different elements of the web page. The viewer can click links or fill forms remotely without downloading or installing any software. To use the application, you must install and start the Co-Browse server. 1. Copy and extract the.tar archive from your installation media to your Linux workstation where you want to install the application. 2. Navigate to the directory that you created by extracting the.tar archive, and open the server directory. 3. Install the node modules with the following command: npm install --production 4. Modify the server configuration values for your environment in the config.json file. For more information about the config.json file, see Determine the parameters to install Co-Browse. 5. To start the Co-Browse server, run the node_env=production node app command. Installing and starting the log server A log server is a central repository that stores the logs of the connected network devices such as hosts and routers. After installing the log server, you can view, filter, and archive the logs. If you installed the Co-Browse server earlier, then ignore step 1. 1. Copy and extract the.tar archive from your installation media to your Linux workstation where you want to install the application. 2. Navigate to the logserver directory and install the node modules with the following command: npm install --production 3. To start the log server, run the PORT=< my port > node logserver command. Replace the my port value with the port number on which you want to start the log server. If no value is entered for the workstation port, then the default port 8002 is used. Registering the company Register your company to receive the token that identifies the company and enables the application for your customer service representatives. 10
Installing Co-Browse 1. Enter the following URL in your browser: <server_host_url>/checkout/pega. Replace <server_host_url> with the value of the host_urls.server_host_url parameter that you specified in the config.json file. For more information about the config.json file, see Determine the parameters to install Co-Browse. 2. On the registration page, enter your login credentials that you specified for the admin_credentials parameter in the config.json file. 3. To register and create an administrator account so that you can access the application, enter an email address and your company name, and then click Register. The server sends an email to the address that you specified with a link that you can click to complete the registration process. 4. Open your email, and click the link that you received. 5. Enter the required fields on the registration page, and then click Sign Up. The application login page is displayed. 6. Enter your access credentials to log in to the application. Optional: Deploying content on a content delivery network You can deploy and retrieve static content such as images, scripts, and stylesheets from a content delivery network. A content delivery network is a distributed network of data servers that stores the static content. It increases the speed with which the content is delivered to the users. Specify the path of each file located in /deploy/assets directory in your installation package on your content delivery network. For example, if the content delivery network host is https://example.com, then set the default.css file in your installation package at /cobrowsing/assets/stylesheets/customer/final/default.css as https://example.com/stylesheets/customer/final/default.css 11
Testing the installation Complete the following steps to verify that the installation process has completed successfully. 1. Log in to the application by entering the credentials that you specified while registering the company. For more information see, Registering the company. 2. Click the Install tab, and then copy the JavaScript code except the script tags. 3. Open a web page where you want to enable the application. 4. Use your browser console to insert the JavaScript in to the web page that you want to co-browse. 5. Click SUPPORT. The co-browse session code is displayed as your customer would see. 6. Copy the Co-Browse session code, and keep the browser window open. 7. In the application, click the Co-Browse tab. 8. In the Start a co-browsing session field, enter the copied code, and then click Start Co-Browse. You see the web page that you want to co-browse. For more information on the application, see the Pega Co-Browse Implementation Guide.