========================================================================== Oracle Commerce ========================================================================== ========================================================================== PATCH# ZDI-CAN-2660-11.0.0 ========================================================================== SUMMARY Date: March 19, 2015 Product: Oracle Commerce Guided Search and Experience Manager Version: 11.0.0 Description: This patch fixes ZDI-CAN-2660. This cumulative hofix includes the following bug hotfixes: 17614556 Existing user assigned admin rights will not have access to everything 17814194 dgraph starts with no config for extended period after baseline update 18671246 Running get_media or editors_config empties ./media or ./editor_config 19046330 Sort selected in Endeca Browser is always saved as descending 19137519 Issue with Migration script from 3.1.2 to 11.0.0 19215059 Silent install in TF doesn't have option to supply OraInventory location 19393804 Very large application logs get created 19416852 Issue with Migration script- Dynamic slot of content xml from 3.1.2 to 11.0.0 19627543 Having invalid XML characters when EXPMGR publishes to MDEX causes failure 19819611 Record selector not enough space 20211909 Experience Manager Editors - This hotfix allows the Endeca Browser to select records whose record spec contain commas. With this records under "Selected Records" tab would be displayed properly, even when we reopen Endeca Browser with our saved selection. 20309861 Unable to send a slash to Mdex through Tools server 20435809 promote_content gives zero-byte zip file 20574107 Can't select all values in record selector when too many results 20709655 Unable to save selection in Spotlight Records with % in the display text 20275685 ZDI-CAN-2660 ========================================================================== SUMMARY OF STEPS 1. Backup your Workbench configuration files and application state. 2. Export Workbench users. 3. Export application content and templates from Workbench. 4. Install ToolsAndFrameworks. 5. Update Deployment Templates. 6. Restore Workbench configuration and application state. 7. Initialize the application. 8. Import Workbench users. 9. Import application content and templates to Workbench. 10. Run a baseline update and promote content. 11. Update the shared secret. ========================================================================== BACKING UP YOUR TOOLS AND FRAMEWORKS SERVER 1. Stop the Endeca Tools Service. 2. Backing up the Workbench configuration files. Oracle Endeca Workbench uses several configuration files located in %ENDECA_TOOLS_CONF%\conf (on Windows) or $ENDECA_TOOLS_CONF/conf (on UNIX) to customize the behavior of various aspects of Workbench. These files store Workbench configuration, user authentication configuration, and definitions of the menus and extensions in Workbench Copy %ENDECA_TOOLS_CONF%\conf to a backup location \conf 3. Backing up the application state. The webstudiostore and emanager directories contain information about your application state, including user and permission settings, preview application settings, content XML, and resource metadata. To back up the application state directories: a. Stop the Endeca Tools Service. b. Copy the webstudiostore directory and its subdirectories from %ENDECA_TOOLS_CONF%\state\ (on Windows) or $ENDECA_TOOLS_CONF/state/ (on UNIX) to another location. This directory contains information such as users and permissions, as well as preview application settings. c. Copy the emanager directory andits subdirectories from %ENDECA_TOOLS_CONF%\state\ (on Windows) or $ENDECA_TOOLS_CONF/state/ (on UNIX) to another location. This directory contains resource metadata, state information, and content XML. 4. Start the Endeca Tools Service. ========================================================================== EXPORTING WORKBENCH USERS FROM TOOLS AND FRAMEWORKS To export Workbench users from Tools and Frameworks 11.0: 1. Configure the export_users script: a. Navigate to the ToolsAndFrameworks\11.0.0\admin\conf directory b. Open the export_users.properties file in a text editor. c. Set the following properties: #-------- source app version (required) source.version = 11.0.0 #-------- location of the webstudiostore of source version of workbench (required if source.version 2.1.x & 3.1.0) #source.webstudiostore= #-------- location of ws-extensions.xml (required if source.version 2.1.x & 3.1.0) #source.ws.extensions= #-------- source workbench host name (required if source version is 3.1.1, 3.1.2 or 11.0.0) source.workbench.host=localhost #-------- source workbench port number (required if source version is 3.1.1, 3.1.2 or 11.0.0) source.workbench.port=8006 #-------- destination workbench Tools and Frameworks directory (required if source version is 3.1.1 or 3.1.2, example: C:/Endeca/ToolsAndFrameworks/11.0.0) destination.directory=c:\Endeca\ToolsAndFrameworks\11.0.0 d. Save and close the file. 2. Navigate to the ToolsAndFrameworks\11.0.0\admin\bin directory. 3. Run the export_users script with the following parameters: • --config — Required. The path to the export_users.properties file. • --output — Optional. The path of the output file. If you do not specify this option, the output file is .\user_.json. For example: > export_users.bat --config ..\conf\export_users.properties This step exports users that can be imported into the 11.0 Workbench after installing the patch. . Confirm that the JSON file exists and contains the expected users. Note the following information as you review the results: • All administrator users and groups have an admin property set to true and do not have permission attributes. • LDAP users and groups have a principalSource value of LDAP. All others have the default value of Workbench. Sample user : { "id": "mmartin", "firstName": "melanie", "lastName": "martin", "email": "mmartin@example.com", "principalSource": "WORKBENCH", "admin": false, "permissions": [ { "application": "Discover", "tools": [ "extension1" ], } ] } Sample group: { "id": "global", "groupName": "global merchandising", "email": "global@example.com", "principalSource": "LDAP", "permissions": [ { "application": "Discover", "tools": [], } ] } You can check the script log at Endeca\ToolsAndFrameworks\11.0.0\admin\logs\export_users.log. 4. Make sure the exported users file is saved in a backup location outside the %ENDECA_TOOLS_ROOT% directory. ========================================================================== EXPORTING APPLICATION CONTENT AND TEMPLATES FROM WORKBENCH You back up application content in Workbench using the export_site script provided with the Deployment Template. The script exports application content in a format that can be re-imported to Workbench. The script connects to the Workbench instance for the current application based on the configuration in AppConfig.xml. Important: To guarantee consistent data, ensure that no baseline or partial updates are running during the backup process. To back up application content in Workbench: 1. Navigate to the control directory of your deployed application, for example, C:\Endeca\apps\Discover\control. 2. Run the export_site script, passing in an optional name for the export file, as in the following examples: export_site.bat C:\backup\Discover\11.0.0-export.xml On UNIX: ./export_site.sh ../backup/Discover/11.0.0-export.xml If no file name is provided, it defaults to a file named according to the pattern -yyyy-mm-dd_time.xml in the working directory. Repeat this procedure for every application. 3. Make sure the exported users file is saved in a backup location outside the %ENDECA_TOOLS_ROOT% directory. ========================================================================== INSTALL TOOLS AND FRAMEWORKS 1. Stop the Endeca Tools Service. 2. Take a backup of the existing %ENDECA_TOOLS_ROOT% folder (This backup is needed in case of rollback). 3. Delete %ENDECA_TOOLS_ROOT% 4. Unzip the patch file containing this readme file to a different temporary location. 5. Unzip the ToolsAndFrameworks-11.0.0--.zip from the temporary location into %ENDECA_TOOLS_ROOT%\..\.. NOTE: is either Linux64, Solaris or win64. is either xmgr or gs 6. Copy the jars eacComponents-11.0.0.jar, eacToolkit-11.0.0.jar, eacHandlers-11.0.0.jar, usageCollection-11.0.0.jar from "%ENDECA_TOOLS_ROOT%\reference\discover-data-cas\lib" to \config\lib\java This must be done for all deployed endeca applications. 7. Copy the jar indexConfigCommand-11.0.0.jar from "%ENDECA_TOOLS_ROOT%\reference\discover-data-cas\lib" to \config\lib\java This must be done for all deployed endeca cas applications. 8. Copy the jars 'endeca_navigation-6.4.1.jar' from "%ENDECA_TOOLS_ROOT%/assembler/lib" to the web application library folder for each application. If using ATG, copy the jar 'endeca_assembler-11.0.0.jar' from "%ENDECA_TOOLS_ROOT%/assembler/lib" to the existing "/DAF/Endeca/Assembler/lib". This must be done for all of your web applications. 9. If using ATG, start the ATG server. ========================================================================== UPDATE DEPLOYMENT TEMPLATES Note that this patch changes scripts in the deployment template (bug 17814194). This implies that existing deployments based on the provided deployment template will need to be changed in a similar manner. You will need to make these changes to any deployed applications as well or running a baseline_update will fail with the following error: Error in method invocation: Method updateConfigFromSnapshot() not found in class'com.endeca.soleng.eac.toolkit.component.cluster.DgraphCluster CHANGE LOG: %ENDECA_TOOLS_ROOT%/deployment_template/app-templates/base-app/config/script/DataIngest.xml %ENDECA_TOOLS_ROOT%/reference/discover-data-catalog-integration/script/DataIngest.xml %ENDECA_TOOLS_ROOT%/reference/discover-data-cas/script/DataIngest.xml Removes the call to 'LiveDgraphCluster.updateConfigFromSnapshot()' in 'DistributeIndexAndApply' function. This call applied the config to all the dgraphs after all had been started. %ENDECA_TOOLS_ROOT%/deployment_template/app-templates/base-app/config/script/LiveDgraphCluster.xml Adds a post startup script with id 'LiveDgraphPostStartup' that will apply the config to a dgraph immediately after it has been started by executing a method 'LiveDgraphCluster.applyConfigSnapshot()'. %ENDECA_TOOLS_ROOT%/deployment_template/app-templates/base-app/config/script/WorkbenchConfig.xml A method name change from 'LiveDgraphCluster.updateConfigFromSnapshot()' to 'LiveDgraphCluster.applyConfigSnapshot()'. This must be done for all of your applications. ========================================================================== RESTORE WORKBENCH CONFIGURATION AND APPLICATION STATE 1. Delete the workspace configuration directory 'conf' from %ENDECA_TOOLS_CONF%\conf (on Windows) or $ENDECA_TOOLS_CONF/conf (on UNIX). 2. Copy the backup of the conf directory you backed up in step 2 of BACKING UP YOUR TOOLS AND FRAMEWORKS SERVER from \conf to %ENDECA_TOOLS_CONF%\conf 3. Copy the backup of the webstudiostore directory in step 3 of including all its subdirectories, from \webstudiostore to %ENDECA_TOOLS_CONF%\state\webstudiostore (on Windows) or $ENDECA_TOOLS_CONF/state/webstudiostore (on UNIX). 4. Copy the backup of the emanager directory in step 3 of including all its subdirectories, from \emanager to %ENDECA_TOOLS_CONF%\state\emanager (on Windows) or $ENDECA_TOOLS_CONF/state/emanager (on UNIX). 5. Start the Endeca Tools Service. ========================================================================== INITIALIZE THE APPLICATION Run the initialize_services script to provision your application in the Endeca Application Controller. To provision your application: 1. Open the command prompt. 2. Navigate to the control directory of the deployed application. For example: C:\Endeca\Apps\Discover\control. 3. Run the initialize_services with the force argument. .\initialize_services.bat --force (on Windows) or ./initialize_services.sh --force (on UNIX) This re-provisions the application within the Endeca Application Controller and creates the necessary structure in Workbench. Repeat this procedure for all of your applications. Deploying and provisioning the application enables you to upload the exported files to the Workbench. ========================================================================== user IMPORT WORKBENCH USERS Use the import_users script to import user information from a JSON format to your Workbench installation. To import the users you previously exported: 1. Configure the import_users script: a) Navigate to the ToolsAndFrameworks\11.0.0\admin\conf directory. b) Open the import_users.properties file in a text editor and set the following properties: #-------- destination workbench host and port (required) dest.workbench.host=localhost dest.workbench.port=8006 c) Comment out the tools.mapping.file property #-------- location of tools mapping (required if source.version 2.1.x & 3.1.0) #tools.mapping.file= d) Save and close the file. 2. Navigate to the ToolsAndFrameworks\11.0.0\admin\bin directory. 3. Run the import_users script with the following parameters: • --input — Required. The path to the user data file that you got from running the export_users script earlier. • --config — Requred. The path to the import_users.properties file. • --default-user-password — The password value for any users that do not have a password set in the exported users file. • --single-app — Optional. A single application for which to import users. For example: > import_users.bat --input user_20140514.json --config ..\conf\import_users.properties --default-user-password CHANGEME --single-app Discover Invalid entries are logged to ToolsAndFrameworks\\admin\logs\import_validation_failed.log. The main log file is output to ToolsAndFrameworks\\admin\logs\import_users.log. ========================================================================== IMPORT APPLICATION CONTENT AND TEMPLATES TO WORKBENCH Running the import_site script uploads your exported application content to Workbench. Important: To guarantee consistent data, ensure that no baseline or partial updates are running during this process. To upload the application content into Workbench: 1. Navigate to the control directory of your deployed application. For example, C:\Endeca\apps\Discover\control. 2. Run the import_site script, passing in the file name of the export file produced during the export of the application content and templates. For example: C:\Endeca\apps\Discover\control>import_site.bat C:\backup\Discover\11.0.0-export.xml On UNIX: ./impport_site.sh ../backup/Discover/11.0.0-export.xml The following prompt appears: "Application '' already exists in IFCR. Delete existing content and continue? [Y/N]:" 3. Enter Y to proceed. 4. Confirm that the import operation completes successfully. Repeat this procedure for every application. ========================================================================== RUN A BASELINE UPDATE AND PROMOTE CONTENT After you have deployed your application and uploaded the exported content and configuration, you must initialize and start the Dgraph to make MDEX Engine data available. To run a baseline update: 1. Navigate to the control directory of your deployed application. For example, C:\Endeca\apps\Discover\control. 2. Run the load_baseline_test_data script. 3. Run the baseline_update script. 4. You may optionally promote teh content and configuration to you live servers. In the Discover Electronics reference application, this is accomplished by running the promote_content script in the control directory. Repeat this procedure for every application. ========================================================================== UPDATE THE SHARED SECRECT IN THE JCR 1) Edit %ENDECA_TOOLS_ROOT%/admin/conf/workbench.proeprties. a) Change workbench.host to reference your ToolsAndFrameworks host. b) Change workbench.port to reference your ToolsAndFrameworks port if different than 8006. c) Set workbench.sslEnabled=true if your ToolsAndFrameworks server is ssl enabled. 2) Change directories to %ENDECA_TOOLS_ROOT%/admin/bin. 3) Execute the set_shared_secret script passing in the workbench.properties config file and a new shared secret with --secret parameter. For example: Unix: ./set_shared_secret.sh --config ../conf/workbench.properties --secret 'some_secret_here' Windows: .\set_shared_secret.bat --config ..\conf\workbench.properties --secret some_secret_here NOTE: On Unix only, it's important to enclose the shared secret with single quotes to avoid the shell script interpreting the text as special characters. The secret value should not be enclosed in single quotes on Windows. ========================================================================== UPDATE THE DEFAULT SHARED SECRECT IN WEBSTUDIO.PROPERTIES 1) Navigate to %ENDECA_TOOLS_CONF%\conf. 2) Open the webstudio.properties file. 3) Locate the sharedSecret property. For example: # Shared secret used for all IFCR-hosted tools # Value should match the shared secret defined for each tool # in ws-extensions.xml sharedSecret=DLK#*@#%Gu3897hr*#FI$fil#H2oHP@ 4) Set the value of the property to the new shared secret. For example: sharedSecret=some_secret_here 5) Save and close the webstudio.properties file. 6) Restart your ToolsAndFrameworks server. ========================================================================== UPDATE THE SHARED SECRET FOR TOOLS EXTENSIONS For every extension, updated the shared secrect. It must match the shared secret in webstudio.propertes and the JCR. 1) Navigate to %ENDECA_TOOLS_CONF%\conf. 2) Open ws-extensions.xml and add or modify the shared secret as necessary for each extension. 3) Save and close the file. 4) Restart your ToolsAndFrameworks server. ========================================================================== DOCUMENTATION IMPACT: The 11.0 documentation has not been updated to reflect the changes outlined in this readme. In the content promotion sections of the Oracle Endeca Commerce Administrator's Guide, note that the updateConfigFromSnapshot() method has been renamed applyConfigSnapshot(). ========================================================================== COPYRIGHT AND DISCLAIMER Copyright 2001, 2015, Oracle and/or its affiliates. All rights reserved. Oracle and Java are registered trademarks of Oracle and/or its affiliates. Other names may be trademarks of their respective owners. UNIX is a registered trademark of The Open Group. This software and related documentation are provided under a license agreement containing restrictions on use and disclosure and are protected by intellectual property laws. Except as expressly permitted in your license agreement or allowed by law, you may not use, copy, reproduce, translate, broadcast, modify, license, transmit, distribute, exhibit, perform, publish, or display any part, in any form, or by any means. Reverse engineering, disassembly, or decompilation of this software, unless required by law for interoperability, is prohibited. The information contained herein is subject to change without notice and is not warranted to be error-free. If you find any errors, please report them to us in writing. U.S. GOVERNMENT END USERS: Oracle programs, including any operating system, integrated software, any programs installed on the hardware, and/or documentation, delivered to U.S. Government end users are "commercial computer software" pursuant to the applicable Federal Acquisition Regulation and agency-specific supplemental regulations. As such, use, duplication, disclosure, modification, and adaptation of the programs, including any operating system, integrated software, any programs installed on the hardware, and/or documentation, shall be subject to license terms and license restrictions applicable to the programs. No other rights are granted to the U.S. Government. This software or hardware is developed for general use in a variety of information management applications. It is not developed or intended for use in any inherently dangerous applications, including applications that may create a risk of personal injury. If you use this software or hardware in dangerous applications, then you shall be responsible to take all appropriate fail-safe, backup, redundancy, and other measures to ensure its safe use. Oracle Corporation and its affiliates disclaim any liability for any damages caused by use of this software or hardware in dangerous applications. This software or hardware and documentation may provide access to or information on content, products, and services from third parties. Oracle Corporation and its affiliates are not responsible for and expressly disclaim all warranties of any kind with respect to third-party content, products, and services. Oracle Corporation and its affiliates will not be responsible for any loss, costs, or damages incurred due to your access to or use of third-party content, products, or services.