Web Author Installation Guide

Transcription

1 Web Author Installation Guide / DITACMS V. 4.0 / Copyright 2015 IXIASOFT Technologies. All rights reserved. Last revised: February 02, 2015

2

3 Table of contents 3 Table of contents About this document Requirements 8 Download the Web Author package 9 What's new in this release of the documentation 9 Chapter 1: Installing the CMS Application Server for the first time Install the Java Development Kit 12 Change the Java logging level 12 Installing the Oracle GlassFish Server 13 Install the Oracle GlassFish Server on Windows 13 Install the Oracle GlassFish Server on Linux 16 Test your GlassFish installation 19 Enable logging for the CMS Application Server 20 Configure access to the TEXTML Server and Output Generator 20 Configure Kerberos authentication on the CMS Application Server (Windows only) 22 Deploy the CMS Application Server 25 Troubleshooting the CMS Application Server deployment 28 Chapter 2: Installing the Web Author Application for the first time

4 4 Web Author Installation Guide Installing Tomcat 33 Install Tomcat on Windows 33 Install Tomcat on Linux 34 Test your Tomcat installation 36 Modify the DITA CMS configuration to handle requests from the Web Author 37 Create a service user in the DITA CMS 38 Add new index definitions for roles in the DITA CMS 39 Configure the DITA CMS Lock method 41 Import the cms.webauthor DITA CMS system configuration 42 Configure the oxygen license 44 Site licenses: Configure the oxygen license in the DITA CMS 44 Floating licenses: Install, deploy, and configure the oxygen License Servlet 45 Install the Web Author Application 47 Web Author logging 48 Configure access to the DITA CMS, CMS Application Server, and oxygen License Servlet 48 Configure Kerberos authentication on the Web Author Application (Windows only) 50 (Optional) Configure the roles in the Web Author Application 52 Deploy the Web Author Application 52 Test your Web Author installation 53

5 Table of contents 5 Troubleshooting the Web Author installation 53 Chapter 3: Upgrading your Web Author installation Apply build-specific configuration updates 56 Build : Upgrade to JDK 7 57 Build : Add "Create topic" configuration 61 Build : Add "Change status" configuration 62 Build : Upgrade the DTDs to the new 4.0 model 63 Upgrade the online help 63 Upgrade the CMS Application Server 64 Upgrade the Web Author Application 66 Chapter 4: Managing and troubleshooting the Web Author Troubleshooting installation issues 68 Restarting the Web Author components 68 Troubleshooting:The TEXTML Server crashed and the CMS Application Server cannot be restarted 70 Troubleshooting: Users cannot commit document 71 Appendix A: Contact IXIASOFT Support for troubleshooting Determine the platform of the browser 74 Turn on the Java Console 74 Delete existing logs and capture new ones for troubleshooting 75 Appendix B: Adding your specializations to the Web Author Create a custom frameworks.zip file 78

6 6 Web Author Installation Guide Add the custom frameworks.zip file to your deployment 78

7 About this document This document describes how to install the Web Author on Windows and Linux and how to upgrade an existing installation. Installing the Web Author requires that you add the following two components to an existing DITA CMS installation: Web Author Application: The Web Author Application is a web application that allows content contributors and reviewers to easily edit and review DITA documents. It is a Tomcat application that supplies the graphical user interface to the Web Author Client. It connects to the CMS Application Server to provide the requested documents to the client. CMS Application Server: The CMS Application Server provides the business logic and cache for DITA CMS applications, such as the Web Author Application. It handles the requests to the TEXTML Server and Output Generator. The CMS Application Server is based on the GlassFish application server technology. The following diagram shows how the Web Author interacts with other DITA CMS components. Note that the diagram shows default port numbers; they may be different in your deployment. Note: The Web Author Application and CMS Application Server components can be installed on the same machine or on two different machines. Also, more than one Web Author Application can be installed and running on the same CMS Application Server.

8 8 Web Author Installation Guide Requirements The Web Author has the following software and hardware requirements. Web Author Client requirements The machine that runs the Web Author Client requires the following software: Internet browser: On Windows: Internet Explorer 8.x and up Mozilla Firefox 3.6 and up Safari 5.1 and up Google Chrome On Linux: Mozilla Firefox 3.6 and up Oracle Java JRE 1.7.0_51 and up Note: Because of an issue in Java 1.7.0_55, the Web Author is not supported on Java 1.7.0_55. CMS Application Server requirements The machine that runs the CMS Application Server has the following requirements: Hardware requirements Software requirements Quad-core (hyper threading does not count) Java JDK 1.7.0_51+ 8 GB of RAM minimum Web Author Application requirements The machine that runs the Web Author Application has the following requirements: Hardware requirements Software requirements Dual-core (hyper threading does not count) Java JRE 1.7.0_51+ 2 GB of RAM minimum

9 About this document 9 Creating a service user IXIASOFT recommends that you create a service user dedicated to the DITA CMS components (for example, CMSServiceUser). This service user account will be used to access the different DITA CMS components, such as the Web Author components, the Output Generator, the TEXTML Server, etc. Download the Web Author package The files required to install the Web Author are packaged in a zip file provided by IXIASOFT. To download the Web Author package: 1. Go to the IXIASOFT Web Author download page: 2. Click the DITA CMS version; for example, Click the latest build available for the DITA CMS; for example, Select WebAuthor-<version>.zip, where <version> is the latest version of the Web Author (for example, WebAuthor zip). 5. Extract the zip file. This package contains three directories, as follows: contentstore: Contains configuration that must be imported in the DITA CMS content store. glassfish: Contains files used during the installation of the GlassFish Server and the CMS Application Server. webauthor: Contains files used during the installation of the Tomcat Server and the Web Author Application. You will need these files when installing and configuring the Web Author. Related Links Upgrading your Web Author installation on page 55 This chapter describes how to upgrade an existing installation of the Web Author. What's new in this release of the documentation Build Updated the Requirements on page 8 for clarity.

10 10 Web Author Installation Guide Build First release of this document for DITA CMS 4.0. Includes minor version updates. Make sure to upgrade your existing installation as described in Upgrading your Web Author installation on page 55.

11 Installing the CMS Application 1Server for the first time Installing the CMS Application Server for the first time Topics: Install the Java Development Kit Installing the Oracle GlassFish Server Enable logging for the CMS Application Server Configure access to the TEXTML Server and Output Generator Configure Kerberos authentication on the CMS Application Server (Windows only) Deploy the CMS Application Server The CMS Application Server provides the business logic and cache for DITA CMS applications, such as the Web Author Application. It handles the requests to the TEXTML Server and Output Generator. The CMS Application Server is based on the GlassFish application server technology. To install the CMS Application Server: 1. Make sure the Java Development Kit is installed on the server. 2. Install the Oracle GlassFish Server. 3. Enable logging. 4. Configure the CMS Application Server to specify how to connect to the TEXTML Server and Output Generator. 5. (Optional) Configure Kerberos authentication. 6. Deploy the CMS Application Server. These steps are described below.

12 12 Web Author Installation Guide Install the Java Development Kit The CMS Application Server requires that the Java Development Kit (JDK) 1.7.0_51 (64-bit) be installed. If necessary, you can download it from the following URL: Note: Because of an issue in Java 1.7.0_55 and up, the Web Author is not supported on Java 1.7.0_55 and up. Change the Java logging level IXIASOFT recommends that you change the Java logging level to WARNING so that you do not get unnecessary entries in your logs. Note: This step is optional. To change the logging level in the JDK and the JRE: 1. Open the following file with a text editor: %JDK_location%/jre/lib/logging.properties For example: C:\Program Files\Java\jdk1.7.0_51\jre\lib\logging.properties 2. Set the.level value to WARNING. Note: This field is usually specified on line 29. For example:.level= WARNING 3. Save and close the file. 4. Open the following file with a text editor: %JRE_location%/lib/logging.properties For example: C:\Program Files\Java\jre7\lib\logging.properties 5. Set the.level value to WARNING.

13 Installing the CMS Application Server for the first time 13 For example:.level= WARNING 6. Save and close the file. Installing the Oracle GlassFish Server The CMS Application Server is based on the GlassFish application server technology, so you need to install the Oracle GlassFish Server. The Web Author supports version x and up of the GlassFish Server. Version 4.x is not supported. Note: Throughout this document, the %GlassFishDir% expression is used to represent the GlassFish installation directory, for example, C:\glassfish3\glassfish\. To install GlassFish, follow one of these procedures: Install the Oracle GlassFish Server on Windows on page 13 Install the Oracle GlassFish Server on Linux on page 16 Install the Oracle GlassFish Server on Windows To install the Oracle GlassFish Server on Windows: 1. Go to the following URL: 2. Select Click here to download Oracle GlassFish Server (3.1.2.x). Where x is the latest version available (for example, ), as shown below: Note: Do not select the Web Profile version of the Oracle GlassFish Server.

14 14 Web Author Installation Guide 3. Select Accept License Agreement. 4. Select the Windows Installer download (for example, ogs windows.exe). Important: Do not run the installer once it has downloaded. 5. Open a command line prompt in the directory where the installer was downloaded (for example, C:\Users\User1\Downloads). 6. Enter the following command: C:\Users\User1\Downloads>ogs-<3.1.2.x>-windows.exe -j "<java>" Where: <3.1.2.x> is the GlassFish version <java> is the location of the JDK on the machine For example: Important: This must be the JDK, not the JRE. C:\Users\User1\Downloads>ogs windows.exe -j "C:\Program Files\Java\jdk1.7.0_51" The installation process starts and the Oracle GlassFish Server Introduction window is displayed. 7. Click Next. 8. Select Typical Installation and click Next. 9. Keep the default installation directory and click Next.

15 Installing the CMS Application Server for the first time (Optional) If desired, activate the Install Update Tool and enter proxy server information as applicable. 11. Click Next. 12. Click Install. The Oracle GlassFish Server is installed and the Domain Info window is displayed. 13. Enter the GlassFish Server domain information: Domain Name: Enter cmsappserver Admin Port: Enter 4848 (keep default) HTTP Port: Enter a port that is not currently in use (for example, 8080) Username: Enter the username for accessing the GlassFish Administration Console; recommended value is admin Password: Enter the password for the GlassFish Administration Console username; for example, admin Reenter Password: For example, admin Click Create Operating System service for the domain Service Name: Enter cmsappserver Keep Start domain after creation checked 14. Click Next. The domain is configured.

16 16 Web Author Installation Guide 15. Click Next and then Exit to finish the installation. 16. Enable the access to the GlassFish Administration Console remotely, as follows: a) Open a command-line prompt. b) Go to the following directory: %GlassFishDir%/bin/ For example: cd C:\glassfish3\glassfish\bin c) Enter the following command: asadmin --host localhost --port 4848 enable-secure-admin A message similar to the following is displayed: You must restart all running servers for the change in secure admin to take effect. Command enable-secure-admin executed successfully. 17. To restart the GlassFish server, click the Start button and select All Programs > Oracle GlassFish Server > Start Application Server. Install the Oracle GlassFish Server on Linux IXIASOFT provides an answer file that you can use to install the GlassFish Server on Linux. To install the Oracle GlassFish Server on Linux: Note: You must have root privileges to run this procedure. 1. Go to the following URL: 2. Select Click here to download Oracle GlassFish Server (3.1.2.x). Where x is the latest version available (for example, ), as shown below: Note: Do not select the Web Profile version of the Oracle GlassFish Server.

17 Installing the CMS Application Server for the first time Select Accept License Agreement. 4. Select the Linux/Unix/Mac Installer download (for example, ogs unix.sh). 5. Log in to the CMS Application Server as user root. 6. Copy the glassfish/answer.txt file provided by IXIASOFT to the directory where you downloaded the GlassFish installer. 7. Open the answer.txt file and make sure that the following fields are set correctly: Domain.Configuration.ADMIN_USER, Domain.Configuration.ADMIN_PASSWORD, and Domain.Configuration.ADMIN_PASSWORD_REENTER: Set to the name and password of the user accessing the GlassFish Administration Console. InstallHome.directory.INSTALL_HOME: Set to the directory where the GlassFish software will be installed. JDKSelection.directory.HIDDEN_JDK and JDKSelection.directory.JDK_LIST: Set to the location of the JDK. 8. From the directory where the answer.txt file is located, run the following command: sh ogs-<3.1.2.x>-unix.sh -j "<java>" -a answer.txt -s Where: <3.1.2.x> is the GlassFish version <java> is the location of the JDK on the machine Important: This must be the JDK, not the JRE.

18 18 Web Author Installation Guide For example: sh ogs unix.sh -j /usr/java/jdk1.7.0_51/ -a answer.txt -s The Oracle GlassFish Server is installed. 9. Copy the glassfish/glassfish.cmsappserver file provided by IXIASOFT to the /etc/init.d directory. 10. To make the file executable, enter: chmod a+x <filename> For example: chmod a+x /etc/init.d/glassfish.cmsappserver 11. Open the glassfish.cmsappserver file and make sure the GLASSFISH_HOME variable is set to the location of the GlassFish installation. For example:... # Application APP_NAME="glassfish.cmsappserver" APP_LONG_NAME="Glassfish3 Domain CMS App Server" GLASSFISH_HOME=${GLASSFISH_HOME:-"/opt/glassfish3/glassfish"} GLASSFISH_DOMAINE=cmsappserver Add the cmsappserver service, as follows: /sbin/chkconfig --add glassfish.cmsappserver 13. Start the service, as follows: /sbin/service glassfish.cmsappserver start 14. Enable the access to the GlassFish Administration Console remotely, as follows: %GlassFishDir%/bin/asadmin --host localhost --port 4848 enable-secure-admin Where %GlassFishDir% is the location of the GlassFish directory; for example, enter: /opt/glassfish3/glassfish/bin/asadmin --host localhost --port 4848 enable-secure-admin If a message similar to the following is displayed, enter Y: Do you trust the above certificate [y N]

19 Installing the CMS Application Server for the first time Restart the service, as follows: /sbin/service glassfish.cmsappserver restart The GlassFish service is now started. Test your GlassFish installation Before you deploy the CMS Application Server on the GlassFish server, make sure GlassFish is installed properly. To test your installation: Enter the following URL in a web browser: Where <glassfishserver> is the address of the machine where the GlassFish Server is installed. For example: If the installation was successful, the Oracle GlassFish Server Administration Console login page is displayed:

20 20 Web Author Installation Guide Troubleshooting the GlassFish Server installation If an error occurs when starting the GlassFish Server, you can look at the log file for more information. The logs for the GlassFish Server are stored in the following file: %GlassFishDir%/domains/cmsappserver/logs/server.log "Certificate has expired" error If you see the following error message in the server.log file, you can safely ignore it: [# T11:10: SEVERE glassfish3.1.2 javax.enterprise.system.ssl. security.com.sun.enterprise.security.ssl.impl _ThreadID=1;_ThreadName=Thread-2; SEC5054: Certificate has expired: [[ Version: V3 Subject: CN=GTE CyberTrust Root 5, OU="GTE CyberTrust Solutions, Inc.", O=GTE Corporation, C=US Signature Algorithm: SHA1withRSA, OID = Key: Sun RSA public key, 2048 bits modulus: Enable logging for the CMS Application Server To enable logging, copy the glassfish/log4j.xml file provided by IXIASOFT to the following directory: %GlassFishDir%/domains/cmsappserver/config For example: C:\glassfish3\glassfish\domains\cmsappserver\config (Windows) /opt/glassfish3/glassfish/domains/cmsappserver/config (Linux) Configure access to the TEXTML Server and Output Generator The next step is to configure the CMS Application Server to specify how to connect to the TEXTML Server and Output Generator. To configure the CMS Application Server: 1. Copy the glassfish/cmsappserver.config file provided by IXIASOFT to your application server installation:

21 Installing the CMS Application Server for the first time 21 For example: C:\glassfish3\glassfish\domains\cmsappserver\config (Windows) /opt/glassfish3/glassfish/domains/cmsappserver/config (Linux) 2. Open the CMSAppServer.config file in an XML editor: <?xml version="1.0" encoding="utf-8"?> <!-- This configuration file must be installed in glassfish. It is put in the 'config' folder inside the domain folder created for the domain in which the cms app server is running. --> <config> <textml-connection address='[textml-server-host]' port='[textml-port]' docbase='docbase'/> <output-generator address='outputgen' port='outgen_port'/> <admin-login domain='userlogindomain' name='username' password='password'/>... <session idle-time='time_in_minutes'/>... <admin-tasks background-jobs='interval_in_minutes'/> </config> 3. Update the fields in bold as follows: Field [textml-server-host] [textml-port] [docbase-name] [output-generator-host] [outgen-port] userlogindomain, username, and password time_in_minutes Value to enter Address of the TEXTML Server that contains the Content Store for the Web Author TEXTML Server port Name of the Content Store on the TEXTML Server; this Content Store contains the documents for the Web Author Address of the Output Generator to connect to Output Generator port to connect to Domain, username, and password used by the CMS Application Server to log in to the TEXTML Server. Note: The username field cannot be empty. Important: IXIASOFT recommends that you use the service account dedicated to the DITA CMS components (for example, CMSServiceUser). Maximum time (in minutes) that a session can be idle before the system cleans it up. This value must always be less than the ConnectionTimeOut value configured for the TEXTML Server. If

22 22 Web Author Installation Guide Field Value to enter this value is set to 0, the system automatically defaults it to 5 minutes, since constantly checking for idle sessions will cause a heavy load on the server. To disable this option, set this value to a negative number (e.g., -1); note that this is NOT recommended. interval_in_minutes Interval (in minutes) at which administrative tasks (such as configuration reloads, adding users, etc.) should run. If this value is set to 0, the system automatically defaults it to 10 minutes, since constantly doing administrative tasks will cause a heavy load on the server. To disable this option, set this value to a negative number (e.g., -1); note that this is NOT recommended. For example: <?xml version="1.0" encoding="utf-8"?> <! > <config> <textml-connection address='server.acme.local' port='2500' docbase='production_docbase'/> <output-generator address='server.acme.local' port='1500'/> <admin-login domain="acme.local" name="cmsserviceuser" password="password"/>... <session idle-time='480'/>... <admin-tasks background-jobs='15'/> </config> Important: If your deployment uses version 4.3 of the TEXTML Server, the username used by the CMS Application Server to log in to the TEXTML Server must be assigned the Document Base Administrator role. Please contact IXIASOFT Support for more information. Configure Kerberos authentication on the CMS Application Server (Windows only) If the CMS Application Server connects to a TEXTML Server that uses Kerberos authentication, you must configure Kerberos authentication on the CMS Application Server. This section describes the procedure for configuring Kerberos authentication on the CMS Application Server.

23 Installing the CMS Application Server for the first time 23 Note: This procedure applies to Windows only. 1. Create the krb5.ini Kerberos configuration file. This file specifies the Kerberos configuration used for authentication. It must contain the following values: realm: Kerberos realm name. This is the Fully Qualified Domain Name (FQDN) of your Windows domain. kdc: Kerberos Key Distribution Center (KDC) host name and port (Windows domain controller). For example: [domain_realm].acme.local = ACME.LOCAL acme.local = ACME.LOCAL acme = ACME.LOCAL [libdefaults] dns_lookup_kdc = true dns_lookup_realm = true [logging] [realms] ACME.LOCAL = { kdc = dc1.acme.local kdc = dc2.acme.local admin_server = dc1.acme.local } 2. Save the file in the %GlassFishDir%/domains/cmsappserver/config directory. 3. Open the %GlassFishDir%/domains/cmsappserver/config/login.conf file with a text editor. 4. Add the following lines at the end of the file: TextmlClientLogin { com.sun.security.auth.module.krb5loginmodule required useticketcache=false; }; 5. Save and close the file. By default, the cmsappserver service is running as the Local System user. When you enable Kerberos, you must run the CMS Application Server as another user. 6. To run the CMS Application Server as another user. a) Click the Start button and select Control Panel > Administrative Tools. b) Double-click Services. c) Right-click the cmsappserver GlassFish Server service in the list and select Properties. d) In the Log On tab, select This account and click Browse.

24 24 Web Author Installation Guide The Select User window appears. e) Enter the name of the user that will run the CMS Application Server in the Enter the object names to select box and click Check Names. Note: IXIASOFT recommends that you use the service account dedicated to the DITA CMS components (for example, CMSServiceUser). The username is underlined. f) Click OK. g) Enter the password for this user in the Password and Confirm password fields. h) Click OK. If the following message is displayed: The account <account_name> has been granted the Log On As A Service right. Click OK. The following message is then displayed: The new logon name will not take effect until you stop and restart the service. i) Click OK. 7. To give the service user access to the GlassFish directory: 8. Give the service user (for example, CMSServiceUser) permissions to the GlassFish directory: a) Right-click the C:\glassfish3 directory and select Properties. b) Select the Security tab. c) Select the user under which the cmsappserver service is running. If the user under which the CMS Application Server runs is not listed in the Group or user names box: 1. Click Edit and then click Add. 2. In the Enter the object names to select box, type the username and click Check Names. 3. Click OK. 4. Select the username. d) Click Edit and set up full permissions for the username:

25 Installing the CMS Application Server for the first time 25 Figure 1: Giving permissions to the CMS Application Server e) Click OK to apply the changes. f) Click OK to close the dialog. Deploy the CMS Application Server The last step is to deploy the CMS Application Server on the GlassFish Server.You perform this step using the GlassFish Administration Console. To deploy the CMS Application Server: 1. In a browser window, enter the following URL: Where <glassfishserver> is the address of the machine where the GlassFish Server is installed. The Oracle GlassFish Server Administration Console login page is displayed. 2. Enter the User Name and Password specified when you installed GlassFish (for example, admin and admin). 3. Click Login.

26 26 Web Author Installation Guide The GlassFish Server Administration Console is displayed: 4. In the Common Tasks panel, expand Configurations > default-config and select JVM Setting. Perform the following steps for the default-config: a) In the JVM General Settings window, click the JVM Options tab. b) Click the Add JVM Option button and enter the following string in the Value field: -Dcom.sun.corba.ee.transport.ORBMaximumReadByteBufferSize= c) Click the Add JVM Option button again and enter the following string in the Value field: -Djava.security.krb5.conf=${com.sun.aas.instanceRoot}/config/krb5.ini d) Click the Add JVM Option button again and enter the following string in the Value field: -Djava.security.auth.login.config=${com.sun.aas.instanceRoot}/config/login.conf e) Click Save. 5. In the Common Tasks panel, expand Configurations > server-config and select JVM Setting. Repeat the same steps for the server-config:

27 Installing the CMS Application Server for the first time 27 a) Click the Add JVM Option button and enter the following string in the Value field: -Dcom.sun.corba.ee.transport.ORBMaximumReadByteBufferSize= b) Click the Add JVM Option button again and enter the following string in the Value field: -Djava.security.krb5.conf=${com.sun.aas.instanceRoot}/config/krb5.ini c) Click the Add JVM Option button again and enter the following string in the Value field: -Djava.security.auth.login.config=${com.sun.aas.instanceRoot}/config/login.conf 6. In the Common Tasks panel, select server (Admin Server). 7. In the General Information window, click Restart. 8. In the Common Tasks panel, select Applications. The Applications window is displayed. 9. Click Deploy. The Deploy Applications or Modules window is displayed. 10. Click Choose File, browse to the directory where you saved the glassfish/cmsappserver.ear file provided by IXIASOFT, and click Open. The Deploy Applications or Modules window is displayed again. 11. Keep all options as is, as shown below, and click OK.

28 28 Web Author Installation Guide The CMS Application Server is started and enabled, as shown in the following diagram: Note: By default, the CMS Application Server is started on port 3700.This value can be updated in the %GlassFishDir%/domains/cmsappserver/config/domain.xml file, under the <iiop-service> element; for example: c:\glassfish3\glassfish\domains\cmsappserver\config\domain.xml (Windows) /opt/glassfish3/glassfish/domains/cmsappserver/config/domain.xml (Linux) You can also configure it in the GlassFish Administration Console, as follows: under Configurations > server-config > ORB > IIOP Listeners > orb-listener-1. Troubleshooting the CMS Application Server deployment If you get an error message when deploying the CMS Application Server, you may not have correctly configured the access to the TEXTML Server and Output Generator. Check to see if the CMS Application Server was deployed To determine if the CMS Application Server was deployed, look at the following log file: %GlassFishDir%/domains/cmsappserver/logs/CMSAppServer.log This log file should contain the following message: CMSAppServer - CMSAppServer started up normally. If this message is not present, then the CMS Application Server was not deployed properly.

29 Installing the CMS Application Server for the first time 29 Determine why the CMS Application Server was not deployed properly To determine why the CMS Application Server was not deployed properly, look at the following log file: %GlassFishDir%/domains/cmsappserver/logs/CMSAppServer.log For example, consider the following messages: :18:42,061 [admin-thread-pool-4848(30)] INFO CMSAppServerBean - Loading configuration :18:43,695 [admin-thread-pool-4848(30)] INFO CMSAppServerBean - Found the following in app server configuration CMSAppServerConfig[textmlAddress=vm-cms-dev, textmlport=2500, textmldocbase=mydocbase, outgenaddress= englix.ixiasoft.local, outgenport= 1532, session_idle_time= 10, background_jobs= 15] :18:43,696 [admin-thread-pool-4848(30)] INFO CMSAppServerBean - Starting up app server internals :18:43,741 [admin-thread-pool-4848(30)] INFO LoginCall - Connecting to TEXTML v :18:44,376 [admin-thread-pool-4848(30)] ERROR CreateServerAdminSessionAction - Login error occurred. This message indicates that the CMS Application Server could not log in to the TEXTML Server. To solve this issue: 1. Check the CMSAppServer.config configuration file as described in Configure access to the TEXTML Server and Output Generator on page Make any required change. 3. Check that the administration user specified in the configuration file (under admin-login) has been added as a TEXTML Server user; try to log in to the TEXTML Server using the name and password specified in the file. 4. Redeploy the CMS Application Server. Contact IXIASOFT Support if the problem still occurs.

30 30 Web Author Installation Guide

31 Installing the Web Author 2Application for the first time Installing the Web Author Application for the first time Topics: Installing Tomcat Modify the DITA CMS configuration to handle requests from the Web Author Configure the oxygen license Install the Web Author Application Configure access to the DITA CMS, CMS Application Server, and oxygen License Servlet Configure Kerberos authentication on the Web Author Application (Windows only) (Optional) Configure the roles in the Web Author Application Deploy the Web Author Application Test your Web Author installation The Web Author Application is a Tomcat application that supplies the graphical user interface to the Web Author Client. It connects to the CMS Application Server to provide the requested documents to the client. To install the Web Author Application: 1. Install Tomcat. 2. Modify the DITA CMS configuration to handle requests from the Web Author. 3. Install the oxygen licenses required to use the Web Author. 4. Install the Web Author Application in Tomcat. 5. Configure the Web Author Application to specify how to access the DITA CMS, CMS Application Server, and oxygen License Servlet. 6. (Optional) Configure Kerberos authentication. 7. (Optional) Configure the roles for the Web Author Application. 8. Deploy the Web Author Application. 9. Test the installation. These steps are described below. Note: The Web Author Application can be installed on the same machine as the CMS Application Server. You can also install more than one instance of the

32 32 Web Author Installation Guide Web Author Application on the same CMS Application Server.

33 Installing the Web Author Application for the first time 33 Installing Tomcat The Web Author Application runs on the Apache Tomcat application server, so you need to install Tomcat. The Web Author supports version and up of Tomcat.Versions 7.x and 8.x are not supported. Note: Throughout this document, the %TomcatDir% expression is used to represent the Tomcat installation directory. To install Tomcat, follow one of these procedures: Install Tomcat on Windows on page 33 Install Tomcat on Linux on page 34 Install Tomcat on Windows To install Tomcat on Windows: 1. Go to the following URL: 2. Select 32-bit/64-bit Windows Service Installer. The apache-tomcat-6.0.x.exe file is downloaded. 3. Run the installer and follow the instructions.when requested to enter the Configuration Options, enter the following information: HTTP/1.1 Connector Port: Change the default value to specify a port that is not used (for example, 80). Important: Do not use the default HTTP/1.1 Connector Port (value 8080), since this will conflict with the GlassFish port. Tomcat Administrator Login User Name: Enter the username for accessing the Tomcat Manager. For example, admin. Tomcat Administrator Login Password: Enter the password for accessing the Tomcat Manager. For example, admin. You can leave the other fields as is; for example:

34 34 Web Author Installation Guide 4. Click Next. 5. Complete the installation, using the default values provided, and click Finish. 6. The next step is to set the Corba timeout in the Tomcat Monitor: a) From the Start menu, select All Programs > Apache Tomcat 6.0 Tomcat6, right-click Monitor Tomcat, and select Run as administrator. The Apache Tomcat 6.0 Tomcat6 Properties dialog appears. b) Select the Java tab. c) In the Java Options area, add the following option: -Dcom.sun.CORBA.transport.ORBTCPReadTimeouts=2:60000:500:7 Install Tomcat on Linux To install Tomcat on Windows on Linux: 1. Go to the following URL: 2. Select the tar.gz download. The apache-tomcat-6.0.x.tar.gz file is downloaded. 3. Untar the file to the /opt directory; for example: opt]# tar xvfz /home/userx/apache-tomcat tar.gz 4. Open the %TomcatDir%/conf/server.xml file (for example, /opt/tomcat6/conf/server.xml). 5. Set the port attribute to a port that is not currently used.

35 Installing the Web Author Application for the first time 35 For example: <Connector port="8090" protocol="http/1.1" connectiontimeout="20000" redirectport="8443" /> Note: By default, port 8080 is used, but this may conflict with the GlassFish server port. 6. Save and close the %TomcatDir%/conf/server.xml file. 7. Create the setenv.sh file in %TomcatDir%/bin/ and add the following lines: #!/bin/sh JAVA_OPTS="-Xms512m -Xmx2048m -Dcom.sun.CORBA.transport.ORBTCPReadTimeouts=2:60000:500:7" JRE_HOME="<JRE_Location>" export JAVA_OPTS export JRE_HOME Important: The JAVA_OPTS= statement must appear on a single line. 8. To make the file executable, enter: chmod a+x <filename> For example: chmod a+x /opt/tomcat6/bin/setenv.sh 9. Replace <JRE_Location> with the path to the Java installation on your machine: For example: JRE_HOME="/usr/java/jre1.7.0_51" 10. Save and close setenv.sh. Note: Make sure that setenv.sh has the same owner and permissions as startup.sh. 11. Start Tomcat from the %TomcatDir%/bin/ directory, as follows: [root@t19c6264 bin]#./startup.sh An output similar to the following is displayed: Using CATALINA_BASE: /opt/tomcat6 Using CATALINA_HOME: /opt/tomcat6 Using CATALINA_TMPDIR: /opt/tomcat6/temp Using JRE_HOME: /usr/java/jre1.7.0_51 Using CLASSPATH: /opt/tomcat6/bin/bootstrap.jar

36 36 Web Author Installation Guide Test your Tomcat installation Before you deploy the Web Author Application on the Tomcat server, make sure Tomcat is installed properly. To test your installation: Enter the following URL in a web browser: Where <tomcatserver> is the address of the Tomcat server. For example: If the installation was successful, the following page is displayed: Troubleshooting the Tomcat installation If a blank page is displayed, then Tomcat was not installed properly. The most common reason for a Tomcat installation failure is configuring the HTTP/1.1 Connector Port to a port that was already in use. To determine why Tomcat did not install and start properly, look at the following log file: %TomcatDir%/logs/catalina.<date>.log

37 Installing the Web Author Application for the first time 37 This file provides detailed information about why Tomcat did not start. For example, consider the following message: May 28, :16:30 AM org.apache.catalina.core.standardservice start SEVERE: Failed to start connector [Connector[HTTP/1.1-80]] LifecycleException: service.getname(): "Catalina"; Protocol handler start failed: java.net.bindexception: Address already in use: JVM_Bind <null>:80 This message indicates that Tomcat is configured to use HTTP/1.1 port 80, but this port is already used by another application. To solve this issue: 1. Find a port that is not used by another application. You can use a utility such as netstat to get a list of ports already used. 2. Open the %TomcatDir%/conf/server.xml file. 3. Look for the <Connector> element for the HTTP/1.1 protocol. For example: <Connector port="80" protocol="http/1.1" connectiontimeout="20000" redirectport="8443" /> 4. Set the port attribute as appropriate; for example: <Connector port="8090" protocol="http/1.1" connectiontimeout="20000" redirectport="8443" /> 5. Save and close the file. 6. Restart Tomcat. Contact IXIASOFT Support if you cannot solve the issue. Modify the DITA CMS configuration to handle requests from the Web Author Before you install the Web Author Application, you must create a Web Author user in the DITA CMS, add new index definitions, configure the Lock API call from the Web Author, and import the web.author DITA CMS system configuration. These steps are required to ensure that the DITA CMS can properly handle requests from the Web Author.

38 38 Web Author Installation Guide Create a service user in the DITA CMS When it starts, the Web Author Application logs in to the DITA CMS to retrieve files required to run the Web Author (for example, the online help). You need to create in the DITA CMS a username that can access the DITA CMS. IXIASOFT recommends that you use the service user dedicated to the DITA CMS components (for example, CMSServiceUser). Note: If you plan to run multiple instances of the Web Author Application, you should create a separate user for each instance to avoid accidental timeouts of your administration sessions. To add a Web Author user to the DITA CMS: 1. Start the DITA CMS and open the TEXTML Administration perspective. 2. Connect to your server and docbase. 3. Right-click the docbase and select DITA CMS Admin > Manage Users. 4. Click the Lock button ( ). 5. In the Users list, right-click the location node where you want to define the new user and select New User. A blank user entry appears below the selected node, and various user configuration panes appear. 6. In the User Personal Information pane: a) Click Active. b) Enter Web Author user in the First name field. 7. In the User Connection Information panel, enter the following information: Option Description Domain User name address Enter the domain for this user (for example, acme) Enter the username for the Web Author application; IXIASOFT recommends that you use CMSServiceUser, but you can enter any name Enter an address for this user (for example, CMSServiceUser@acme.com) The panels should look as follows: Note: Make sure to select Active.

39 Installing the Web Author Application for the first time Click Check In Document ( ). Your new user appears in the Users list. Add new index definitions for roles in the DITA CMS For each role available in the Web Author, you must specify the status that determines when documents are active for the role. For example, assume the following two roles: writer reviewer You could decide that, for writers, the documents must be in the Authoring:work status to be displayed in the Web Author; for reviewers, you could decide that the documents must be in the Authoring:review status to be displayed in the Web Author. Important: You may not need to perform this procedure. To determine if you need to add new index definitions:

40 40 Web Author Installation Guide 1. Start the DITA CMS and open the TEXTML Administration perspective. 2. Connect to your server and docbase. 3. Expand the docbase node to display the Index Definition branch. 4. Double-click the Index Definition document to open it. 5. Search for the active_contributor index; is it in the document? No: You must perform this procedure. Yes: Look at the status content of the active_contributor index (see step 7 on page 40 below); does it match the roles in your deployment? No: You must perform this procedure. Yes: You can skip this procedure. To implement these status, you create new elements in the active_contributor index definition, as shown below: 1. Start the DITA CMS and open the TEXTML Administration perspective. 2. Connect to your server and docbase. 3. Expand the docbase node to display the Index Definition branch. 4. Right-click Index Definition and select Lock. 5. Open the Index Definition Document in an XML editor. 6. Add the following custom property: <index CUSTOMPROPERTY="True" NAME="active_contributor" SYNC="True"> <!-- System index required by the DITA CMS --> <stringindex KEEPEXTRACTEDVALUES="True"> <elements> </elements> </stringindex> </index> 7. Under <elements> add an <element> for each role, as follows: <element DEPTH="INFINITE" XPATH="//assignedTo[parent::node()/@role='role' and //status='status']"/> Where: role: Is the role defined in the Web Author. The role names are case-sensitive and must match a role configured in the DITA CMS. status: Is the status at which the document will be visible for that role in the Web Author

41 Installing the Web Author Application for the first time 41 For example: <index CUSTOMPROPERTY="True" NAME="active_contributor" SYNC="True"> <!-- System index required by the DITA CMS --> <stringindex KEEPEXTRACTEDVALUES="True"> <elements> <element DEPTH="INFINITE" and //status='authoring:contribute']"/> <element DEPTH="INFINITE" and //status='authoring:work']"/> <element DEPTH="INFINITE" and //status='authoring:review']"/> <element DEPTH="INFINITE" and //status='authoring:review']"/> </elements> </stringindex> </index> 8. Save, close, and check in the index definition document. Note: Documents must also be assigned to the user, otherwise they will not be displayed in the Web Author. Configure the DITA CMS Lock method You must configure the DITA CMS Lock method to include the Web Author API call for locking documents. This ensures that the Web Author locks documents appropriately in the DITA CMS. 1. Start the DITA CMS and open the TEXTML Administration perspective. 2. Connect to your server and docbase. 3. Locate the accessrights.xml file in the repository's /system/conf collection. 4. Right-click the accessrights.xml file and select Check out. 5. Open accessrights.xml with a text editor. 6. Locate the line that starts with the following string: <method name="lock" type="front-end" hide-when-disabled="false" multiselect-disabled="false" use-specialization="false"> 7. After the type attribute, add the following attribute: alt="lockdocumentsaction" For example: <method name="lock" type="front-end" alt="lockdocumentsaction" hide-when-disabled="false" multiselect-disabled="false" use-specialization="false">

42 42 Web Author Installation Guide 8. Save, close, and check in the accessrights.xml file. Import the cms.webauthor DITA CMS system configuration If this is the first time that you install the Web Author, you need to import the cms.webauthor system configuration in the DITA CMS. This configuration contains the user assistance and the structure for the site licenses. The cms.webauthor system configuration is provided by IXIASOFT in the contentstore directory of the Web Author package. To import the cms.webauthor system configuration: 1. Start the DITA CMS and open the TEXTML Administration perspective. 2. Connect to your server and docbase. 3. Expand the docbase's repository node and right-click the system folder. 4. Select Insert Documents. The Insert Documents Dialog window appears. 5. Click Add Folder and browse to the contentstore directory of the extracted Web Author package provided by IXIASOFT. 6. Select the cms.webauthor directory and click OK. The Insert Documents Dialog window appears again, listing the cms.webauthor directory. 7. In the Set Options area, select Add and Replace. For example:

43 Installing the Web Author Application for the first time Click OK. The cms.webauthor directory is now displayed in the system configuration:

44 44 Web Author Installation Guide Configure the oxygen license Documents are edited and reviewed in the Web Author Application using the oxygen XML editor, so you need to install oxygen licenses for your users. There are two types of oxygen licenses: site licenses and floating licenses. You only need to install one type of license. The Web Author first checks if a site license is available; if it is, it will use this license. If a site license is not available, it will check if a floating license is available. If it does not find a floating license, the Web Author will not start. This section describes the procedures to install both types of licenses. Use the procedure for the licensing model selected for your deployment. Site licenses: Configure the oxygen license in the DITA CMS Site licenses are configured in a DITA CMS system configuration file. To configure an oxygen site license: 1. Start the DITA CMS and open the TEXTML Administration perspective. 2. Connect to your server and docbase. 3. Locate the oxygen.lic.empty file in the repository's /system/cms.webauthor/license collection. 4. Check out oxygen.lic.empty and open it with a text editor. The file looks as follows: START-LICENSE-KEY Enter your professional-site license here and rename the file oxygen.lic END-LICENSE-KEY Copy the oxygen license to the oxygen.lic.empty file; for example: Note: The license must be of category Professional-Site, as shown in bold below START-LICENSE-KEY Registration_Name=IXIASOFT Company=IXIASOFT Category=Professional-Site Component=Author-Component Version=14

45 Installing the Web Author Application for the first time 45 Number_of_Licenses=1 Date= Maintenance=0 SGN=<actual_license_here> END-LICENSE-KEY Save, close, and check in the oxygen.lic.empty file. 7. Right-click the oxygen.lic.empty file and select Rename. 8. In the New Document Name window, enter oxygen.lic and click OK. Floating licenses: Install, deploy, and configure the oxygen License Servlet Floating licenses are configured by installing and deploying a servlet that handles the oxygen licenses. To install the oxygen License Servlet: 1. Download the oxygen License Servlet from the following oxygen website: Note: For more information about running oxygen with floating licenses, see 2. Copy the oxygenlicenseservlet.war file to the following directory: %TomcatDir%\webapps Where %TomcatDir% is the location where you installed Tomcat. For example: C:\Program Files\Apache Software Foundation\Tomcat 6.0\webapps (Windows) /opt/tomcat6/webapps (Linux) Tomcat will deploy it automatically and the webapps directory now contains the oxygenlicenseservlet directory. Note: If the application does not get deployed after a few minutes, restart the Tomcat service. 3. Copy the floating license file (license.txt) provided by oxygen to the following directory: %TomcatDir%/webapps/oXygenLicenseServlet/WEB-INF/license Note: The actual path may vary according to your deployment.

46 46 Web Author Installation Guide 4. To configure the required security roles for the license, open the following file in an XML editor: %TomcatDir%/conf/tomcat-users.xml Note: The actual path may vary according to your deployment. 5. Add the following line to the file, in the <tomcat-users> element: <user username="license" password="license" roles="standard,manager"/> For example: <tomcat-users> <user username="license" password="license" roles="standard,manager"/> </tomcat-users> 6. Restart the Tomcat service. 7. To test your installation, enter the following URL in a web browser: Where <tomcatserver> is the address of the Tomcat server. For example: The <oxygen/> XML License Server page is displayed: 8. Click here, enter the username and password set in the tomcat-users.xml file (for example, license, license), and click Login. The <oxygen/> XML Floating License Server page is displayed, indicating that the servlet was installed correctly.

47 Installing the Web Author Application for the first time 47 Install the Web Author Application The next step is to install the Web Author Application. To install the Web Author Application: 1. Stop the Tomcat service. 2. Copy the webauthor/webauthor.war file provided in the IXIASOFT Web Author package to the following directory: %TomcatDir%/webapps Where %TomcatDir% is the location of the Tomcat installation. For example: C:\Program Files\Apache Software Foundation\Tomcat 6.0\webapps (Windows) /opt/tomcat6/webapps (Linux) 3. In the %TomcatDir%/conf directory, create a webauthor directory. For example: C:\Program Files\Apache Software Foundation\Tomcat 6.0\conf\webauthor (Windows) /opt/tomcat6/conf/webauthor (Linux) This ensures that the configuration files do not get erased every time you redeploy the Web Author Application. Note: The name of the directory must match the name of the war file. By default, this will be webauthor. But if you rename the.war file for example, to install multiple instances of the Web Author Application make sure that the directory created matches the new file name (without the.war extension). 4. Copy the following files (provided in the IXIASOFT Web Author package) to the directory created in the previous step (for example, %TomcatDir%/conf/webauthor/): webauthor/webconfig.xml webauthor/log4j.properties webauthor/web.author.roles.xml 5. On windows only: To configure the Corba time-out, start the Tomcat Monitor: a) From the Start menu, select All Programs > Apache Tomcat 6.0 Tomcat6, right-click Monitor Tomcat, and select Run as administrator. The Apache Tomcat 6.0 Tomcat6 Properties dialog appears. b) Select the Java tab.

48 48 Web Author Installation Guide c) In the Java Options area, add the following option: -Dcom.sun.CORBA.transport.ORBTCPReadTimeouts=2:60000:500:7 Web Author logging The Web Author uses standard Apache log4j logging. The logging file, log4j.properties, is stored in the following location: %TomcatDir%/conf/webauthor Unless requested by IXIASOFT Support, you do not need to update this file. Configure access to the DITA CMS, CMS Application Server, and oxygen License Servlet The next step is to configure the Web Author Application to specify how to connect to the DITA CMS, CMS Application Server, and oxygen License Servlet. To configure the Web Author Application: 1. Open the following file in an XML editor: %TomcatDir%/conf/webauthor/webconfig.xml Note: The actual path may vary according to your deployment. This file specifies how to connect to the CMS Application Server and looks as follows: <?xml version="1.0" encoding="utf-8"?> <!DOCTYPE properties SYSTEM " <properties> <comment>connection configuration for CMS Application Server</comment> <!--Configured admin user MUST be defined in the DITA CMS users.xml profiles. --> <entry key="administrator.domain">admin_domain</entry> <entry key="administrator.name">admin_name</entry> <entry key="administrator.password">admin_password</entry> <entry key="server.address">cms_app_server_address</entry> <entry key="server.port">3700</entry> <entry key="license.servlet.url"> license_servlet_url/oxygenlicenseservlet/license-servlet </entry> <entry key="license.servlet.username">license_username</entry> <entry key="license.servlet.password">license_password</entry> <! > <entry key="default.login.domain">default_domain</entry> <entry key="web.author.application.cfg">web.author.roles.xml</entry>

49 Installing the Web Author Application for the first time 49 <! > <entry key="cms.webauthor.frameworks.path"></entry> <entry key="cms.webauthor.options.path"></entry> </properties> Update the fields in bold as follows: Field admin_domain, admin_name, admin_password cms_app_server_address license_username, license_password license_servlet_url default_domain Enter this value Domain, username, and password used by the Web Author Application to log in to the DITA CMS and retrieve files required to run the Web Author (for example, the online help). IXIASOFT recommends that you use CMSServiceUser as the username. Note: You must also add this user to the DITA CMS, as described in Create a service user in the DITA CMS on page 38. Address of the CMS Application Server. If you are using the oxygen License Servlet, enter the username and password that you set for the License Servlet (for example, license and license). Note: Do not update these fields if you are using site licenses. If you are using the oxygen License Servlet, enter the URL of the License Servlet; this is the URL that the Web Author Client will use to find the License Servlet. Note: Do not update this field if you are using site licenses. Default domain when users log in to the Web Author. This ensures that users only need to enter a username and password when logging in to the Web Author. If you do not use domains for user logins, leave this field empty. This field is optional. You can leave all the other fields as is. For example: <?xml version="1.0" encoding="utf-8"?> <!DOCTYPE properties SYSTEM " <properties> <comment>connection configuration for CMS Application Server</comment>

50 50 Web Author Installation Guide <!-- Configured admin user MUST be defined in the DITA CMS users.xml profiles. --> <entry key="administrator.domain">acme</entry> <entry key="administrator.name">cmsserviceuser</entry> <entry key="administrator.password">admin</entry> <entry key="server.address">cmsappserver</entry> <entry key="server.port">3700</entry> <entry key="license.servlet.url"> </entry> <entry key="license.servlet.username">license</entry> <entry key="license.servlet.password">license</entry> <! > <entry key="default.login.domain">acme</entry> <entry key="web.author.application.cfg">web.author.roles.xml</entry> <! > <entry key="cms.webauthor.frameworks.path"></entry> <entry key="cms.webauthor.options.path"></entry> </properties> 2. Save and close the file. Configure Kerberos authentication on the Web Author Application (Windows only) If the CMS Application Server connects to a TEXTML Server that uses Kerberos authentication, you must configure Kerberos authentication on the Web Author Application. This section describes the procedure for configuring Kerberos authentication on the Web Author Application. Note: This procedure applies to Windows only. 1. Create the krb5.ini Kerberos configuration file. This file specifies the Kerberos configuration used for authentication. It must contain the following values: realm: Kerberos realm name. This is the Fully Qualified Domain Name (FQDN) of your Windows domain. kdc: Kerberos Key Distribution Center (KDC) host name and port (Windows domain controller). For example: [domain_realm].acme.local = ACME.LOCAL acme.local = ACME.LOCAL

51 Installing the Web Author Application for the first time 51 acme = ACME.LOCAL [libdefaults] dns_lookup_kdc = true dns_lookup_realm = true [logging] [realms] ACME.LOCAL = { kdc = dc1.acme.local kdc = dc2.acme.local admin_server = dc1.acme.local } 2. Save the file in the %TomcatDir%/conf/ directory. For example: C:\Program Files\Apache Software Foundation\Tomcat 6.0\conf\ 3. Create the login.conf login configuration file. This file specifies the Java login configuration for Active Directory. It must include the following code: TextmlClientLogin { com.sun.security.auth.module.krb5loginmodule required useticketcache=false; }; 4. Save the file in the %TomcatDir%/conf/ directory. 5. To specify the location of these files to Tomcat, start the Tomcat Monitor: a) From the Start menu, select All Programs > Apache Tomcat 6.0 Tomcat6, right-click Monitor Tomcat, and select Run as administrator. The Apache Tomcat 6.0 Tomcat6 Properties dialog appears. b) Select the Java tab. c) In the Java Options area, add the following options: -Djava.security.krb5.conf=%TomcatDir%\conf\krb5.ini -Djava.security.auth.login.config=%TomcatDir%\conf\login.conf Where %TomcatDir% is the location of the Tomcat directory; for example: -Djava.security.krb5.conf=C:\Program Files\Apache Software Foundation\Tomcat 6.0\conf\krb5.ini -Djava.security.auth.login.config=C:\Program Files\Apache Software Foundation\Tomcat 6.0\conf\login.conf Note: Do not use the %TomcatDir% variable; you must specify the absolute path to the Kerberos files.

52 52 Web Author Installation Guide (Optional) Configure the roles in the Web Author Application Depending on your DITA CMS configuration, you may need to configure the role names used in the Web Author. Important: You only need to perform this procedure if you changed the default roles for your company. Otherwise, if you are using the Writer, Reviewer, and Contributor roles, you can skip this procedure. By default, the following role names are used in the Web Author: Writer Contributor Reviewer If your configuration uses different names (for example, if the term "Author" is used in your DITA CMS instead of "Writer"): 1. Open the following file in an XML editor: %TomcatDir%/conf/webAuthor/web.author.roles.xml Note: The actual path may vary according to your deployment. This file defines the toolbar and menus available based on roles. 2. Make sure that the role names provided correspond to the roles configured for your company. For example, if the term "Author" is used in your DITA CMS instead of "Writer", look for the <role name="writer" string in the file and change it to Author; for example: <role name="author" css="dita.css" mode="full_tags" editable="true"> Deploy the Web Author Application To deploy the Web Author Application in Tomcat: 1. Start the Tomcat service. When it starts, Tomcat deploys the Web Author application and the %TomcatDir%/webapps directory now contains the webauthor directory.

53 Installing the Web Author Application for the first time To confirm that the Web Author application was deployed, check that the following directory exists: %TomcatDir%/webapps/webauthor/ Important: If this is not the first time that you deploy the Web Author Application and it does not seem to deploy properly: 1. Stop the Tomcat service. 2. Delete the %TomcatDir%/webapps/webauthor/ directory. 3. Restart this procedure at step 1. Test your Web Author installation The final step is to test your installation. To test your installation: 1. Enter the following URL in a web browser: Where: <tomcatserver:port> is the address of the Tomcat server <Web_Author_Application> is the name of the Web Author Application.war file (webauthor by default) For example: The Web Author login page is displayed, indicating that the application was installed correctly. Troubleshooting the Web Author installation If you see the Web Author login page but you do not see any documents, this means that documents haven't been assigned to you or that they are not in the right status. See the Web Author Administrator's Guide for more information. If the Web Author login page is not displayed, open the following log file: %TomcatDir%/logs/webauthor.log

54 54 Web Author Installation Guide This file provides details on the execution of the Web Author Application and will help you determine why the Web Author Application could not be started.

55 Upgrading your Web Author 3installation Upgrading your Web Author installation Topics: Apply build-specific configuration updates Upgrade the online help Upgrade the CMS Application Server Upgrade the Web Author Application This chapter describes how to upgrade an existing installation of the Web Author. It includes the following steps: 1. Apply build-specific configuration changes 2. Upgrade the online help 3. Upgrade the CMS Application Server 4. Upgrade the Web Author Application You must have downloaded the Web Author package before you start these procedures. Related Links Download the Web Author package on page 9 The files required to install the Web Author are packaged in a zip file provided by IXIASOFT.

56 56 Web Author Installation Guide Apply build-specific configuration updates When a new Web Author build is released, it sometimes requires changes to the configuration, especially when new features are added. This section describes the configuration changes introduced at specific builds. To determine which configuration updates you need to apply, first determine your current build number, as follows: 1. Open the %TomcatDir%/webapps/webauthor/META-INF/MANIFEST.MF file with a text editor. 2. Look for the value of the Implementation-Version field. It contains the build number. For example: Implementation-Version: This indicates that you are running version of the Web Author. You need to apply all the configuration changes for the builds that were released after your current build version. For example, if you're at version of the Web Author and you're upgrading to version , then you need to apply the following procedures: Build : Upgrade to JDK 7 Build : Add "Create topic" configuration Build : Add "Change status" configuration Build : Upgrade the DTDs to the new 4.0 model The following table lists the configuration updates currently available: Table 1: Configuration updates Build Number Configuration updates to apply Upgrade to JDK 7 Add "Create topic" configuration Add "Change status" configuration Upgrade the DTDs to the new 4.0 model

57 Upgrading your Web Author installation 57 Build : Upgrade to JDK 7 If your Web Author deployment is currently using version 6 of Java, you need to upgrade to version 7 as of build The CMS Application Server requires that the Java Development Kit (JDK) 1.7.0_51 (64-bit) be installed. Note: If you are already using version 7, you can skip this procedure. To upgrade a Java 6 deployment to Java 7: 1. Download the JDK from the following URL: Note: Because of an issue in Java 1.7.0_55 and up, the Web Author is not supported on Java 1.7.0_55 and up. 2. Install it according to the instructions from the Oracle website. You now need to upgrade the Java path in the configuration files used by the Web Author. Upgrade the Java installation on Windows You must update your Web Author installation to use Java Version Update the CMS Application Server installation as follows: a) Edit the %GlassFishDir%/lib/registration/servicetag-registry.xml file. For example, C:\glassfish3\glassfish\lib\registration\servicetag-registry.xml. b) Update the <product_defined_inst_id> tag to point to the JDK 7 installation. For example: <product_defined_inst_id>os.name=windows Server 2008;os.version=6.0;java.version=1.7.0_51;java.home=c:\Program Files\Java\jdk1.7.0_51\jre;</product_defined_inst_id> c) Edit the %GlassFishDir%/config/asenv.bat file. For example, C:\glassfish3\glassfish\config\asenv.bat. d) Update the AS_JAVA variable to point to the JDK 7 installation. For example: set AS_JAVA=c:\Program Files\Java\jdk1.7.0_51 e) Edit the C:\glassfish3\var\install\config\Domain\JDKSelection.xcu file.

58 58 Web Author Installation Guide f) If this file includes paths to the JDK 6 installation, update them to point to the JDK 7 installation. Note: This file does not always include the JDK installation path. If that is the case, you do not need to update the file. For example: <?xml version="1.0" encoding="utf-8" standalone="yes"?> <ns1:component-data xmlns:ns1=" xmlns:ns3=" ns1:readonly="true" ns1:finalized="true" ns1:package="org.openinstaller.jdkselection"> <node ns1:name="directory"> <prop ns1:type="xs:boolean" ns1:name="jdk_from_list_choice"> <value>true</value> </prop> <prop ns1:type="xs:boolean" ns1:name="jdk_typed_in_choice"> <value>false</value> </prop> <prop ns1:type="xs:string" ns1:name="jdk_list"> <value>c:\program Files\Java\jdk1.7.0_51 (v _51 by Oracle Corporation)</value> </prop> <prop ns1:type="xs:string" ns1:name="jdk_versionrange"> <value>jdk[1.6--infinity)</value> </prop> <prop ns1:type="xs:string" ns1:name="jdk_type_in"> <value></value> </prop> <prop ns1:type="xs:string" ns1:name="hidden_jdk"> <value>c:\program Files\Java\jdk1.7.0_51</value> </prop> <prop ns1:type="xs:string" ns1:name="selected_jdk"> <value>c:\program Files\Java\jdk1.7.0_51</value> </prop> <prop ns1:type="xs:boolean" ns1:name="select_jdk_to_install"> <value>false</value> </prop> <prop ns1:type="xs:string" ns1:name="onload"> <value>true</value> </prop> </node> </ns1:component-data> 2. Update the Web Author Application installation as follows: a) From the Start menu, select All Programs > Apache Tomcat 6.0 Tomcat6, right-click Configure Tomcat, and select Run as administrator. b) Click the Java tab. c) Set the Java Virtual Machine field to point to the jvm.dll file on your computer. For example:

59 Upgrading your Web Author installation 59 Note: The JDK folder contains a jre folder. If you have installed the JDK then you automatically have the JRE as well. In that case, you can point to the jvm.dll file that is part of the JDK; for example: C:\Program Files\Java\jdk1.7.0_51\jre\bin\server\jvm.dll. Upgrade the Java installation on Linux You must update your Web Author installation to use Java Version Update the CMS Application Server installation as follows: a) Open the %GlassFishDir%/config/asenv.conf file. For example, /opt/glassfish3/glassfish/config/asenv.conf. b) Update the AS_JAVA variable to point to the JDK 7 installation. For example: AS_JAVA=/usr/java/jdk1.7.0_51 c) Open the /opt/glassfish3/var/install/config/domain/jdkselection.xcu file. d) Update all the paths to point to the JDK 7 installation.

60 60 Web Author Installation Guide For example: <?xml version="1.0" encoding="utf-8" standalone="yes"?> <ns1:component-data xmlns:ns1=" xmlns:ns2="h ttp://openinstaller.org/config/v1" ns1:readonly="true" ns1:finalized="true" ns1: package="org.openinstaller.jdkselection"> <node ns1:name="directory"> <prop ns1:type="xs:boolean" ns1:name="jdk_from_list_choice"> <value>true</value> </prop> <prop ns1:type="xs:boolean" ns1:name="jdk_typed_in_choice"> <value>false</value> </prop> <prop ns1:type="xs:string" ns1:name="jdk_list"> <value>/usr/java/jdk1.7.0_51 (v _51 by Sun Microsystems Inc.)< /value> </prop> <prop ns1:type="xs:string" ns1:name="jdk_versionrange"> <value>jdk[1.7--infinity)</value> </prop> <prop ns1:type="xs:string" ns1:name="jdk_type_in"> <value></value> </prop> <prop ns1:type="xs:string" ns1:name="hidden_jdk"> <value>/usr/java/jdk1.7.0_51</value> </prop> <prop ns1:type="xs:string" ns1:name="selected_jdk"> <value>/usr/java/jdk1.7.0_51</value> </prop> <prop ns1:type="xs:boolean" ns1:name="select_jdk_to_install"> <value>false</value> </prop> <prop ns1:type="xs:string" ns1:name="onload"> <value>true</value> </prop> </node> </ns1:component-data> 2. Update the Web Author Application installation as follows: a) Open the %TomcatDir%/bin/setenv.sh file. b) Replace <JRE_Location> with the path to the Java 7 installation on your machine: For example: JRE_HOME="/usr/java/jre1.7.0_51" Note: The JDK folder contains a jre folder. If you have installed the JDK then you automatically have the JRE as well. In that case, you can point to the jre folder that is part of the JDK; for example: JRE_HOME="/usr/java/jdk1.7.0_51/jre" c) Save and close setenv.sh. d) Start Tomcat from the %TomcatDir%/bin/ directory, as follows: [root@t19c6264 bin]#./startup.sh

61 Upgrading your Web Author installation 61 An output similar to the following is displayed: Using CATALINA_BASE: /opt/tomcat6 Using CATALINA_HOME: /opt/tomcat6 Using CATALINA_TMPDIR: /opt/tomcat6/temp Using JRE_HOME: /usr/java/jre1.7.0_51 Using CLASSPATH: /opt/tomcat6/bin/bootstrap.jar Build : Add "Create topic" configuration Build introduces a new feature that allows users to create topics while using the Web Author. This feature is disabled by default. To allow users to create topics, you first need to add two configuration files to your DITA CMS; you then enable this feature as described in the Web Author Administrator's Guide. Note: Even if you do not plan to use this feature, you still need to add the configuration files to your DITA CMS for backward compatibility. To add the "Create topic" configuration: 1. Start the DITA CMS and open the TEXTML Administration perspective. 2. Connect to your server and docbase. 3. Expand the docbase's repository node and navigate to the system/cms.webauthor/configuration folder. 4. Look under the configuration folder and check whether the templates.dtd and templates.xml files exist: If the files exist, please contact IXIASOFT Support to verify if you need to update them. Do not perform the remainder of this procedure unless requested by IXIASOFT. If the files do not exist, continue to step Right-click the configuration folder and select Insert Documents. The Insert Documents Dialog window appears. 6. Click Add File and browse to the contentstore/cms.webauthor/configuration directory of the extracted Web Author package provided by IXIASOFT. 7. Select the templates.dtd and templates.xml files and click Open. 8. Click OK. The files are added to the DITA CMS configuration.

62 62 Web Author Installation Guide The templates.xml file specifies the user roles allowed to create topics as well as the templates associated with each topic type. By default, this feature is disabled. To allow users to create new topics, see the Web Author Administrator's Guide. Build : Add "Change status" configuration Build introduces a new feature that lets users change the status of their topics while using the Web Author. This feature is disabled by default. To allow users to change the status of topics, you first need to add a configuration file to your DITA CMS; you then enable this feature as described in the Web Author Administrator's Guide. Note: Even if you do not plan to use this feature, you still need to add the configuration file to your DITA CMS for backward compatibility. 1. Start the DITA CMS and open the TEXTML Administration perspective. 2. Connect to your server and docbase. 3. Expand the docbase's repository node and navigate to the the system/cms.webauthor/configuration folder. 4. Look under the configuration folder and check whether the statuschangeconfig.xml file exists: If the file exists, please contact IXIASOFT Support to verify if you need to update it. Do not perform the remainder of this procedure unless requested by IXIASOFT. If the file does not exist, continue to step Right-click the configuration folder and select Insert Documents. The Insert Documents Dialog window appears. 6. Click Add File and browse to the contentstore/cms.webauthor/configuration directory of the extracted Web Author package provided by IXIASOFT. 7. Select the statuschangeconfig.xml file and click Open. 8. Click OK. The file is added to the DITA CMS configuration. This file specifies the roles that can perform Change status operations as well as status changes available. You may need to modify this file if your deployment is not using the standard roles (Contributor, Writer, Reviewer) or standard workflow. See the Web Author Administrator's Guide for more information.

63 Upgrading your Web Author installation 63 Build : Upgrade the DTDs to the new 4.0 model The DTD model has changed in version 4.0 of the DITA CMS. As such, you must also update the Web Author to use the new DTD structure. Note: Make sure you have applied all the configuration updates for the previous 1.0.9* builds before performing this procedure. This procedure assumes that you have created a plug-in for your DTDs as described in the Integrating DTDs into the DITA CMS document. 1. Start the DITA CMS and open the TEXTML Administration perspective. 2. Connect to your server and docbase. 3. Expand the docbase's repository node and navigate to the system/cms.webauthor/frameworks folder. 4. Make a backup copy of your existing frameworks: a) Right-click frameworks.zip and select Rename. b) Enter frameworks.zip.backup and click OK. 5. Download the 4.0 frameworks.zip from the following URL: 6. Add your DTDs as described in Adding your specializations to the Web Author on page If you made other changes to the frameworks, for example to apply different CSS, reapply these changes in the 4.0 framework. Upgrade the online help To get the latest documentation, you need to upgrade the online help. 1. Start the DITA CMS and open the TEXTML Administration perspective. 2. Connect to your server and docbase. 3. Expand the docbase's repository node and navigate to the system/cms.webauthor/help folder. 4. Right-click the help folder and select Insert Documents. The Insert Documents Dialog window appears.

64 64 Web Author Installation Guide 5. Click Add File and browse to the contentstore/cms.webauthor/help directory of the extracted Web Author package provided by IXIASOFT. 6. Select the cms.webauthor.hlp file and click Open. 7. In the Set Options area, select Add and Replace. 8. Click OK. The file is added to the DITA CMS configuration. Upgrade the CMS Application Server To update the CMS Application Server, you upload the glassfish/cmsappserver.ear file and deploy it again. 1. In a browser window, enter the following URL: Where <glassfishserver> is the address of the machine where the GlassFish Server is installed. The Oracle GlassFish Server Administration Console login page is displayed. 2. Enter the User Name and Password specified when you installed GlassFish (for example, admin and admin). 3. Click Login. The GlassFish Server Administration Console is displayed:

65 Upgrading your Web Author installation In the Common Tasks panel, select Applications. The Applications window is displayed. 5. Click Redeploy. The Redeploy Applications or Modules window is displayed. 6. Click Choose File, browse to the directory where you saved the glassfish/cmsappserver.ear file provided by IXIASOFT, and click Open. The Deploy Applications or Modules window is displayed again. 7. Keep all options as is, as shown below, and click OK. The CMS Application Server is upgraded and enabled, as shown in the following diagram:

66 66 Web Author Installation Guide Upgrade the Web Author Application To update the Web Author Application, you copy the webauthor/webauthor.war file and deploy it again. 1. Stop the Tomcat service. 2. Delete the %TomcatDir%/webapps/webauthor directory. 3. Delete the %TomcatDir%/webapps/webauthor.war file. 4. Copy the webauthor/webauthor.war file provided in the IXIASOFT Web Author package to the following directory: %TomcatDir%/webapps Where %TomcatDir% is the location of the Tomcat installation. For example: C:\Program Files\Apache Software Foundation\Tomcat 6.0\webapps (Windows) /opt/tomcat6/webapps (Linux) 5. Restart the Tomcat service.

67 Managing and troubleshooting the 4Web Author Managing and troubleshooting the Web Author Topics: Troubleshooting installation issues Restarting the Web Author components Troubleshooting: The TEXTML Server crashed and the CMS Application Server cannot be restarted Troubleshooting: Users cannot commit document This section provides information for managing and troubleshooting your Web Author installation.

68 68 Web Author Installation Guide Troubleshooting installation issues If you encounter issues while installing the Web Author, see the Troubleshooting section that applies to the Web Author component that is causing the issue, as described in the following table: Component GlassFish Server installation CMS Application Server deployment Tomcat installation Web Author installation Section Troubleshooting the GlassFish Server installation on page 20 Troubleshooting the CMS Application Server deployment on page 28 Troubleshooting the Tomcat installation on page 36 Troubleshooting the Tomcat installation on page 36 Restarting the Web Author components If you need to restart the TEXTML Server, you must stop and restart the Web Author components in a specific order. 1. Before stopping the TEXTML Server: a) Stop the Tomcat service: On Windows: On Linux: Click the Start button and select All Programs > Oracle GlassFish Server > Stop Application Server. Go to the %TomcatDir%/bin/ directory and enter the following command: [root@t19c6264 bin]#./shutdown.sh b) Stop the CMS Application Server: On Windows: Click the Start button and select All Programs > Oracle GlassFish Server > Stop Application Server.

69 Managing and troubleshooting the Web Author 69 On Linux: Enter the following command: /sbin/service glassfish.cmsappserver stop 2. Restart the TEXTML Server. 3. When the TEXTML Server is restarted: a) Restart the CMS Application Server: On Windows: On Linux: Click the Start button and select All Programs > Oracle GlassFish Server > Start Application Server. Enter the following command: /sbin/service glassfish.cmsappserver start b) Wait 30 seconds and check that the CMS Application Server has correctly restarted: Look at the following log file: %GlassFishDir%/domains/cmsappserver/logs/CMSAppServer.log This log file should contain the following message: CMSAppServer - CMSAppServer started up normally. Wait until this message is displayed. c) Start the Tomcat service. d) Check that the service has correctly started: Look at the following log file: %TomcatDir%/logs/webauthor.log This log file should contain the following message: Initialization complete

70 70 Web Author Installation Guide Troubleshooting: The TEXTML Server crashed and the CMS Application Server cannot be restarted Problem description In some cases, if the TEXTML Server crashes while the Web Author is in use, the CMS Application Server component cannot be restarted properly. This can happen if the CMS Application Server did not shut down properly and is still running. To determine if this is the case: 1. Stop the CMS Application Server: On Windows: On Linux: Click the Start button and select All Programs > Oracle GlassFish Server > Stop Application Server. Enter the following command: /sbin/service glassfish.cmsappserver stop 2. Try to rename the %glassfish%\domains\cmsappserver\logs\cmsappserver.log file. If you cannot rename the file, then the process is still running and must be killed manually. Solution The solution is to kill the process. Unfortunately, determining which process to kill is not straightforward. On Windows: You can use a tool such as Process Explorer from the Windows Sysinternals Suite (available at This tool will help you determine which process to kill. To kill the process using the Process Explorer tool on Windows: 1. Download and install Windows Sysinternals Suite (available at 2. Double-click the procexp.exe program in the Sysinternals Suite. 3. From the Process Explorer menu, select Find > Find Handle or DLL. 4. In the Process Explorer search window, enter the name of the log file (i.e., CMSAppServer.log) and click Search.

71 Managing and troubleshooting the Web Author 71 The java.exe process to kill is displayed in the window. 5. In the Process Explorer window, right-click the process and select Kill Process. On Linux: 1. Enter the following command: ps -ef grep glassfish This will return the process that is running the GlassFish service. 2. Enter the following command to kill the process: kill <process_number> Where <process_number> is the GlassFish process. You can then restart the Web Author components as described in Restarting the Web Author components on page 68. Troubleshooting: Users cannot commit document Problem description Users are able to click Edit Document and make their changes, but when they try to submit their changes, the following message appears: Action failed due to server-side error. For example:

72 72 Web Author Installation Guide This error can occur when public IDs have not been properly defined in your catalogs. To confirm that this is the problem: 1. Open the GlassFish log file: %glassfish%/domains/cmsappserver/logs/server.log For example: C:\glassfish3\glassfish\domains\cmsappserver\logs\server.log 2. Look for the logs that occurred around the date and time that the user experienced the problem. If you see a message similar for the following: Caused by: com.ixiasoft.cms.api.model.exception.cmscatalogexception: Your catalog is not configured correctly for item with public id =[ -//IXIA//DTD IXIA DITA Composite//EN ] Then one of your catalogs is missing a public ID. The error message specifies the public ID that is missing. For example, in the deployment above, you need to define the following public ID: -//IXIA//DTD IXIA DITA Composite//EN Solution To solve this issue: 1. Open the TEXTML Administration view. 2. Connect to your server and docbase. 3. Navigate to the Repository/system/catalogs collection. 4. Check out the catalog to which you need to add the public ID. 5. Add the public ID definition to the catalog; for example, for the error above, you could add the following line to the catalog-dita-ixia.xml catalog: <public publicid="-//ixia//dtd IXIA DITA Composite//EN" uri="ixiaditabase.dtd"/> 6. Save and check in the file. 7. Restart the CMS Application Server.

73 Contact IXIASOFT Support for Atroubleshooting Contact IXIASOFT Support for troubleshooting Topics: Determine the platform of the browser Turn on the Java Console Delete existing logs and capture new ones for troubleshooting If an error occurs when installing the Web Author and you cannot solve the issue, you need to contact IXIASOFT Support and send logs that will help identify the issue. This document describes the steps to perform before contacting IXIASOFT Support for Web Author installation issues. There are three main steps involved in sending IXIASOFT Support the logs required to solve the issue: 1. Determine the platform of the browser on the client. 2. Turn on the Java console in the browser. 3. Delete existing logs and capture new ones on the server.

74 74 Web Author Installation Guide Determine the platform of the browser To determine the platform of the browser: Find out whether the browser is 32-bit or 64-bit: If your operating system is 32-bit, then the browser is 32-bit. If your operating system is 64-bit: a) Start the Task Manager. b) Click the Processes tab. c) Check the process for the browser; if it has an asterisk beside it (for example, chrome.exe *32 in the following diagram), the browser is 32-bit. Otherwise, the browser is 64-bit. Turn on the Java Console This procedure describes how to turn on the Java Console and enable its debugging and logging options. For a 32-bit operating system 1. Open the Control Panel. 2. Double-click Java. 3. Click the Advanced tab. 4. Expand the Debugging section. 5. Check the following options: Enable tracing Enable logging