Server Installation Guide. Alfresco Mobile Workdesk

Transcription

1 Server Installation Guide Alfresco Mobile Workdesk

2 Copyright 2013 by Alfresco and others. Information in this document is subject to change without notice. No part of this document may be reproduced or transmitted in any form or by any means, electronic or mechanical, for any purpose, without the express written permission of Alfresco. The trademarks, service marks, logos, or other intellectual property rights of Alfresco and others used in this documentation ("Trademarks") are the property of Alfresco and their respective owners. The furnishing of this document does not give you license to these patents, trademarks, copyrights, or other intellectual property except as expressly provided in any written agreement from Alfresco. The United States export control laws and regulations, including the Export Administration Regulations of the U.S. Department of Commerce, and other applicable laws and regulations apply to this documentation which prohibit the export or re-export of content, products, services, and technology to certain countries and persons. You agree to comply with all export laws, regulations, and restrictions of the United States and any foreign agency or authority and assume sole responsibility for any such unauthorized exportation. You may not use this documentation if you are a competitor of Alfresco, except with Alfresco's prior written consent. In addition, you may not use the documentation for purposes of evaluating its functionality or for any other competitive purposes. This copyright applies to the current version of the licensed program. ii

3 Table of Contents Introduction... 1 About this guide... 2 Intended audience... 2 Typographical conventions used in this guide... 3 Abbreviations... 4 Checklist... 5 PREREQUISITES... 6 Server-side prerequisites... 6 Application server... 6 Databases and JDBC drivers... 6 Back end ECM systems... 6 Client-side prerequisites... 7 RECOMMENDATIONS... 8 Ports... 8 URL structure... 8 PREPARING FOR INSTALLATION... 9 Required settings for application server... 9 Deploying on Unix/Linux systems... 9 Configuration files location DEPLOYING MOBILE WORKDESK SERVER Initial deployment Create a Mobile Workdesk Web Archive Application servers Verification of the initial Mobile Workdesk deployment ECM system configuration Activate your own ECM system Redeploy and verify Database connection Configure the datasource Create the database table Redeploy and verify LOGGING Log4j configuration file Log4j and JBoss UPDATING MOBILE WORKDESK SERVER APPENDIX Example for Log4J configuration Background about Log4J iii

4

5 Introduction Besides collaboration centric document challenges there are a lot of process centric business challenges. The goals of automating these processes are increased process efficiency, cost savings, increased customer or employee satisfaction, and achievement of compliance. Many of the analysts also call this Transactional Content Management. Alfresco Workdesk is a purpose-built solution for process centric or transactional content processes. Alfresco Workdesk helps you streamline document centric business processes and cases. With its business role management feature it provides every user group with the right documents in the right business context and in the right application, that can be created by simple configuration rather than coding. Since documents, processes and cases can be accessed via any standard web browser, from within most Office applications and from mobile devices, processes do not stop at the boundary of an enterprise and users are optimally supported in their way of working. Thus processes are accelerated dramatically and compliance is assured. Alfresco Workdesk provides faster time-to-value because it offers state of the art ECM functionality out of the box and makes the creation of customer specific business applications as easy as possible. Productivity enhancing features like dynamic folders, views and actions, which are determined by the user s role in the process allow that the very same document can live in many different views. Hence, Alfresco Workdesk helps your organization to process cases, deals, loans, claims faster and more efficiently. There are 3 modules of Workdesk offering the same functionality on different devices: Alfresco Workdesk - Robust features and flexibility on any web browser Alfresco Office Workdesk - Bypass the browser with seamless desktop integration Alfresco Mobile Workdesk - Mobilize your business processes on ipads and iphones Alfresco Mobile Workdesk Server is the core and back end of the Alfresco Mobile Workdesk ios app. It provides comprehensive business logic and a wide range of productivity enhancing enterprise features. In addition to simple search and browse functions provided by other mobile ECM apps, Mobile Workdesk Server and app allow you to interact with personalized content. For example, there are individual inboxes and tailored views, as well as personal favorites and stored searches. You can participate in workflows and approval processes from a mobile device, and you can edit and annotate documents either directly online or offline. The Mobile Workdesk app gives the business user access to the contents and native functionality of the underlying ECM system(s) in an ergonomic and customizable way, and it introduces a number of additional concepts addressing typical business requirements. Mobile Workdesk provides a flexible solution for your specific business needs, but does not require Objective-C knowledge to customize the server-side. You can customize different flavors of the app by configuring the Mobile Workdesk Server component. The comprehensive role management of Mobile Workdesk Server provides users on their ipad with exactly the specific flavor of the app, including efiles and searches that they need to fulfill their individual business tasks. Also, by using Mobile Workdesk app/server in conjunction with Alfresco Workdesk, this provides a unified working environment with customized applications and views from your desktop computer in the office or ipad on the road. Alfresco Mobile Workdesk

6 About this guide This guide explains how to deploy Mobile Workdesk Server and how to configure the Server. Here is a brief overview of the different sections in this guide. The Prerequisites section discusses the prerequisites, which need to be fulfilled before starting the Mobile Workdesk Server installation process. Making assurance of the fulfillment of these prerequisites will provide you a confidence that you are on the right track. The Recommendations section gives a few recommendations about the ports and the URL structure for the Mobile Workdesk Server deployment. The Preparing for installation section explains the installation process, which includes settings for application servers, operating systems and ECM systems. The Deploying Mobile Workdesk section describes the deployment of Mobile Workdesk Server. The deployment process is split into 3 steps: Deployment of Mobile Workdesk Server using its initial configuration, connecting Mobile Workdesk Server against your own ECM system and connecting Mobile Workdesk Server to a database to store persistent configuration information. After you have finished deploying Mobile Workdesk Server, the Logging section provides recommendations for how to configure the logging Mobile Workdesk Server deployment. The Updating Mobile Workdesk section describes how you can update an existing Mobile Workdesk Server deployment with the latest released version or with fix packs for the current version. Intended audience This document is intended for software professionals whose tasks it will be to install the Mobile Workdesk Server component. Depending on the ECM system you want to run with Mobile Workdesk Server, you need basic skills to administrate the underlying ECM systems and the corresponding CMIS API. Furthermore, it is recommended to be a system administrator and being at least experienced with: deploying web applications (on IBM WebSphere, JBoss, Oracle WebLogic, Apache Tomcat) classpath configurations log4j configuration, reading of log files XML JDBC Connections Web-Applications You must have the authorization to modify and create resources. If you already have an Alfresco Workdesk deployment, you should be familiar with the configuration of that deployment. This is because the Mobile Workdesk Server deployment must use the same datasource as the Alfresco Workdesk deployment to use the DB RoleManager with Mobile Workdesk. 2 Alfresco Mobile Workdesk

7 Typographical conventions used in this guide Convention Important terms Classes Methods Source Code Comments in Source Code Java Package Plugins Path XML Attribute XML value Product-specific terms Example OpenECM-Framework OwAppContext getname() public void mymethod(){} // simple source code comment com.wewebu.server.app com.wewebu.ow.server.plug.owdemo.owmain com/wewebu/ow/server/ <node> value Add Document Formatting legend for brackets in Source Code, Paths, File Names, and so on: Ellipsis (...): Parameter the user must supply Between brackets [ ]: Optional items Between braces { }, choices separated by pipe, example: {even odd}: Set of choices from which the user must choose only one The following placeholders are used in this document: (mobileworkdesk) root directory of Alfresco Mobile Workdesk deployment. (workdesk) root directory of Alfresco Workdesk deployment. (workplace) root directory of IBM FileNet P8Workplace deployment. (WebSphere) installation root of WebSphere application server. (Tomcat) installation root of Tomcat application server. (Jboss) installation root of Jboss application server. Alfresco Mobile Workdesk

8 Abbreviations AE AMWD AOWD AWD CE ECM FNCM IE MS MS Word Office P8 Application Engine Alfresco Mobile Workdesk Alfresco Office Workdesk Alfresco Workdesk Content Engine Enterprise Content Management IBM FileNet P8 Content Manager Internet Explorer Microsoft Microsoft Word Microsoft Office IBM FileNet P8 All trademarks, trade names, registered trademarks, or registered trade names are property of their respective holders. 4 Alfresco Mobile Workdesk

9 Checklist 1. Before starting to deploy Mobile Workdesk 2. Deployment [Section Prerequisites] Fulfill prerequisites? [Section Recommendations] Checked recommendations? [Section Preparing for installation] ECM system prepared? [Section Initial deployment] Initial deployment running? [Section ECM system configuration] Is Mobile Workdesk Server running against your own ECM system? [Section Database connection] Datasource configured? 3. After Mobile Workdesk Server was deployed and you encounter problems [Section Logging] Is the Mobile Workdesk Server application logging mechanism configured? Alfresco Mobile Workdesk

10 Prerequisites Before deploying the Mobile Workdesk Server application, make sure that your infrastructure meets the following prerequisites on the server-side (Server-side prerequisites) and the clientside (Client-side prerequisites). Server-side prerequisites Check the server-side prerequisites before starting the Mobile Workdesk Server installation. Application server As the Mobile Workdesk Server application is based on a web application, an application server is always required. Mobile Workdesk has been successfully tested on several application servers. The following list includes the recommended ones: Jboss Oracle WebLogic IBM WebSphere Apache Tomcat See the official Mobile Workdesk Server Release Notes for a complete list of fully supported application server vendors and versions. If you already have a running Alfresco Workdesk deployment, you must deploy Mobile Workdesk Server on the same application server respectively the same node. Databases and JDBC drivers Mobile Workdesk Server uses a database connection to store persistent configuration data, i.e. to store user permissions for the DB Role Manager. You can configure the DB Role Manager only with Alfresco Workdesk, which already uses a database and has a datasource configured. Therefore, it is not necessary to create a new database and a new table for Mobile Workdesk Server, but only to configure Mobile Workdesk Server to use the same database as Alfresco Workdesk by making the corresponding datasource available to Mobile Workdesk Server on your application server (see Configure the datasource). Back end ECM systems As a prerequisite for any CMIS compliant ECM system Mobile Workdesk Server should connect to, you have to ensure that the CMIS API services of the ECM system are activated and reachable. Versions of ECM systems: See the Release Notes for supported ECM system versions. 6 Alfresco Mobile Workdesk

11 Client-side prerequisites To use the Mobile Workdesk App together with Mobile Workdesk Server on your Apple ipad, you need to download and configure the corresponding Mobile Workdesk ipad App from the Apple App Store. Afterwards, connect to the Mobile Workdesk Server component in the account settings of the App. The Mobile Workdesk App is available in the App Store worldwide and can be found by searching for Alfresco Mobile Workdesk. Alfresco Mobile Workdesk

12 Recommendations Before you actually start deploying Mobile Workdesk Server, take note of the following recommendations. Ports Mobile Workdesk Server does not require any special port or port settings. It can also use Secure Sockets Layer (SSL) to provide secure communication. You have to install a security certificate at your application server. For more information check the help of your specific application server. URL structure For the following sections, the base URL of the installed Mobile Workdesk Server application is referred to as (mobileworkdesk). It is composed of (Protocol)://(Server name)[:(port)]/(context path) Note: (Port) in the URL is required only for non-standard ports and even forbidden for the default ports 80 (HTTP) and 443 (HTTPS). 8 Alfresco Mobile Workdesk

13 Preparing for installation Mobile Workdesk Server may need some special settings on the application server and the underlying ECM system. This section describes these settings. Required settings for application server There are no further settings necessary for Apache Tomcat, IBM WebSphere and Jboss. When using Oracle WebLogic, you cannot work with relative file paths in your configuration files. You have to use absolute file paths. Furthermore, the option deploy# is not possible. For Oracle WebLogic version 10 and higher: MWD Server uses the getrealpath() method to read some configuration files from the file structure of the MWD Server deployment. Therefore, set the WebLogic parameter <show-archived-real-path-enabled> in WebLogic s config.xml to true: <web-app-container> <show-archived-real-path-enabled>true </show-archived-real-path-enabled> </web-app-container> Deploying on Unix/Linux systems When using a Unix/Linux system for the Mobile Workdesk Server deployment, make sure that the access rights (owner) of the deployment files are the same as the access rights of the application server user. This is especially important for an IBM WebSphere application server. When the access rights (owner) for the application server user are set to root, there should not be any problems. Alfresco Mobile Workdesk

14 Configuration files location For all underlying CMIS compliant ECM systems, configuration files like search or virtual folder templates used by Mobile Workdesk server are stored in the file system of the application server. Per default, the required folder structure is stored within the Mobile Workdesk Server deployment at (mobileworkdesk)\web-inf\opencmis\*.* Inside owbootstrap.xml located in (mobileworkdesk)\web-inf\conf\opencmis, this path can be changed by using the <OwApplicationObjectBaseDir> node. If you change the <OwApplicationObjectBaseDir> node, keep in mind to move the whole content and folder structure of (mobileworkdesk)\web-inf\opencmis\*.* to this new location. By default, this folder contains the directories other (containing virtual folder templates), owpreferences (containing user settings) and owsearchtemplates (containing search templates). 10 Alfresco Mobile Workdesk

15 Deploying Mobile Workdesk Server This section describes how to deploy Mobile Workdesk Server by going through each of the deployment steps. The Initial deployment section describes how to deploy Mobile Workdesk Server with its initial delivered configuration (i.e. using a demo IBM FileNet P8 5.x ECM system in the cloud). This configuration allows you to test your Mobile Workdesk Server deployment without using your own back end ECM system. For the description of the deployment procedure, all supported application servers are taken into account and a general verification mechanism is provided to ensure that your first deployment steps were successful. The ECM system configuration section refers to the deployment procedure, when it comes to redeploy Mobile Workdesk Server in advanced configuration, for example, after switching from default demo ECM system in the cloud to your own ECM system. This step also includes a verification mechanism to ensure a correct deployment. The Database connection section describes how to establish a database connection by creating a datasource at the application server side. Mobile Workdesk Server must have a datasource to store persistent information in a database. This step includes the redeploying and verification procedure. Initial deployment This section describes how to create a valid Mobile Workdesk Server web archive (WAR) file and how to deploy this archive in its initial configuration state on several supported application servers. We recommend deploying Mobile Workdesk Server initially without any modifications. After a successful initial deployment of Mobile Workdesk Server, you can continue with the section ECM system configuration, which describes how to modify Mobile Workdesk Server s configuration and redeploy Mobile Workdesk Server with the changed configuration. Alfresco Mobile Workdesk

16 Create a Mobile Workdesk Web Archive Extract the Mobile Workdesk delivery zip file received to a temporary location. Depending on the deployment procedure of your application server, a web archive (WAR) is needed in one of the following modes: Packed Mode: To create a packed WAR file, a Java Development Kit (JDK) has to be installed on your system. For Microsoft Windows operating systems, we provide a batch script called create_mobileworkdesk_war.bat in the \bin directory of the Mobile Workdesk delivery. See the create_war_readme.txt file in the same directory for further information. On other operating systems than Microsoft Windows, you may want to create the web archive file manually by executing a command like jar cf mobileworkdesk.war *. Exploded Mode: The \bin\mobileworkdesk folder in the extracted delivery is already an exploded web archive. For deploying the Mobile Workdesk Server web archive, see one of the following sections for your web application server. Application servers This section describes the most important steps of the Mobile Workdesk Server deployment procedure on different supported application servers. IBM WebSphere On IBM WebSphere application servers, Mobile Workdesk Server has to be deployed as packed web archive (*.war file). Use the WebSphere Server Administration Console to deploy the WAR file. You do not need to change the default settings during the deployment process of WebSphere. After deploying Mobile Workdesk Server, check that all classes are loaded with the application class loader. Normally you can find this option in the WebSphere administration console by navigating through step 1 to 3 like in the following screenshot: 12 Alfresco Mobile Workdesk

17 Select Classes loaded with application class loader first : Oracle WebLogic On Oracle WebLogic application servers, Mobile Workdesk Server has to be deployed as packed web archive (*.war file). Use the WebLogic Administration Console to deploy this file. WebLogic only supports absolute file paths in the Mobile Workdesk Server configuration files like web.xml. Placeholders like deploy# are not supported. For Oracle WebLogic version 10 and higher: Mobile Workdesk Server uses the getrealpath() method to read some configuration files from the Mobile Workdesk Server deployment file structure. Therefore set the WebLogic parameter <show-archived-real-path-enabled> in WebLogic s config.xml to true: <web-app-container> <show-archived-real-path-enabled>true </show-archived-real-path-enabled> </web-app-container> Alfresco Mobile Workdesk

18 JBoss On JBoss application servers, Mobile Workdesk Server has to be deployed as exploded web archive. After copying the \bin\mobileworkdesk folder from the Mobile Workdesk Server delivery to (JBoss)\server\default\deploy, you may rename the folder to your desired application context. Do not forget to append the.war extension to the folder name. An example would be (JBoss)\server\default\deploy\mobileworkdesk.war. JBoss and log4j*.jar: do not deploy log4j*.jar when using JBoss. See Log4j and JBoss for further information. Apache Tomcat On Apache Tomcat, Mobile Workdesk Server can be deployed either as exploded or as packed web archive. After copying the \bin\mobileworkdesk folder respectively the generated mobileworkdesk.war file from the Mobile Workdesk Server delivery to (Tomcat)\webapps, you may rename the created folder to your desired application context. An example would be (Tomcat)\webapps\mobileworkdesk. If you used a generated war file for deploying Mobile Workdesk Server, Apache Tomcat will automatically create an exploded web archive folder after the next server restart. If you are using Alfresco as ECM Repository, Mobile Workdesk Server may not be deployed in the same Apache Tomcat as Alfresco is deployed. Use a separate Apache Tomcat instance. 14 Alfresco Mobile Workdesk

19 Verification of the initial Mobile Workdesk deployment To check whether your initial Mobile Workdesk Server deployment is up and running, open any web browser (for example, Internet Explorer or Mozilla Firefox) and navigate to path). The default value for context path is mwd. If your initial deployment was successful, the following page with a service overview should be displayed after you logged in with a valid user 1 of your ECM system: 1 In the initial configuration of Mobile Workdesk Server the user name is mwdusr and the corresponding password is mwdpwd. Contact your ECM system administrator, if you have connected Mobile Workdesk Server to your own ECM system and you need a valid user now. Alfresco Mobile Workdesk

20 ECM system configuration The Mobile Workdesk Server deployment can be switched from the preconfigured Alfresco ECM system in the cloud to your own CMIS-compliant ECM system by updating the Mobile Workdesk Server configuration in owbootstrap.xml as described in the following section. Activate your own ECM system Before Mobile Workdesk Server is able to access your own ECM system, its configuration file owbootsrap.xml under (mobileworkdesk)/web-inf/conf/opencmis has to be adapted. You have to setup the AtomPub CMIS interface 2 of your CMIS compliant ECM system under the node <EcmAdapter> like in the following example. Example: <EcmAdapter> <ClassName>com.wewebu.ow.server.ecmimpl.opencmis.OwCMISNetwork</ClassName> <Version>4.1.1</Version> <AtomPub> CMIS in combination with Alfresco aspects Since Alfresco Aspects are not part of the CMIS standard and are not completely covered by CMIS, the CMIS adaptor of Mobile Workdesk was extended to provide the information of mandatory aspects during the document creation process. Therefore, the following configuration nodes are provided under <bootstrap>/<ecmadapter>/ node: <AspectRetrieverClass>...</AspectRetrieverClass> Defines a class that is responsible for the information retrieval. It also provides the list of mandatory Aspects Id s of your adaptor. You don't have to activate this line. <AspectRetrieveUrl> An URL that defines the service-location for information retrieval the standard setting is configured to use the Alfresco cloud. If you connect to your local repository (and not the cloud), disable the complete line (for example,for set a comment or remove it) the correct URL will be dynamically built by Mobile Workdesk Server. 2 Contact your ECM system administrator if you do not know how the CMIS API of your ECM system is configured and how to reach the CMIS interface. 16 Alfresco Mobile Workdesk

21 Redeploy and verify To finalize the activation of your own ECM system, Mobile Workdesk Server has to be redeployed. See Initial deployment. Before deploying Mobile Workdesk Server with the new configuration you may have to undeploy the old Mobile Workdesk Server deployment first. Alfresco Mobile Workdesk

22 Database connection The following section describes how to reuse the datasource used by an Alfresco Workdesk deployment. If you don't have an Alfresco Workdesk deployment, you can skip this section. Configure the datasource You must configure the same datasource used by Alfresco Workdesk for the Alfresco Mobile Workdesk Server deployment, as you are configuring parts of Alfresco Mobile Workdesk using the Alfresco Workdesk UI and the underlying database. Therefore copy the <DefaultDataSource> configuration node from owbootsrap.xml under (workdesk)/web- INF/conf/(Adapter) to owbootsrap.xml under (mobileworkdesk)/web- INF/conf/opencmis. If Alfresco Workdesk is using a datasource for MySQL, the <DefaultDataSource> configuration node to be copied may look like the following example: <DefaultDataSource> <JNDIName>java:/MySQLDS</JNDIName> </DefaultDataSource> Create the database table This section describes how to create the required database table in the datasource used by Alfresco Workdesk for the corresponding database vendor/version. IBM DB2 Use the following script to create the required database table in the database configured for and used by Alfresco Workdesk: - (Delivery)\db\scripts\MwDB2_CreateDBRoleManagerTable_Scheme3.sql Microsoft SQL Server Use the following script to create the required database table in the database configured for and used by Alfresco Workdesk: - (Delivery)\db\scripts\MwMSSQL_CreateDBRoleManagerTable_Scheme3.sql Oracle 9i Use the following script to create the required database table in the database configured for and used by Alfresco Workdesk: - (Delivery)\db\scripts\MwOracle_CreateDBRoleManagerTable_Scheme3.sql MySQL Use the following delivered script to create the required database table in the database configured for and used by Alfresco Workdesk: 18 Alfresco Mobile Workdesk

23 - (Delivery)\db\scripts\MwMySQL_CreateDBRoleManagerTable.sql PostgreSQL Use the following delivered script to create the required database table in the database configured for and used by Alfresco Workdesk: - (Delivery)\db\scripts\MwPostgreSQL_CreateDBRoleManagerTable.sql Redeploy and verify To finish the setup of the database connection, Mobile Workdesk Server has to be redeployed. See Initial deployment. A correct database connection can be verified by starting up the Mobile Workdesk Server deployment and checking the corresponding Mobile Workdesk Server log file. If some lines like the following ones appear in the log file (especially the entry with the <DefaultDataSource> element is the most important line), everything seems to work fine and a database connection should be established by Mobile Workdesk Server: [main] DEBUG owd.core [] - OwConfiguration.applicationInitalize: start reading the bootstrap configuration data... [main] DEBUG owd.core [] - OwConfiguration.createJdbcDataSource: Initializing datasource successfully. [main] DEBUG owd.core [] - OwConfiguration.createJdbcDataSource: Initializing Spring Jdbc template successfully done. [main] DEBUG owd.core [] - OwConfiguration.applicationInitalize: DB <DefaultDataSource> of owbootstrap.xml, JNDIName = java:/mssqlds [main] DEBUG owd.core [] - OwConfiguration.applicationInitalize:...reading the bootstrap configuration data finished. Alfresco Mobile Workdesk

24 Logging Mobile Workdesk Server uses log4j for error reporting. By default, only errors are logged to the console. You can modify the reporting/logging level from error to debug and/or write the log into a file by changing the log4j.properties configuration file. If you want to log during the startup/initialization phase of Mobile Workdesk Server, you have to copy the log4j.properties file, for example, from (mobileworkdesk)/web- INF/conf/opencmis to the (mobileworkdesk)/web-inf/classes/ directory. This can be very useful if errors are caused by incorrect configuration of Mobile Workdesk Server (for example, syntax errors in owbootstrap.xml, wrongly configured datasource or missing libraries). Multiple log4j.jar libraries: Make sure that you do not have multiple log4jx.y.z.jar files installed on your application server and in the Mobile Workdesk deployment itself. Log4j configuration file The following text shows an example configuration file for log4j (log4j.properties): # Set root logger level to DEBUG and its only appender to A1. log4j.rootlogger=debug,a1 # A1 is set to be a ConsoleAppender. log4j.appender.a1=org.apache.log4j.consoleappender # A1 uses PatternLayout. log4j.appender.a1.layout=org.apache.log4j.patternlayout # %x inserts the user id to the log file log4j.appender.a1.layout.conversionpattern=%d{iso8601} [%t] %-5p %c [%x] - %m%n # log4j.appender.a1.layout.conversionpattern=%-4r [%t] %-5p %c - %m%n # FileNet P8 log4j.category.com.filenet=warn log4j.category.com.filenet.wcm.api.impl.remotecommand=error # FileNet P8 5.0 log4j.category.filenet_tracing=warn # Apache log4j.category.org.apache=warn # Spring log4j.category.org.springframework=warn 20 Alfresco Mobile Workdesk

25 You can log into a separate log file with the following example of a log4j configuration. In this case, an appender called mwd_file was defined, which logs into a file mwd.log in the root directory of your C drive: # file appender for mwd #log4j.appender.mwd_file=org.apache.log4j.dailyrollingfileappender #log4j.appender.mwd_file.datepattern='.'yyyy-mm-dd log4j.appender.mwd_file =org.apache.log4j.fileappender log4j.appender.mwd_file.file= C:/mwd.log log4j.appender.mwd_file.layout=org.apache.log4j.patternlayout #log4j.appender.mwd_file.layout.conversionpattern=%-4r [%t] %-5p %c %x - %m%n log4j.appender.mwd_file.layout.conversionpattern=%d{iso8601} [%t] %-5p %c - m%n log4j.appender. mwd_file.append=true You can use this appender with the following command line: log4j.rootlogger=debug, mwd_file For further technical background information about log4j see Background about Log4J. Log4j and JBoss JBoss assigns a separate class loader for each deployed application, so that different versions of common libraries do not interfere with each other. But JBoss also uses log4j and has its own version of a log4j library. Therefore, do not deploy an additional log4j-xxx.jar and do not create an additional appender in the log4j configuration file. It is highly recommended to use only the appender that is already present in the global JBoss log4j configuration. Contact your JBoss administrator to configure the global configuration file also for Mobile Workdesk Server. Alfresco Mobile Workdesk

26 Updating Mobile Workdesk Server The following guide gives a brief overview of the tasks to be done when updating to a newer version of Mobile Workdesk Server: See the Release Notes for the new Mobile Workdesk Server version to see what s changed in the new release. Backup your current Mobile Workdesk Server deployment. Copy the new JAR files to (mobileworkdesk)\web-inf\lib. Afterwards, delete the corresponding old JAR files, so that only the new library versions will be deployed. Mobile Workdesk Server libraries are located in the (Delivery)/lib folder of the delivery. Update your configuration: Take the old owbootstrap.xml and transfer the configuration to the new one. You can do this by comparing the old file with the new file, and by checking for new parameters or nodes. Take the old owplugins.xml and transfer the configuration to the new one. You can do this by comparing the old file with the new file, and by checking for new parameters or nodes. Take the old owmimetable.xml and transfer the configuration to the new one. You can do this by comparing the old file with the new file, and by checking for new parameters or nodes. Mobile Workdesk Server should always be downwards compatible. You should always be able to use your old configuration to run a newer version of Mobile Workdesk Server. But if you are using your old configuration files, you may miss new features introduced with a new Mobile Workdesk Server release (see Release Notes). 22 Alfresco Mobile Workdesk

27 Appendix Example for Log4J configuration The following text shows a typical log4j configuration file, which has to be put in the root folder of the directory where your classes are located. The value../yourlogfilefolder/yourlogfile.log represents the location of your logs. <?xml version="1.0" encoding="utf-8"?> <!DOCTYPE log4j:configuration SYSTEM "log4j.dtd"> <!-- ===================================================================== --> <!-- Log4j Configuration --> <!-- --> <!-- On WebSphere this file must be placed in the "web-inf/classes" folder of the deployed application --> <!-- On JBOSS, the.xml-file should be in the following folder: "jboss \server\default\conf" --> <!-- ===================================================================== --> <!-- $Id: log4j.xml,v /05/11 16:33:46 belaban Exp $ --> <!-- For more configuration information and examples see the Jakarta Log4j website: --> <log4j:configuration xmlns:log4j=" <appender name="file" class="org.apache.log4j.dailyrollingfileappender"> <param name="file" value="../yourlogfilefolder/yourlogfile.log"/> <! - True adds entries to an existing log file when starting --> <! - False deletes the existing log file when starting --> <param name="append" value="false"/> <!-- Rollover at midnight each week --> <param name="datepattern" value="'.'yyyy-ww"/> <layout class="org.apache.log4j.patternlayout"> <!-- The default pattern: Date Priority [Category] Message\n --> <param name="conversionpattern" value="%d %-5p [%c] %m%n"/ <!-- The full pattern: Date MS Priority [Category] (Thread:NDC) Message\n <param name="conversionpattern" value="%d %-5r %-5p [%c] (%t:%x) %m%n"/> --> </layout> </appender> <!-- Limit the org.apache category to INFO as its DEBUG is verbose --> <category name="org.apache"> Alfresco Mobile Workdesk

28 <priority value="error"/> </category> <!-- Limit FileNet categories to WARN --> <category name="com.filenet"> <priority value="warn"/> </category> <category name="com.filenet.wcm.api.impl.remotecommand"> <priority value="error"/> </category> <category name="com.wewebu.ow"> <priority value="warn"/> </category> <root> <appender-ref ref="file"/> </root> </log4j:configuration> Background about Log4J There are three main aspects that cause massive problems with log4j on an application server: A java ClassLoader is responsible for loading Classes from their corresponding.class or.jar file. For security reasons, classes with the same name but loaded by different ClassLoaders are treated as different classes. Example: class Foo { } private static Bar x; public setx(newx : Bar); { } x = newx; class Bar {} class BarChild extends Bar {} Imagine some code loaded by ClassLoader1 creates an object of class Foo. So, this class Foo is loaded by ClassLoader1. This ClassLoader will also load the class Bar since it is used by Foo. 24 Alfresco Mobile Workdesk

29 Then some other code loaded by ClassLoader2 creates an object of class BarChild. So, BarChild and Bar will be loaded by ClassLoader2. When this other code tries to call setx(), a ClassMismatchException is thrown. Why? BarChild extends Bar and so you can call setx() with an object of class BarChild, but Bar@ClassLoader1 is different from Bar@ClassLoader2. An application server uses a couple of different ClassLoaders. There is the default Java System Loader, responsible for loading all Classes of the JRE. Next, an application server has some root ClassLoader responsible for loading all classes in the shared libraries folders of the application server (tomcat: common/lib). And there is an extra ClassLoader for each application. This is also done for security reasons. With this design, no class of ApplicationA can be loaded or used by code from ApplicationB. Log4j creates a static logging object used by all applications. Due to 1 and 2, you can get lots of problems depending on where your log4j archives are located. Due to the third point, problems are depending on your application server. If you are using only one log4j instance, you can get into conflict with log4j of your application server. If you have problems with log4j, contact Alfresco Support for assistance. Alfresco Mobile Workdesk