Installation Guide Version 5.0
2015 Pitney Bowes Software Inc. All rights reserved. This document may contain confidential and proprietary information belonging to Pitney Bowes Inc. and/or its subsidiaries and associated companies. Portrait Software, the Portrait Software logo, Portrait, and Portrait Software s Portrait brand are the trademarks of Portrait Software International Limited and may not be used or exploited in any way without the prior express written authorization of Portrait Software International Limited. Acknowledgement of trademarks Other product names, company names, marks, logos and symbols referenced herein may be the trademarks or registered trademarks of their registered owners. Portrait Software Support If you need help with something that s not covered by this documentation, try the Knowledge Base on our web site. http://support.portraitsoftware.com and follow the links to your product. You can also download other Portrait Software documentation from the site. If you don t have a username and password or you ve forgotten them please contact us through one of the channels below. If you find a problem with the use, installation, or documentation of this product, please contact us using any of the following methods: Email:software.support@pb.com Phone USA/Canada 1-800-335-3860 (toll-free) Rest of world +44 800 840 0001 When you report a problem, it helps if you can tell us: The name of the software application The circumstances in which the problem arose What error messages you saw (if any); The version of the software that you were using. Pitney Bowes Software Inc. February 04, 2015
Contents Chapter 1: Introduction...5 Purpose...6 Intended audience...6 Related documentation...6 Chapter 2: Product overview...7 About Portrait Explorer...8 Architecture...9 Key components...9 Portrait Shared Server...9 Analytics Data Server (ADS)...10 Chapter 3: Installing Portrait Explorer...11 Installation overview...12 Installation prerequisites...12 Before you begin...13 Portrait suite compatibility...13 Installation procedures...14 Configuring your Windows servers...14 Installing Portrait Shared Server...15 Installing Analytics Data Server (ADS)...18 Enable Portrait Explorer...19 Chapter 4: Upgrading Portrait Explorer...21 Upgrading overview...22 Upgrade procedures...22 Upgrading Portrait Shared Server...22 Upgrading Analytics Data Server (ADS)...26
Chapter 5: Uninstalling Portrait Explorer...27 Uninstallation overview...28 Uninstallation procedures...28 Uninstalling Portrait Shared Server...28 Preparing to uninstall ADS...28 Uninstalling Analytics Data Server (ADS)...29 Appendix...31 Advanced installation...32 Install scripts...32 Advanced uninstallation...43 Uninstall scripts...43 Portrait Shared Server silent install scripts...46 InstallPortraitHQ.ps1...46 ConfigurePortraitHQ.ps1...46 Additional settings and defaults...50 Portrait HQ datasheet...53 Explorer Acknowledgments...54 4 Portrait Explorer 5.0
Introduction 1 In this section: Purpose.........................................6 Intended audience................................6 Related documentation............................6
Purpose Purpose This document describes how to install Portrait Explorer. Intended audience This guide is provided for system administrators and data analysts who need to install and integrate Portrait Explorer with existing systems. Related documentation Document Portrait Suite Installation Guide (for multi-product installations) Portrait Explorer Administration Guide Media (ZIP/DVD) and location Portrait Explorer media in: \Documentation\<language_code>\suite_installation\ Portrait Explorer media in: \Documentation\<language_code>\ Note: These documents and others can be downloaded from the Pitney Bowes Software website: http://www.pbinsight.com/support/product-documentation/p/ 6 Portrait Explorer 5.0
Product overview 2 In this section: About Portrait Explorer............................8 Architecture......................................9 Key components..................................9
About Portrait Explorer About Portrait Explorer Portrait Explorer is an easy-to-use, browser-based, customer data exploration tool. It allows business users to access their customer data quickly and easily without the need for advanced analytical or statistical help. Portrait Explorer allows for fast interactive visualization, selection and profiling of very large customer bases. It provides a unique blend of summary, aggregate and individual level information to aid customer insight, and guide you through making better decisions on targeting and treatment of a customer base. Portrait Explorer allows business users to: Search for customers or groups of customers across an enterprise. Drill down on individual customers to confirm their personal details and data. Use key selection criteria (e.g. age, sex, income) to expose customers and groups of customers for potential review or campaign actions. Segment customers via an ordered list of pre-defined selections and determine the impact of the selection priority in terms of which segment an individual customer is assigned to. Portrait Explorer provides tooling to allow data analysts to: prepare the data prepare views on the data monitor application performance 8 Portrait Explorer 5.0
Chapter 2: Product overview Architecture Key components Portrait Shared Server Portrait Shared Server consists of three key components: Portrait Shared Services (PSS). Provides the set of web services that allow Portrait Suite applications (Portrait Explorer, Miner, Dialogue and Interaction Optimizer) to communicate with each other. Portrait Shared Repository (PSR). Provides the Portrait Shared Repository and Portrait Data Warehouse databases. Portrait HQ. Provides a central dashboard for planning, launching and monitoring large scale (1 to 1) marketing campaigns. In addition to providing live (up-to-the-minute) summary views of your overall marketing position, Portrait HQ also provides real-time data enabling you to evaluate campaign progress and take immediate action if required. Databases Portrait Shared Repository: Installation Guide 9
Analytics Data Server (ADS) Portrait Explorer uses the Portrait Shared Repository SQL Server database to store selections and lists created in Explorer. This database also stores the definition of the common customer data logical model that allows selections created in Explorer to be shared with other Portrait systems. Analytics Data Server (ADS) The Analytics Data Server is the server-side component of Portrait Explorer, acting as the primary data source for all calculations and selections performed on the customer data. The server consists of two major components, the Analytics Data Server, a set of Web Services hosted in an Apache Tomcat Web Server instance; and the Analytics Data Server Repository, the data store used to hold both customer and system data. The Analytics Data Server provides command line tools for creating and modifying the customer data model. The data model is imported into the Portrait Shared Repository for use by Explorer and, in an integrated environment, will be merged with the data model definitions from Interaction Optimizer and Portrait Dialogue systems to create a logical data model. The merged logical data model allows users to define customer segments and utilize these definitions operationally in inbound and outbound marketing campaigns. The Analytics Data Server and Analytics Data Repository components can be installed on the same physical server as the Portrait Shared Services, although we generally recommend installation onto a separate server for performance reasons. ADS service The Analytics Data Server web services provide SOAP based web services to provide access to analytics query services, metadata query and management services and performance monitoring services. The services are hosted in an Apache Tomcat Application Server running as a Windows Service. Analytics Data Repository The Analytics Data Repository is an instance of a custom MonetDB database engine running as a Windows Service. The Analytics Data Repository is used to store both the customer data displayed to users in Explorer to view and select their customers and as a storage space for metadata definitions and caching of operational data for Explorer. In order to maximize system performance, it is recommended that the Analytics Data Repository and the ADS services are hosted on the same physical machine and not hosted on the same server as the PSR/PSS. 10 Portrait Explorer 5.0
Installing Portrait Explorer 3 In this section: Installation overview..............................12 Installation prerequisites..........................12 Before you begin.................................13 Portrait suite compatibility.........................13 Installation procedures...........................14
Installation overview Installation overview To install Portrait Explorer for the first time, complete the procedures listed below. If upgrading to a new version of Explorer see Upgrading overview on page 22. Installation procedure Configuring your servers Installing Portrait Shared Server on page 15 Configuring Portrait Shared Server Installing Analytics Data Server (ADS) on page 18 Configuring Analytics Data Server (ADS) on page 19 Time estimate 30 minutes 30 minutes 30 minutes 20 minutes 10 minutes Installation prerequisites The Portrait Explorer installation procedures assume that the following software has been installed. Server All servers Software Microsoft Windows Server Software level Portrait Explorer can be installed on any of the following: Standard and Datacenter Editions of Windows Server 2012 All servers Web server Microsoft.Net Framework IIS v4.5 on all servers, and v8.0 on Windows Server 2012 v8.5 on Windows Server 2012 R2 Database server Microsoft SQL Server 2012 SP1 and 2014, for Standard and Enterprise Editions and either case-sensitive or case-insensitive master databases. Note: The following features must be installed: Database Engine Services Management Tools - Basic Management Tools - Complete Client Tools Connectivity Analytics Data Server Java Runtime Environment v1.7 64-bit 12 Portrait Explorer 5.0
Chapter 3: Installing Portrait Explorer Client All clients Software Microsoft Silverlight Software level v5.0 Before you begin Before starting the installation, you need to: 1. Source all required software and associated documentation. Software + documentation Portrait Shared Server Analytics Data Server Portrait Explorer Installation Guide (this guide) Media location (ZIP file/dvd) Portrait Explorer media in: \Portrait Shared Server\ Portrait Explorer media in: \ADS\ Portrait Explorer media in: \Documentation\ 2. Collect all information required to configure the installation. The information required is listed in the installation datasheet in the Appendix. Installation considerations: When running the Portrait Shared Server installer, select the Custom Setup Type and install only the Database Administration and Portrait Shared Server features. (The other features are not required for Portrait Explorer.) It is recommended that you use the same account to run the HQ and PSS application pool as that used by the PSS to connect to the Portrait Shared Repository database. This account should be on a network domain, rather than a local machine. Portrait suite compatibility Portrait Explorer is compatible with the following Portrait Software. Software Portrait Foundation Portrait Miner Portrait Dialogue Interaction Optimizer Software level 5.0 Update 1 7.0B 6.1 5.6 Installation Guide 13
Installation procedures Note: The installation part of this guide takes you through installing Portrait Explorer as a standalone application. If you want to install or integrate Portrait Explorer with other Portrait Software applications, see the Portrait Suite Installation Guide. Installation procedures Configuring your Windows servers Configuring your application servers Windows Server 2012 Use the following procedure to configure your application server roles, role services and features. If you have multiple application servers, you need to repeat the procedures on all machines. 1. Log on to your Windows Server 2012 machine. 2. On the Windows 2012 Start screen, click Server Manager. 3. On the Server Manager Dashboard, click Manage from the top right menu to open the Add Roles and Features wizard. 4. Click Next and ensure Role-based or Feature-based installation is selected. 5. Click Next and select all servers you want to configure. 6. Click Next and ensure the role Application Server has been installed. If not, check the box. 7. Open the Application Server sub-section, and ensure the following services have been enabled. If not, check the relevant items. Web Server (IIS) Support TCP Port Sharing Windows Process Activation Service Support HTTP Activation Message Queuing Activation TCP Activation Named Pipes Activation COM+ Network Access 8. Click Next twice and then Install. If all items have already been set up, close the wizard. Configuring your web servers Windows Server 2012 Use the following procedure to configure your web server roles, role services and features. If you have multiple web servers, you need to repeat the procedures on all machines. 1. Log on to your Windows Server 2012 machine. 2. On the Windows 2012 Start screen, click Server Manager. 14 Portrait Explorer 5.0
Chapter 3: Installing Portrait Explorer 3. On the Server Manager Dashboard, click Manage from the top right menu to open the Add Roles and Features wizard. 4. Click Next and ensure Role-based or Feature-based installation is selected. 5. Click Next and select all servers you want to configure. 6. Click Next and ensure the role Web Server (IIS) has been installed. If not, check the box. 7. Open the Web Server (IIS) sub-section, and ensure the following services have been enabled. If not, check the relevant items. Management Tools IIS 6 Management Compatibility IIS 6 Metabase Compatibility IIS 6 WMI Compatibility IIS 6 Scripting Tools IIS 6 Management Console Windows Authentication ASP.NET 3.5 ASP.NET 4.5 8. Click Next and ensure the feature Message Queueing has been enabled. If not, add it. 9. Click Next and then Install. If all items have already been set up, close the wizard. Verifying the SQL agent service is running Use this procedure to verify the SQL agent service is running. 1. Log on to your SQL Server machine. 2. Click Start > All Programs > Microsoft SQL Server > SQL Server Management Studio. 3. Connect to the instance of the Database Engine as a database user (requires sysadmin role). In the Object Explorer window, right-click SQL Server Agent (Agent XPs disabled) and select Start. Verifying Names Pipes and TCP/IP protocols are enabled Use the following procedure to ensure that SQL Server is enabled to accept TCP/IP connections on port 1433. You can do this using SQL Server Configuration Manager. 1. On your SQL Server machine, open SQL Server Configuration Manager and, in the left pane, expand SQL Native Client Configuration and select Client Protocols. 2. In the right pane, check if Named Pipes and TCP/IP are enabled. If not, right-click them and select Enable. When the warning tells you to restart, click OK. Installing Portrait Shared Server Installing PSS features The Portrait Shared Server installer can install any of the following features: Portrait Shared Server. Provides the HQ web application and the Portrait Shared Services web services that integrate the Portrait product suite. Installation Guide 15
Installing Portrait Shared Server Database Administration. Enables administration of the databases used by Portrait Shared Server. Install this feature on the SQL Server database server. Data Warehouse Refresh. Provides the SQL Server Integration Services packages that populate the Portrait Data Warehouse. Install this feature on the Integration Services server. Reports. Provides SQL Server Reporting Services reports that report on campaign performance. Install this feature on the Reporting Services server. Tasks. Provides a SharePoint site that manages tasks created when working with campaigns. Install this feature on the SharePoint server. To install any of these features: 1. Log on to the server where Portrait Shared Server feature(s) are to be installed. 2. Open File Explorer and navigate to Portrait Shared Server on the release media (.iso). 3. Right-click setup.exe and click Run as administrator. 4. Click Next on the Welcome page. 5. Accept the license terms and conditions and click Next. 6. Accept the default destination folder and click Next. 7. Choose the installation type and click Next. When installing the full set of Portrait Shared Server features, click Complete, otherwise click Custom. 8. On the Custom Setup screen (shown if a custom installation type was selected in the previous step), select This feature will be installed on local hard drive for the features you wish to install. Select This feature will be not be available for features you do not wish to install. Click Next. 9. Click Install on the Ready to Install the Program dialog. 10. On the InstallShield Wizard Completed screen, click Finish. Creating the PSS databases The PSS has a dependency on the Portrait Shared Repository and Portrait Data Warehouse databases that must be created following the install. These databases are created using the steps shown below: 1. Run the Windows PowerShell application as Administrator and navigate to the PowerShell scripts directory of the installation. By default this is found at: C:\Program Files (x86)\pst\portrait Shared Server\Administration\ 2. Run the PowerShell script CreatePortraitDatabases.ps1 The script takes the following parameters: -DWDatabaseName The name given to the Portrait Data Warehouse database [defaults to PortraitDW] -PSRDatabaseName The name given to the Portrait Shared Repository database [defaults to PortraitPSR] -DBAccessUsername The name of the user account that will be used to access the databases by the web applications (this should generally be the same Windows account as the Application Pool user used in the SetupWebsites script). This login must already exist in the SQL Server database 16 Portrait Explorer 5.0
Chapter 3: Installing Portrait Explorer -IntegratedSecurity Flag used to indicate whether the user running the script is the user account used to connect to the database server or not. If set to TRUE, the user account used to run the PowerShell script must have rights to create databases on the target SQL Server -DBUsername The name of the SQL Server account to connect to the database server and create the databases (only required if IntegratedSercurity is FALSE) -DBPassword The password for the SQL Server account to connect to the database server and create the databases (only required if IntegratedSercurity is FALSE) -DBServerName The name of the SQL Server on which the databases are to be created -Sourceroot The path to the database creation scripts (only required if not installed to the default location) Example: >CreatePortraitDatabases.ps1 -DBAccessUsername MyDomain\AppPoolUser -DBServerName MYSERVER\MSSQLSERVER 3. Confirm the databases have been created by connecting to the target database server using SQL Server Management Studio and confirm the databases are present and the specified user account is a valid user of the new databases Creating the PSS web sites The Portrait Shared Server comprises of two web applications. Both of these application containers must be created before the Portrait HQ can be accessed. A PowerShell script is provided to allow the web applications to be created and the application pool for the new web applications created and assigned. 1. Log onto the application server with an account that has permission to create databases on the target SQL server database server. 2. Run the Windows PowerShell application as Administrator and navigate to the PowerShell scripts directory of the installation. By default this is found at: C:\Program Files (x86)\pst\portrait Shared Server\Administration\ 3. Run the PowerShell script SetupWebsites.ps1 The script takes the following parameters: -PSSWebAppPoolAccountDomain The Windows Active Directory domain for the IIS application pool user account -PSSWebAppPoolAccountName The username for the application pool identity -PSSWebAppPoolAccountPassword The password for the application pool identity Installation Guide 17
Installing Analytics Data Server (ADS) -IISWebsite The IIS website to which web applications will be installed [defaults to Default Web Site] -HQWebApplicationPhysicalPath The path for the HQ web application (only required when installed to a non-default location) [defaults to C:\Program Files (x86)\pst\portrait Shared Server\MarketingHQ] -PSSWebApplicationPhysicalPath The path for the PSS web application (only required when installed to a non-default location) [defaults to C:\Program Files (x86)\pst\portrait Shared Server\Portrait Shared Services] Example: >SetupWebsites.ps1 -PSSWebAppPoolAccountDomain MyDomain -PSSWebAppPoolAccountName AppPoolUser -PSSWebAppPoolAccountPassword password 4. Confirm the web applications have been installed successfully by starting up a web browser navigating to the URL of the PSS analytics web services URL. The default location from the application server is http://localhost/portraitsharedservices/analyticsservices.svc Installing Analytics Data Server (ADS) The Analytics Data Server installer is included in the installation media at:.\analytics Data Server Running the Analytics Data Server (ADS) installer The Analytics Data Server consists of two distinct components, both of which are installed (but not configured) by the installer setup.exe file located in the installation media. The Analytics Data Server is an Apache Tomcat web server that hosts the web services used by Explorer. The Analytics Data Repository is the database engine component that is used to store and query the customer data that is displayed in Explorer. Neither of the two services will be ready for use before the configuration step has been run. 1. Run the setup.exe in the \Analytics Data Server directory on your installation media (.iso). Ensure you right-click the setup.exe and select Run as Administrator. 2. Select the display language for your installation 3. If not present, InstallShield will identify missing pre-requisite software and will attempt to install them. Press the Install button to continue with the installation of the required components. 4. Click Next on the Welcome dialog. 5. Accept the license agreement and click Next. 6. Choose the install location (the default is C:\Program Files\PST\Analytics Data Server\) and click Next. 7. Under the Ready to Install the Program, click on Install. During the installation the Installing Analytics Data Server page shows a progress indicator. 8. On the final page, click Finish to exit the wizard. 18 Portrait Explorer 5.0
Chapter 3: Installing Portrait Explorer Configuring Analytics Data Server (ADS) In order to create the two new Windows services that form the Analytics Data Server, the services need to be configured. The configuration is performed using PowerShell scripts that are installed by the InstallShield installer. A single Setup script is supplied that allows the user to configure the most common parameters for the services. Additional scripts are available for more advanced configuration tasks. The advanced configuration scripts are detailed in the Appendices of this document. 1. Launch the PowerShell command prompt window (running the process as Administrator). 2. Navigate to the PowerShell Scripts directory of the Analytics Data Server installation (typically C:\Program Files\PST\Analytics Data Server\PowerShell Scripts) 3. At the command prompt run the Setup script (the following parameters are optional): -ADRPort The TCP port that the analytics Data Repository will listen on [default value is 50000] -DBFarmPath The file location on the server that the Analytics Data Repository will store it's data files [defaults to the C:\Program Files\PST\Analytics Data Server\MonetDB\dbfarm] -ADSPort The TCP port for accessing the web services [default value is 8080] Example: >Setup -ADRPort 40000 -DBFarmPath 'C:\Program Files\PST\Analytics Data Server\DBFarm\' -ADSPort 8888 See the Portrait Explorer Administration Guide for instructions on to describe the customer data you wish to explore (setting up metadata), plus how to load customer data into Explorer. Enable Portrait Explorer In order to enable the Explorer application within the HQ, the PSS must be configured to enable Explorer and the location of the ADS services must be specified. 1. Run the Windows PowerShell application as Administrator and navigate to the PowerShell scripts directory of the installation. By default this is found at: C:\Program Files (x86)\pst\portrait Shared Server\Administration\ 2. Run the PowerShell script ExplorerIntgration.ps1 The script takes the following parameters: -PSSUserAcountName The user name for connecting to Portrait Shared Services -PSSUserAcountPassword The password for the user account -ExplorerIntegrationEnabled Installation Guide 19
Enable Portrait Explorer Flag to indicate whether to enable or disable Explorer -ExplorerAnalyticsDataServerURL The Analytics Data Server web services URL Example: >ExplorerIntegration.ps1 -PSSUserAcountName MyDomain\ExplorerUser -PSSUserAcountPassword password -ExplorerIntegrationEnabled TRUE -ExplorerAnalyticsDataServerURL http://adsserver:8080/analytics-data-server 20 Portrait Explorer 5.0
Upgrading Portrait Explorer 4 In this section: Upgrading overview..............................22 Upgrade procedures..............................22
Upgrading overview Upgrading overview To upgrade Portrait Explorer, complete the procedures listed below. Upgrade procedure Upgrading Portrait Shared Server on page 22 Upgrading Analytics Data Server (ADS) on page 26 Time estimate 10 minutes 10 minutes Upgrade procedures Upgrading Portrait Shared Server The introduction of the Analytics Data Server in this release of Explorer affects: Reports. As the Excel reports generated from Explorer relied on the use of Datasets, all reports will now no longer be valid and will not be capable of being refreshed once the upgrade has been completed. Any report templates stored in the Portrait Shared Repository will need to be manually deleted once the upgrade has been completed. Card Visualizations. Customer card visualizations may no longer be valid due to the changes to allow Explorer to work with its own database. The cards may need to be re-created depending upon the nature of the card. Uninstalling Portrait HQ components Use the following procedure to uninstall your Portrait Shared Server (PSS) component. 1. Log on to your Portrait Shared Server machine. 2. Back up configuration files that you have modified since the original installation. The configuration files that you may have modified include: C:\Program Files (x86)\pst\portrait Shared Server\Marketing HQ\web.config C:\Program Files (x86)\pst\portrait Shared Server\Portrait Shared Services\web.config C:\Program Files (x86)\pst\portrait Shared Server\Portrait Shared Services\bin\config\Portrait.Mas.Cms.Services.Authorization.config C:\Program Files (x86)\pst\portrait Shared Server\Portrait Shared Services\bin\config\Portrait.Mas.Cms.Services.IO.config for version 5.5 C:\Program Files (x86)\pst\portrait Shared Server\SSIS\DWPopulate.dtsConfig 3. Click Start > Control Panel > Uninstall a program. 4. Select Portrait Shared Server and follow the wizard prompts to uninstall the Portrait Shared Server. 22 Portrait Explorer 5.0
Chapter 4: Upgrading Portrait Explorer Installing PSS features The Portrait Shared Server installer can install any of the following features: Portrait Shared Server. Provides the HQ web application and the Portrait Shared Services web services that integrate the Portrait product suite. Database Administration. Enables administration of the databases used by Portrait Shared Server. Install this feature on the SQL Server database server. Data Warehouse Refresh. Provides the SQL Server Integration Services packages that populate the Portrait Data Warehouse. Install this feature on the Integration Services server. Reports. Provides SQL Server Reporting Services reports that report on campaign performance. Install this feature on the Reporting Services server. Tasks. Provides a SharePoint site that manages tasks created when working with campaigns. Install this feature on the SharePoint server. To install any of these features: 1. Log on to the server where Portrait Shared Server feature(s) are to be installed. 2. Open File Explorer and navigate to Portrait Shared Server on the release media (.iso). 3. Right-click setup.exe and click Run as administrator. 4. Click Next on the Welcome page. 5. Accept the license terms and conditions and click Next. 6. Accept the default destination folder and click Next. 7. Choose the installation type and click Next. When installing the full set of Portrait Shared Server features, click Complete, otherwise click Custom. 8. On the Custom Setup screen (shown if a custom installation type was selected in the previous step), select This feature will be installed on local hard drive for the features you wish to install. Select This feature will be not be available for features you do not wish to install. Click Next. 9. Click Install on the Ready to Install the Program dialog. 10. On the InstallShield Wizard Completed screen, click Finish. Review Portrait Shared Server AppPool settings This release of the Portrait Shared Server implements session management within the dedicated Portrait Shared Server AppPool worker process. It is necessary to manage the way IIS recycles the AppPool worker process to ensure that user sessions do not encounter unexpected errors. It is recommended that AppPool recycling is configured to occur once a day during quiet periods e.g. at 1 a.m. to cause as little disruption as possible. To configure Portrait Shared Server AppPool recycling as recommended above: a) Open a Powershell prompt with elevated permissions and enter the following commands: b) Clear-ItemProperty ("IIS:\AppPools\Portrait Shared Server AppPool") -Name recycling.periodicrestart.schedule c) New-ItemProperty ("IIS:\AppPools\Portrait Shared Server AppPool") -Name recycling.periodicrestart.schedule -Value ( [TimeSpan]::FromHours(1)) d) Set-ItemProperty ("IIS:\AppPools\Portrait Shared Server AppPool") -Name recycling.periodicrestart.time -Value ( [TimeSpan]::FromHours(0)) Installation Guide 23
Upgrading Portrait Shared Server e) Set-ItemProperty ("IIS:\AppPools\Portrait Shared Server AppPool") -Name processmodel.idletimeout -Value ( [TimeSpan]::FromHours(24)) Review custom PSS settings It is necessary to identify which PSS settings have been changed in your environment, so that the same values can be re-applied to the upgraded installation. The table below summarizes all settings you may have changed. Config File Name Property Name Identifier in config file Default Value HQ Web.config UI Culture UICulture EN HQ Web.config Culture Culture EN HQ Web.config CampaignApprovalEnabled CampaignApprovalEnabled False HQ Web.config LogLevel LogLevel Verbose HQ Web.config ReportIntegrationEnabled ShowReportsLink False HQ Web.config ReportServerURL ReportsUri http://localhost/reportserver PSS Web.config AnalyticsIntegrationEnabled AnalyticsIntegrationEnabled False PSS Web.config AnalyticsDataServerURL Endpoint url section http://localhost:8080/analytics-data-server PSS Web.config DialogueIntegrationEnabled DialogueIntegrationEnabled False PSS Web.config DialogueServerURL Endpoint url section http://localhost/mhdialogserverapi PSS Web.config DialogueInstanceName PCM.InstanceName Default PSS Web.config IOIntegrationEnabled IOIntegrationEnabled False PSS Web.config IOServerURL Endpoint url section http:\\localhost PSS Web.config SharePointIntegrationEnabled SharePointIntegrationEnabled False PSS Web.config SharePointServerURL Endpoint url section None DWPopulate.dtsConfig DW_ConnectionString Provider=SQLNCLI11;Data Source=LOCALHOST;Integrated Security=SSPI;Initial Catalog=PortraitDW DWPopulate.dtsConfig InstallationDirectory. DWPopulate.dtsConfig IO_BatchCopySize 2000 DWPopulate.dtsConfig IO_ConnectionString Provider=SQLNCLI11;Data Source=localhost;Integrated Security=SSPI;Initial Catalog=PortraitIO DWPopulate.dtsConfig IO_MinSourceHistoryRows 2000 24 Portrait Explorer 5.0
Chapter 4: Upgrading Portrait Explorer Config File Name Property Name Identifier in config file Default Value DWPopulate.dtsConfig IO_Present 1 DWPopulate.dtsConfig PD_ConnectionString Provider=OraOLEDB.Oracle;Data Source=[data source];password=[password];user ID=[User id] DWPopulate.dtsConfig PD_SQL_ConnectionString Data Source=localhost;Initial Catalog=PDSystemReportSampleData1;Provider=SQLNCLI1 1;Integrated Security=SSPI; DWPopulate.dtsConfig PD_IsOracle 0 DWPopulate.dtsConfig PD_Present 0 DWPopulate.dtsConfig PDADO_ConnectionString Data Source=[Data source];persist Security Info=True;User ID=[User ID];Password=[password];Unicode=True DWPopulate.dtsConfig PSR_ConnectionString Provider=SQLNCLI11;Data Source=LOCALHOST;Integrated Security=SSPI;Initial Catalog=PortraitPSR DWPopulate.dtsConfig TransferOnly 0 Take note of any setting value that differs from the default. Configuring PSS features 1. Log on to the application server. 2. Run Portrait Powershell as an administrator. 3. Run command cd "C:\Program Files (x86)\pst\portrait Shared Server\Administration" 4. Run command CreatePortraitDatabases.ps1 with existing PSR and PDW database names to upgrade the databases. See CreatePortraitDatabases.ps1 on page 33 for a description of the arguments to this script. 5. Run command SetPSSDatabaseConnections.ps1. See SetPSSDatabaseConnections.ps1 on page 39 for a description of the arguments to this script. 6. Run command SetupWebsites.ps1. See SetupWebsites.ps1 on page 40 for a description of the arguments to this script. Reapply custom PSS settings To re-apply the Portrait Shared Server custom settings you identified in Review custom PSS settings on page 24: Installation Guide 25
Upgrading Analytics Data Server (ADS) 1. Go to C:\Program Files (x86)\pst\portrait Shared Server\Portrait Shared Services\bin\config and copy file Portrait.Mas.Cms.Services.Authorization.config.template and Portrait.Mas.Cms.Services.IO.config.template and paste at %PROGRAMDATA%\Pitney Bowes Software\Portrait Shared Services. Delete the.template extension of both files. 2. If you have custom settings for field segmentations, field exclusions, external field look-ups or secondary audiences (in Portrait.Mas.Cms.Services.IO.config), then this configuration needs to be applied to the file %PROGRAMDATA%\Pitney Bowes Software\Portrait Shared Services\Portrait.Mas.Cms.Services.IO.config. 3. If you have custom settings for elements Domain, DomainGroupRoleMappings, RolePermissions and OperationPermissions (in Portrait.Mas.Cms.Services.Authorization.config), then this configuration needs to be applied to the file %PROGRAMDATA%\Pitney Bowes Software\Portrait Shared Services\Portrait.Mas.Cms.Services.Authorization.config. 4. If you have any custom HQ settings for logging levels, Campaign Approval or display language, then run script AdminSettings.ps1 to apply your settings. See AdminSettings.ps1 on page 32 for a details on how to run this script. 5. If you have a custom ReportIntegrationEnabled setting, run script ReportIntegration.ps1 to apply your setting. See ReportIntegration.ps1 on page 38 for a details on how to run this script. 6. If you have custom configuration for the AnalyticsIntegrationEnabled setting, run script ExplorerIntegration.ps1 to apply your setting. See ExplorerIntegration.ps1 on page 35 for a details on how to run this script. 7. If you have custom configuration for the PDIntegrationEnabled setting, run script DialogueIntegration.ps1 to apply your setting. See DialogueIntegration.ps1 on page 34 for a details on how to run this script. 8. If you have custom configuration for the IOIntegrationEnabled setting, run script IOIntegration.ps1 to apply your setting. See IOIntegration.ps1 on page 37 for a details on how to run this script. 9. If you have custom configuration for the SharePointIntegrationEnabled setting, run script SharepointIntegration.ps1 to apply your setting. See SharepointIntegration.ps1 on page 41 for a details on how to run this script. Upgrading Analytics Data Server (ADS) As the Analytics Data Server is a new component in Explorer 5.0, there are no upgrade instructions for this component. It is recommended that as part of an upgrade of Explorer, that the existing PAWS component is uninstalled from the system. As the new ADS does not use PAWS datasets, any datasets that are to be kept should be copied from the PAWS repository before uninstalling. 1. Copy any required datasets from the PAWS repository (default location C:\Program Files (x86)\pst\paws\ext\paws\repository) 2. Open the Windows Control Panel 3. Navigate to the Programs section 4. Select Uninstall a program link 5. Right click on the Portrait Analytics Web Services entry in the list of installed programs and select Uninstall from the menu 6. Follow the procedures in Installing Portrait Explorer to install the Analytics Data Server. 26 Portrait Explorer 5.0
Uninstalling Portrait Explorer 5 In this section: Uninstallation overview...........................28 Uninstallation procedures.........................28
Uninstallation overview Uninstallation overview To uninstall Portrait Explorer, complete the procedures listed below. Uninstallation procedure Uninstalling Portrait Shared Server on page 28 Uninstalling Analytics Data Server (ADS) on page 29 Time estimate 10 minutes 10 minutes Uninstallation procedures Uninstalling Portrait Shared Server Removal of Portrait Shared Server will remove both the HQ and the Portrait Shared Services web applications from the web server, as well as the Portrait Shared Repositoryand Portrait Data Warehouse databases from the database server. Caution: Portrait Shared Server is a component that is shared by Portrait products. It should only be uninstalled when removing all Portrait products. To remove Portrait Shared Server: 1. Log on to the web server. 2. Run application Portrait Powershell as an administrator. 3. Run command RemoveWebsites.ps1. See RemoveWebsites.ps1 on page 44 for a description of the parameters to this script. 4. Run command RemoveDatabases.ps1. See RemovePortraitDatabases.ps1 on page 44 for a description of the parameters to this script. 5. Open the Programs and Features application. Right-click Portrait Shared Server in the list of installed programs and click Uninstall. Preparing to uninstall ADS Before uninstalling the Analytics Data Server component, the following steps should be followed. 1. Ensure that the Explorer instance that was using the ADS install has been disabled. This requires that the PSS configuration settings have been updated to ensure that Explorer has been removed and is no longer accessible. 2. Run the UninstallADSServices PowerShell script from the PowerShell Scripts directory of the Analytics Data Server installation. NOTE: This script should be run automatically by the uninstaller. 28 Portrait Explorer 5.0
Chapter 5: Uninstalling Portrait Explorer Uninstalling Analytics Data Server (ADS) It is recommended that the ADS is uninstalled using the Programs and Features control panel in Windows 1. In the Programs and Features control panel, click on the line containing Analytics Data Server to highlight the program. 2. In the toolbar above the list of programs and features, click on Uninstall to remove ADS. Installation Guide 29
Appendix In this section: Advanced installation.................................................32 Advanced uninstallation...............................................43 Portrait Shared Server silent install scripts................................46 Portrait HQ datasheet..................................................53 Explorer Acknowledgments............................................54
Advanced installation Install scripts AddEmptyUserSchemaIfNotExists.ps1 Script name Location Purpose Syntax AddEmptyUserSchemaIfNotExists.ps1 <InstallationFolder>\PST\Analytics Data Server\PowerShell Scripts Adds a schema "user" to the database (if it isn't there already) AddEmptyUserSchemaIfNotExists.ps1 [-SetAsSchemaForDefaultUser] where: -SetAsSchemaForDefaultUser is a flag to indicate that the new schema should be made the schema for the default user. cmdlets The AddEmptyUserSchemaIfNotExists.ps1 script makes use the following separate PowerShell cmdlet. If required, it can be run individually in place of the script: Add-EmptyUserSchemaIfNotExists Note: You can choose to run individual cmdlets in place of the script if that is more efficient. For more information on cmdlets, type Get-Help <cmdletname> in the Windows PowerShell console. AdminSettings.ps1 Script name Location Purpose AdminSettings.ps1 <PSS Installation Folder>\Administration To set the Portrait HQ display language, enable or disable HQ campaign approval, or manage HQ logging levels.
Syntax AdminSettings.ps1 [[-WindowsAuthentication] <String>] [-PSSUserAccountName] <String> [-PSSUserAccountPassword] <String> [[-UICulture] <String>] [[-Culture] <String>] [[-CampaignApprovalEnabled] <String>] [[-LogLevel] <String>] where: WindowsAuthentication specifies whether or not to use Windows authentication to log on to Portrait Shared Services. Set to true to use the current Windows user account to log on to Portrait Shared Services. PSSUserAccountName is the user name for connecting to Portrait Shared Services. Required only if WindowsAuthentication set to false. PSSUserAccountPassword is the password for connecting to Portrait Shared Services. Required only if WindowsAuthentication set to false. UICulture is the language code for the language to be used when displaying language strings in the HQ. Must be set to en. Culture is the language code for the language to be used by culture-dependent functions, such as date, number and currency formatting. Must be set to en. CampaignApprovalEnabled is the flag to specify whether to enable campaign approval in the HQ. If omitted, defaulted to false. LogLevel is the level of information logged by the HQ. Choice of Critical, Error, Warning, Information or Verbose. If omitted, defaulted to Verbose. Cmdlets This script uses the following PowerShell cmdlets. If required, these cmdlets can be run individually in place of the script. Set-LanguageSetting Set-CampaignApproval Set-LogSetting Tip: For more information on cmdlets, type Get-Help <cmdlet name> -Detailed in the Windows PowerShell console. Notes The default values used when script parameters are omitted are read from the file %PROGRAMDATA%\Pitney Bowes Software\Portrait Shared Server\PSSModules.config. Edit this file to change these defaults. CreatePortraitDatabases.ps1 Script name Location Purpose CreatePortraitDatabases.ps1 <PSS Installation Folder>\Administration Creates the Portrait Shared Repository and Portrait Data Warehouse databases.
Syntax CreatePortraitDatabases.ps1 [-DWDatabaseName] <String> [-PSRDatabaseName] <String> [-DBAccessUsername] <String> [-IntegratedSecurity] <String>[-DBUsername] <String> [-DBPassword] <String> [-DBServerName] <String> [-Sourceroot] <String> where: DWDatabaseName Name of the Portrait Data Warehouse database PSRDatabaseName Name of the Portrait Shared Repository database DBAccessUsername This is the identity under which the Portrait Shared Services will access the Portrait Shared Repository and Datawarehouse databases. IntegratedSecurity Flag to be set to enable (true) or disable (false) connecting to the database using Windows authentication. DBUsername User name for connecting to the database. Mandatory if integrated security is NOT enabled. DBPassword Password for the user to connect to the SQL Server. Mandatory if integrated security is NOT enabled. DBServerName Name or IP of the database server. Sourceroot Root location of the database sql scripts. Uses install folder when not specified. cmdlets The CreatePortraitDatabases.ps1 script makes use of two separate PowerShell cmdlets. If required, they can be run individually in place of the script. New-DatabaseDW: sets up the Portrait Data Warehouse database. New-DatabasePSR: sets up the Portrait Shared Repository database. Tip: For more information on cmdlets, type Get-Help <cmdlet name> -Detailed in the Windows PowerShell console. Notes The default values used when script parameters are omitted are read from the file %PROGRAMDATA%\Pitney Bowes Software\Portrait Shared Server\DbModules.config. Edit this file to change these defaults. DialogueIntegration.ps1 Script name Location Purpose DialogueIntegration.ps1 <PSS InstallationFolder>\Administration To enable or disable Portrait Dialogue on Portrait Shared Server.
Syntax DialogueIntegration.ps1 [[-WindowsAuthentication] <String>] [-PSSUserAcountName] <String> [-PSSUserAcountPassword] <String> [[-DialogueIntegrationEnabled] <String>] [[-DialogueServerURL] <String>][[-DialogueInstanceName] <String>] where: WindowsAuthentication specifies whether or not to use Windows authentication to log on to Portrait Shared Services. Set to true to use the current Windows user account to log on to Portrait Shared Services. PSSUserAccountName is the user name for connecting to Portrait Shared Services. Required only if WindowsAuthentication set to false. PSSUserAccountPassword is the password for connecting to Portrait Shared Services. Required only if WindowsAuthentication set to false. DialogueIntegrationEnabled specifies whether to enable (true) or disable (false) Portrait Dialogue integration with Portrait Shared Server. DialogueServerURL is the URL of the Portrait Dialogue Server API. For example, http://my-pd-server/mhdialogserverapi. DialogueInstanceName is the name of the Portrait Dialogue instance. Cmdlets The DialogueIntegration.ps1 script makes use of one PowerShell cmdlet. If required, it can be run individually in place of the script. Set-DialogueIntegration: sets the integration with Dialogue. Note: For more information on cmdlets, type Get-Help <cmdletname> in the Windows PowerShell console. Notes Caution: Running this script will re-start the Portrait Shared Server application pool. This has the effect of ending any open Portrait Shared Server sessions. Any users logged on to the HQ when the script is run will be forced to log in again. Any arguments not entered are read from %programdata%/\pitney Bowes Software\Portrait Shared Services\PSSModules.config. This script enables or disables integration between Portrait Dialogue and PSS. ExplorerIntegration.ps1 Script name Location Purpose ExplorerIntegration.ps1 <InstallationFolder>\PST\Portrait Shared Server\Administration To enable or disable Portrait Explorer on Portrait Shared Server.
Syntax ExplorerIntegration.ps1 [[-WindowsAuthentication] <String>] [-PSSUserAcountName] <String> [-PSSUserAcountPassword] <String> [[-ExplorerIntegrationEnabled] <String>] [[-ExplorerAnalyticsDataServerURL] <String>] where: WindowsAuthentication specifies whether or not to use Windows authentication to log on to Portrait Shared Services. Set to true to use the current Windows user account to log on to Portrait Shared Services. PSSUserAccountName is the user name for connecting to Portrait Shared Services. Required only if WindowsAuthentication set to false. PSSUserAccountPassword is the password for connecting to Portrait Shared Services. Required only if WindowsAuthentication set to false. ExplorerIntegrationEnabled allows you to enable (true) or disable (false) Portrait Explorer integration with PSS. ExplorerAnalyticsDataServerURL is the Analytics Data Server Server URL. Notes Any arguments not entered are read from %programdata%/\pitney Bowes Software\Portrait Shared Services\PSSModules.config. This script enables or disables integration between Portrait Explorer and PSS. InstallADSServices.ps1 Script name Location Purpose InstallADSServices.ps1 <InstallationFolder>\PST\Analytics Data Server\PowerShell Scripts To start the Analytics Data Server services required by Portrait Explorer. The Analytics Data Server consists of two services: The Analytics Data Server service hosts the available analytics services, and The Analytics Data Repository service allows access to the associated database. Both services must be configured and started in the correct order (Analytics Data Repository started first).
Syntax InstallADSServices.ps1 -ADRServiceName <value> -ADRPort value -DBFarmPath <value> -ADSServiceName <value> -ADSPort <value> where: ADRServiceName is the name assigned to the Analytics Data Repository service. ADRPort is the port number the Analytics Data Repository service listens on. DBFarmPath is the directory where the database is stored on the file system. ADSServiceName is the name assigned to the Analytics Data Server service. ADSPort is the port number the Analytics Data Server is hosted on. cmdlets The InstallADSServices.ps1 script makes use of two separate PowerShell cmdlets. If required, they can be run individually in place of the script: Add-AnalyticsDataRepository Add-AnalyticsDataServerService Note: You can choose to run individual cmdlets in place of the script if that is more efficient. For more information on cmdlets, type Get-Help <cmdletname> in the Windows PowerShell console. IOIntegration.ps1 Script name Location Purpose IOIntegration.ps1 <PSS Installation Folder>\Administration To enable or disable Interaction Optimizer on Portrait Shared Server.
Syntax IOIntegration.ps1 [[-WindowsAuthentication] <String>] [-PSSUserAccountName] <String> [-PSSUserAccountPassword] <String> [[-IOIntegrationEnabled] <String>] [[-IOServerURL] <String>] where: WindowsAuthentication specifies whether or not to use Windows authentication to log on to Portrait Shared Services. Set to true to use the current Windows user account to log on to Portrait Shared Services. PSSUserAccountName is the user name for connecting to Portrait Shared Services. Required only if WindowsAuthentication set to false. PSSUserAccountPassword is the password for connecting to Portrait Shared Services. Required only if WindowsAuthentication set to false. IOIntegrationEnabled specifies whether to enable (true) or disable (false) Interaction Optimizer integration with Portrait Shared Server. IOServerURL is the URL of the web server hosting the Interaction Optimizer web service API. For example, http://my-io-server. Cmdlets The IOIntegration.ps1 script makes use of one PowerShell cmdlet. If required, it can be run individually in place of the script. Set-IOIntegration: sets the integration with Interaction Optimizer. Tip: For more information on cmdlets, type Get-Help <cmdlet name> -Detailed in the Windows PowerShell console. Notes The default values used when script parameters are omitted are read from the file %PROGRAMDATA%\Pitney Bowes Software\Portrait Shared Services\PSSModules.config. Edit this file to change these defaults. ReportIntegration.ps1 Script name Location Purpose ReportIntegration.ps1 <PSS Installation Folder>\Administration To enable or disable Portrait Reports on Portrait Shared Server.