EMC Syncplicity Connector for Documentum Installation Guide

Transcription

1 EMC Syncplicity Connector for Documentum Installation Guide EMC Corporation Corporate Headquarters: Hopkinton, MA

2 EMC believes the information in this publication is accurate as of its publication date. The information is subject to change without notice. The information in this publication is provided as is. EMC Corporation makes no representations or warranties of any kind with respect to the information in this publication, and specifically disclaims implied warranties of merchantability or fitness for a particular purpose. Use, copying, and distribution of any EMC software described in this publication requires an applicable software license. For the most up-to-date listing of EMC product names, see EMC Corporation Trademarks on EMC.com. All other trademarks used herein are the property of their respective owners. Copyright 2014 EMC Corporation. All rights reserved.

3 Table of Contents Preface... 5 Chapter 1 Overview... 7 Product Overview... 7 Product Behavior... 8 Installation Overview... 8 Chapter 2 Installing Syncplicity Connector for Documentum Before You Begin Installing on the Content Server Installing on the Application Server When Using Derby as the Database Installing on the Application Server When Using a Database Other Than Derby Configuring Network Proxy Completing the Installation Configuring the Connector Chapter 3 Managing the Syncplicity Connector Managing Sync Frequency Checking the Log Error Messages Managing Repository Folders Managing a C2 Configuration Managing Paused Workflows Managing Network Connections Uninstalling the Syncplicity Connector EMC Syncplicity Connector for Documentum Installation Guide 3

4 Table of Contents 4 EMC Syncplicity Connector for Documentum Installation Guide

5 Preface This guide provides step-by-step procedures for installing the EMC Syncplicity Connector for Documentum. It lists installation prerequisites and provides step-by-step instructions for installing and uninstalling the software. In addition, this manual includes a brief overview of the EMC Syncplicity Connector for Documentum product. Intended Audience This guide is intended for the person who installs and configures system products, often called the system administrator or system operator. It is assumed that the system operator has a basic understanding of the chosen operating system, as well as application server deployment. Revision History This section contains a description of this document s revision history. Revision Date November 2014 March 2013 Description Added information about configuring network proxy, in Configuring Network Proxy, page 18 Initial Publication EMC Syncplicity Connector for Documentum Installation Guide 5

6 Preface 6 EMC Syncplicity Connector for Documentum Installation Guide

7 Overview Chapter 1 Review the sections in this chapter before installing EMC Syncplicity Connector for Documentum. Product Overview The EMC Syncplicity Connector for Documentum is a Cloud offering for synchronizing and sharing files among computers and mobile devices. It does not require users to move files. Synchronization happens automatically in the background. Folders and files under synchronization have a special Syncplicity decorator on the file system, which indicates their synchronization status. The Syncplicity Connector is an application server instance running between Syncplicity and Documentum repositories. It supports one-way publishing from Documentum to Syncplicity only. The Syncplicity Connector publishes contents from Documentum repositories to Syncplicity so that other computers and mobile devices can share the content, and it synchronizes content in the Documentum repositories with Syncplicity. The Syncplicity Connector consists of the following basic components: Connector Engine. This is a web application, packaged as a WAR file, running on an application server, such as Apache Tomcat. The Connector Engine handles Syncplicity folder creation and stores profile and credential information, and it is independent of the underlying repository. Connector Agent for Documentum. The agent acts as a bridge between the Connector Engine and the Documentum repository. It leverages the Documentum Process Integrator (PI) and Process Engine (PE) for this purpose. Each repository must have its own instance of the Connector Agent. The Connector Agent performs the following: Navigates the folder structure on a Documentum repository. Uploads content from a Documentum repository to the engine. Records the synchronization status of each uploaded file and folder in the Documentum repository and syncagentdb. Connector Administrator. The Administrator is a configuration tool that you use to manage the content published from Documentum repositories to Syncplicity. It also allows you to view the Connector log and manage the Connector and Syncplicity accounts. EMC Syncplicity Connector for Documentum Installation Guide 7

8 Overview Product Behavior Before installing the product, be aware of the following product behaviors: The Syncplicity Connector publishes only one content per object. The Syncplicity Connector allows you to specify rules that limit what is published based on file size, object type, and formats (including renditions). The Syncplicity Connector supports publishing the Current version only of a document. Content is removed from Syncplicity should a rendition or size change occur which disqualifies the object based on the filtering rules. If content fails to upload to Syncplicity due to reasons caused by Syncplicity (such as a folder in Syncplicity failed to be created, Syncplicity quota was exceeded, and so on), the previously-published content is not changed. The docbase permissions for the user do not apply in the Connector. The files are read on behalf of dmc_sync_admin user who is a member of dm_read_all group. Therefore, you have read permissions on all the objects regardless of the object level permissions. Syncplicity does not support the virtual document format. Should a virtual document be published to Syncplicity, it is shown as a normal document. The Connector does not support a multi-docbase configuration, where a document link from one docbase folder is created in another docbase folder. Installation Overview The following is a high level overview of the Connector installation procedure. The detailed steps are in the next chapter. Check the system environment and verify all prerequisites, as described in Before You Begin, page 11. Extract the syncagent zip file on the Content Server and run the DarInstaller for each repository. Using DA, set the dm_wfmstimer job to active and schedule it for one minute for each repository. Extract the syncagent zip file on the application server and encrypt a password for the database. In the syncagent WAR file, edit app.properties to configure the connection to the database. In the syncpconfig WAR file, edit dfc.properties to add the various repository values. If using Derby, install and deploy the Derby database. The procedure differs depending on the type of application server. If using Tomcat, copy either derby.war (if using Derby) or syncagent.war (if not using Derby) into $CATALINA_HOME/webapps. If using tcserver, create a tc runtime instance then copy syncagent.war into the instance s webapps folder. If using Weblogic, configure it to allow the Connector to handle the authentication credentials. 8 EMC Syncplicity Connector for Documentum Installation Guide

9 Overview Make sure that the application server is configured for UTF encoding. For the Process Integrator (PI), specify the docbase information in bps_template.xml. Deploy syncagent.war and syncpconfig.war to the application server then start the instance of the application server. Check the URL of the syncagent.war to verify that the installation was successful. If configuring the Connector with Documentum D2, encrypt the Connector account password and edit the D2FS.properties. Configure the Syncplicity Connector Administrator by logging in, entering account information, and creating profiles and folders. EMC Syncplicity Connector for Documentum Installation Guide 9

10 Overview 10 EMC Syncplicity Connector for Documentum Installation Guide

11 Chapter 2 Installing Syncplicity Connector for Documentum This chapter contains the following sections: Before You Begin, page 11 Installing on the Content Server, page 12 Installing on the Application Server When Using Derby as the Database, page 13 Installing on the Application Server When Using a Database Other Than Derby, page 17 Completing the Installation, page 20 Configuring the Connector, page 20 Before You Begin Before you start the installation procedure, review the following items: Review the EMC Syncplicity Connector for Documentum Release Notes to make sure that your environment meets the supported platforms and system requirements. The Connector does not support High Availability (HA) configurations. Make sure that you are not installing the Connector on systems in an HA configuration. Locate each Content Server instance where you plan to install the Connector, and make sure that you have administrator privileges for each. Make sure that the Process Engine (PE) and Process Integrator (PI) are installed and configured for each Content Server instance. Identify the Documentum repositories that you will map to Syncplicity, and make sure that you have an account for each repository. Locate the application servers where you plan to install and configure the Connector credentials and database. The Content Server and application server are not required to be on the same system. Make sure that you have a Syncplicity Enterprise Edition account. It is recommended that the account be dedicated for use by the Syncplicity Connector. If your company uses Single-Sign ON (SSO) in Syncplicity, you must use an account with an application token. EMC Syncplicity Connector for Documentum Installation Guide 11

12 Installing Syncplicity Connector for Documentum Choose a database to use with the Connector. The Derby database is provided with the kit. If you use a different database, make sure that the database is configured for case sensitive collation. If using SSL, it is recommended that you have a version later than 2.0. Installing on the Content Server This procedure describes how to configure the Connector agent for each Documentum repository. 1. Download syncagent-1.0.zip to the Content Server then unzip it. 2. In the resulting directory, unzip DarInstaller.zip. 3. In the resulting directory, run the command: For Windows: darinstall.bat <docbasename> <InstallOwnerName> For Linux:./darinstall.sh <docbasename> <InstallOwnerName> Where <docbasename> is the name of the repository and <InstallOwnerName> is the name of the owner of the repository. The program creates the needed type, objects and process templates in the repository. 4. Repeat the previous step for each repository. 5. Log in to Documentum Administrator (DA) and set dm_wfmstimer to one minute as follows: a. Go to Job Management -> Jobs. b. Search for the job, dm_wfmstimer. Right click and view the properties. c. Make sure the State is set to Active. d. Go to the Schedule tab and make sure that Frequency is set to 1 minute. 12 EMC Syncplicity Connector for Documentum Installation Guide

13 Installing Syncplicity Connector for Documentum e. Repeat this step to set the dm_wfmstimer for each repository. 6. If installing on multiple instances of the Content Server, repeat this procedure for each Content Server. The next step is to install the Connector on the application server. Installing on the Application Server When Using Derby as the Database This procedure describes how to setup credentials and configure the database on an application server. This procedure also contains the steps to install the Derby database. If not using Derby as the database, follow the procedure in Installing on the Application Server When Using a Database Other Than Derby, page If not done already, download syncagent-1.0.zip to the application server and extract it. 2. In the resulting directory which includes syncagent-encryption-<version>.jar, run the following command to encrypt a password for the database: java -cp syncagent-encryption-<version>.jar com.emc.syncplicity.connector.util.encryption.passwordutils <password> Where <password> is a password that you choose. The password is used in the next step to connect to the database. Copy the encrypted value to use in the next step. 3. Configure syncagent.war, which is the Connector Engine, as follows: a. Unpackage the syncagent.war. b. In the WAR file, go to \sync\syncagent\web-inf\classes\ and edit the app.properties file as follows: Set jdbc.username to any name you choose. Set jdbc.password with the encrypted value from step 2. Leave the jdbc.dbschemaname, jdbc.driverclassname, and jdbc.url associated with Derby. For example: jdbc.dbschemaname=dbderbyschema jdbc.driverclassname=org.apache.derby.jdbc.clientdriver jdbc.url=jdbc:derby://localhost:1527/syncagentdb;create=true EMC Syncplicity Connector for Documentum Installation Guide 13

14 Installing Syncplicity Connector for Documentum During the initial startup the database is created using the username and password which are set in app.properties file. That user becomes the database owner. If you manually access the Derby database later on, use the unencrypted version of the password. By default, native Derby authentication is used, which means that all users are stored within the Derby database. Also by default, it is the same database, SyncAgentDB, that is defined in the derby.properties file. If you would like to use a different user to connect to the database, you need to create a new user in Derby, grant the user permissions and define that user in the app.properties file. Also, you can change the password of the database owner using system procedure. Refer to the Derby documentation for details. The Derby database owner password never expires. However, you can define expiration period for regular users with the derby.authentication.native.passwordlifetimemillis property. c. Archive syncagent.war. 4. Unpackage syncpconfig.war, which is the Connector Administrator. Make sure that the dfc.properties file in /WEB-INF/classes has the correct values for the repositories to be shared with Syncplicity, such as the docbroker address and global registry. Afterwards, archive syncpconfig.war. 5. If using Tomcat as the application server, perform the steps given in this procedure: Note: If network proxy exists, then follow the procedure given in Configuring Network Proxy, page 18. a. Create a folder to place the database files then move derby.properties to the new folder. b. Move derby.war into the $CATALINA_HOME/webapps directory. c. Go to the Apache Tomcat x.x folder in the Start Menu then start Configure Tomcat. d. In the opened dialog, go to the Java tab. e. In the Java Options edit box, add the following value: -Dderby.system.home=<yourDerbyDataDirectory> For example: -Dderby.system.home=c:\myData f. Copy the derby.properties into your derby.system.home. g. Add a new service into the Tomcat server.xml (located in /conf folder). For example: <Service name="syncagent"> <Connector port="8090" protocol="http/1.1" connectiontimeout="20000" redirectport="8443" /> <Engine name="catalina" defaulthost="localhost"> <Realm classname="org.apache.catalina.realm.lockoutrealm"> <Realm classname="org.apache.catalina.realm.userdatabaserealm" resourcename="userdatabase"/> </Realm> <Host name="localhost" appbase="webapps2" unpackwars="true" autodeploy="true"> <Valve classname="org.apache.catalina.valves.accesslogvalve" directory="logs" prefix="localhost_access_log." suffix=".txt" pattern="%h %l %u %t %r %s %b" /> </Host> 14 EMC Syncplicity Connector for Documentum Installation Guide

15 Installing Syncplicity Connector for Documentum </Engine> </Service> Make a note of the port number, which you need to log in to the Connector Administrator. h. Make sure that the new service name is placed after the default Service entry, Catalina. It is important that Derby is started before syncagent. i. Create a new service folder (appbase="webapps2" in the example), copy the host-manager and manager folders from the default Tomcat service directory ($CATALINA_HOME/webapps) into the new folder. Make a note of the folder name for later deployment of syncagent.war. j. Make sure that the application server is configured for UTF encoding by setting URIEncoding="UTF-8" as an attribute with the <connector> element within the server.xml configuration. If there are multiple <connector> elements, make sure to change the element used by syncagent.war. TIP: The <connector> element used by syncagent would specify an http port such as If using tcserver as the application server, perform the steps given in this procedure: Note: If network proxy exists, then follow the procedure given in Configuring Network Proxy, page 18. a. Create a folder to place the database files then move derby.properties to the new folder. b. Create a tc runtime instance as described in the VMware documentation. You can use any name you choose when creating the instance. c. Make a copy of the webapps folder in the instance directory and rename it. In the examples for this procedure, the name is webapps2. Make a note of the folder name for later deployment of syncagent.war. d. Place derby.war in the original webapps directory. e. Change server.xml in <yourinstancedir>/conf folder. Initially there is only one Service configured to the webapps folder. You need to add a new service and configure it to use the webapps2 folder. Make sure that port in the Syncplicity Connector is different from the one which was used to create the tc runtime instance. It is 8080 by default. For example: <Service name="syncagent"> <Executor maxthreads="300" minsparethreads="50" name="tomcatthreadpool" nameprefix="tomcat-http--"/> <Engine defaulthost="localhost" name="catalina"> <Realm classname="org.apache.catalina.realm.lockoutrealm"> <Realm classname="org.apache.catalina.realm.userdatabaserealm" resourcename="userdatabase"/> </Realm> <Host appbase="webapps2" autodeploy="true" deployonstartup="true" deployxml="true" name="localhost" unpackwars="true"> <Valve classname="org.apache.catalina.valves.accesslogvalve" directory="logs" pattern="%h %l %u %t "%r" %s %b" EMC Syncplicity Connector for Documentum Installation Guide 15

16 Installing Syncplicity Connector for Documentum prefix="localhost_access_log." suffix=".txt"/> </Host> </Engine> <Connector acceptcount="100" connectiontimeout="20000" executor="tomcatthreadpool" maxkeepaliverequests="15" port="8090" protocol="org.apache.coyote.http11.http11protocol" redirectport="${bio.https.port}"/> </Service> f. Make sure to place the new service name after the default Service entry, Catalina. It is important that Derby is started before syncagent. g. If on a Linux platform, configure the Derby database as follows: Edit the setenv.sh file in <yourinstancedir>/bin directory so that JVM_OPTS also includes -Dderby.system.home=<derby_database_folder>. For example: JVM_OPTS="-Xmx512M -Xss256K -Dderby.system.home=<derby_database_folder>" Where <derby_database_folder> is a full path to the directory where the database files will be located. Copy the derby.properties into your derby.system.home folder. h. If on a Windows platform, configure the Derby database as follows: Add the Java Additional Parameters in the wrapper.conf, which is located in <yourinstancedir>\conf directory. The following example assumes that there already exists a 9 wrapper: wrapper.java.additional.10="-dderby.system.home=<derby_database_folder>" Where <derby_database_folder> is a full path to the directory where the database files will be located. Copy the derby.properties into your derby.system.home folder. i. Make sure that the application server is configured for UTF encoding by setting URIEncoding="UTF-8" as an attribute with the <connector> element within the server.xml configuration. If there are multiple <connector> elements, make sure to change the element used by syncagent.war. TIP: The <connector> element used by syncagent would specify an http port such as If using Weblogic as the application server, configure it to allow the Connector to handle the authentication credentials as follows: a. Open <domain_folder>/config/config.xml. b. Add the following element before the closing tag (</security-configuration>): <enforce-valid-basic-auth-credentials>false</enforce-valid-basic-auth-credentials> c. Disable host verification by editing %DOMAIN_HOME%\bin\setDomainEnv.cmd and adding: -Dweblogic.security.SSL.ignoreHostnameVerification=true d. Make sure that the application server is configured for UTF encoding by setting the webapp.encoding.default application parameter in weblogic-application.xml. 16 EMC Syncplicity Connector for Documentum Installation Guide

17 Installing Syncplicity Connector for Documentum 8. Proceed to Completing the Installation, page 20. Installing on the Application Server When Using a Database Other Than Derby This procedure describes how to setup credentials and configure the database on an application server. 1. If not done already, download syncagent-1.0.zip to the application server and extract it. 2. In the resulting directory which includes syncagent-encryption-<version>.jar, run the following command to encrypt a password for the database: java -cp syncagent-encryption-<version>.jar com.emc.syncplicity.connector.util.encryption.passwordutils <password> Where <password> is a password that you choose. The password is used in the next step to connect to the database. Copy the encrypted value to use in the next step. 3. Configure syncagent.war, which is the Connector Engine, as follows: a. Unpackage the syncagent.war. b. In the WAR file, go to \sync\syncagent\web-inf\classes\ and edit the app.properties file as follows: Set jdbc.username to any name you choose. Set jdbc.password with the encrypted value from step 2. Comment out the jdbc.dbschemaname, jdbc.driverclassname, and jdbc.url associated with Derby. Uncomment the jdbc.dbschemaname, jdbc.driverclassname, and jdbc.url values associated with the desired database. For example, if using Oracle: jdbc.dbschemaname=dboracleschema jdbc.driverclassname=oracle.jdbc.driver.oracledriver jdbc.url=jdbc:oracle:thin:@//localhost:1521/orcl.corp.emc.com For example, if using Microsoft SQL Server: jdbc.dbschemaname=dbmssqlschema jdbc.driverclassname=com.microsoft.sqlserver.jdbc.sqlserverdriver jdbc.url=jdbc:sqlserver://localhost;databasename=sync_test; c. If necessary, change jdbc.url to a value appropriate for your database instance. For example, the url would not include localhost if the database was on a different machine. d. Archive syncagent.war. 4. Unpackage syncpconfig.war, which is the Connector Administrator. Make sure that the dfc.properties file in /WEB-INF/classes has the correct values for the repositories to be shared with Syncplicity, such as the docbroker address and global registry. Afterwards, archive syncpconfig.war. EMC Syncplicity Connector for Documentum Installation Guide 17

18 Installing Syncplicity Connector for Documentum 5. If using Tomcat as the application server, perform the following: Note: If network proxy exists, then follow the procedure given in Configuring Network Proxy, page 18. a. Copy syncagent.war into $CATALINA_HOME/webapps. b. Make sure that the application server is configured for UTF encoding by setting URIEncoding="UTF-8" as an attribute with the <connector> element within the server.xml configuration. If there are multiple <connector> elements, make sure to change the element used by syncagent.war. TIP: The <connector> element used by syncagent would specify an http port such as If using tcserver as the application server, perform the following: Note: If network proxy exists, then follow the procedure given in Configuring Network Proxy, page 18. a. Create a tc runtime instance as described in the VMware documentation. You can use any name you choose when creating the instance. Afterwards, copy syncagent.war into the instance s webapps folder. b. Make sure that the application server is configured for UTF encoding by setting URIEncoding="UTF-8" as an attribute with the <connector> element within the server.xml configuration. If there are multiple <connector> elements, make sure to change the element used by syncagent.war. TIP: The <connector> element used by syncagent would specify an http port such as If using Weblogic as the application server, configure it to allow the Connector to handle the authentication credentials and configure it for UTF encoding as follows: a. Open <domain_folder>/config/config.xml. b. Add the following element before the closing tag (</security-configuration>): <enforce-valid-basic-auth-credentials>false</enforce-valid-basic-auth-credentials> c. Disable host verification by editing %DOMAIN_HOME%\bin\setDomainEnv.cmd and adding: -Dweblogic.security.SSL.ignoreHostnameVerification=true d. Make sure that the application server is configured for UTF encoding by setting the webapp.encoding.default application parameter in weblogic-application.xml. 8. Proceed to Completing the Installation, page 20. Configuring Network Proxy If the Sync Connector application uses proxy, then follow the procedure given in this section. 1. Download the syncagent-1.0.zip file to the application server and extract it. 2. If the proxy has a password, then follow the below procedure, else go to the next step in this procedure. 18 EMC Syncplicity Connector for Documentum Installation Guide

19 Installing Syncplicity Connector for Documentum a. If the directory syncagent-1.0 includes syncagent-encryption-<version>jar, run the following command to encrypt a password for the proxy authentication: java -cp syncagent-encryption- <version>jar com.emc.syncplicity.connector.util.encryption.passwordutils<password> Here, password is a password that you can choose. The password is used in the next step as proxy password. 3. Go to the JMS startup script location in the Content Server (Documentum\jbossX.X. X\server\startMethodServer.cmd) and set the JAVA_OPTS as follows by providing the unencrypted proxy password (if applicable) for <httpproxypassword> and <httpsproxypassword> Add Dhttp.nonProxyHosts if you want proxy to bypass internal urls. For more details, see Example: JAVA_OPTS=%JAVA_OPTS%-Dhttp.proxyHost=<YourhttpProxyhost>-Dhttp. proxyport=<yourhttpproxyport>-dhttps.proxyhost=<yourhttpsproxyhost>-dhttps. proxyport=<httpsproxyport>-dhttp.proxyuser=<httpproxyusername>-dhttp.proxypassword= <httpproxypassword>-dhttps.proxyuser=httpsproxyusername>-dhttps.proxypassword= <httpsproxypassword>-dhttp.nonproxyhosts=<internaldomainurls> 4. If using tomcat zip setup, go to Tomcat\Bin\Catalina.bat and set the JAVA_OPTS as follows by providing the encrypted password (if applicable) for <httpproxypassword> and <httpsproxypassword> Add Dhttp.nonProxyHosts if you want proxy to bypass internal urls. For more details, see Example: JAVA_OPTS=%JAVA_OPTS%-Dhttp.proxyHost=<YourhttpProxyhost>-Dhttp.proxyPort= <YourhttpProxyport>-Dhttps.proxyHost=<YourhttpsProxyHost>-Dhttps.proxyPort= <httpsproxyport>-dhttp.proxyuser=<httpproxyusername>-dhttp.proxypassword= <httpproxypassword>-dhttps.proxyuser=httpsproxyusername>-dhttps.proxypassword= <httpsproxypassword>-dhttp.nonproxyhosts=<internaldomainurls> 5. If using Tomcat Service Installer, then follow steps below: a. Go to the Apache Tomcat x.x folder in the Start menu, and then start Configure Tomcat b. From the window that appears, go to the Java tab. c. In the Java Options edit box, add the following values: -Dhttp.proxyHost=<YourhttpProxyhost> -Dhttp.proxyPort=<YourhttpProxyport> -Dhttps.proxyHost=<YourhttpsProxyHost> -Dhttps.proxyPort=<httpsProxyPort> -Dhttp.proxyUser=<httpProxyUsername> -Dhttp.proxyPassword=<httpProxyPassword> -Dhttps.proxyUser=<httpsProxyUsername> -Dhttps.proxyPassword=<httpsProxyPassword> -Dhttp.nonProxyHosts=<internalDomainUrls> EMC Syncplicity Connector for Documentum Installation Guide 19

20 Installing Syncplicity Connector for Documentum Completing the Installation 1. For the Process Integrator (PI), specify the docbase information in bps_template.xml. Specify dmc_sync_admin as the docbase user for the Connector. If the same PI instance is shared with other applications and there is a need to use a different user for the docbase, make sure that the user has at least RELATE permission on all the process templates installed with the Connector. The process template installed with the Connector is available under the /Connector Processes folder in the docbase. 2. Deploy syncagent.war and syncpconfig.war to the application server by placing it in the appropriate folder configured previously. 3. Start the instance of the application server. If using Derby, you can check its status, the port it uses and manage it using the following URL. If using Tomcat, <port> is the port number used by Tomcat (the default port is 8080). If using tcserver, <port> is the configured port number where derby.war is deployed When startup is complete, go to the URL of syncagent.war. If the installation is successful, the page displays information about the current version of the Syncplicity Connector. 5. If configuring the Connector with Documentum D2, encrypt the Connector account password and edit the D2FS.properties as follows: a. On the application server, go to the directory where you extracted syncagent-1.0.zip and locate syncagent-encryption-<version>.jar. b. Encrypt the Connector password using the following command: java -cp syncagent-encryption-<version>.jar com.emc.syncplicity.connector.util.encryption.passwordutils <password> Where <password> is the password you entered for the Syncplicity Connector Account. c. Using the instructions in the EMC Documentum D2 Version 4.1 Installation Guide, locate the D2FS.properties file and include the encrypted password value. You need to repeat this procedure whenever you change the Syncplicity Connector Account password. 6. Proceed to Configuring the Connector, page 20. Configuring the Connector This section describes how to start the Syncplicity Connector Administrator, configure a Documentum repository to publish its contents to a Syncplicity folder, and change the default Connector password. 1. Enter the following command in your browser to start the Syncplicity Connector Administrator: The <host>:<port> is where you installed syncpconfig.war. If using Derby as the database and Tomcat as the application server, <port> is the Connector port number you defined when you added the service to the Tomcat server.xml. The Syncplicity Connector Sign In window appears. 20 EMC Syncplicity Connector for Documentum Installation Guide

21 Installing Syncplicity Connector for Documentum 2. Enter the Connector URL, which is the URL of the application server where you installed the Connector Engine. For example: The <host>:<port> is where you installed syncagent.war. If logging in to a virtual environment, make sure you use the internal IP address; otherwise, a timeout could occur without an error message or other indication. 3. Enter CEadmin as the user name. To log in to the Administrator for the first time, enter Syncplicity as the password. 4. Once you successfully log in to the Connector, enter the credentials for your Documentum repository. The URL is where the Process Integrator for the Documentum repository was installed. The account must belong to the group dmc_sync_users. Optionally, you can use the Test button to verify the URL. 5. In the Global Settings tab, enter the Syncplicity Service Account information. Once entered, do not change the Syncplicity account user or credential type; otherwise, the Connector will be unable to properly synchronize content between the repository and Syncplicity. 6. In the Global Settings tab, edit the Syncplicity Connector Account and change the password to replace the default password, Syncplicity, which you entered in the first login window. 7. In the Profiles tab, create the profiles you need. The profiles determine what type of content will be published (maximum size, object types, formats and whether renditions are checked for format). For an explanation of how to create a profile, click the Help link and navigate to the Profiles topic. A profile can be associated with one or more folders. 8. In the Folders tab, click New. In the opened dialog box, select a repository folder, enter any name you choose to be the name of the Syncplicity folder and then assign a profile. The Syncplicity folder is created automatically by the Connector. If the repository folder does not have any files that can be published in accordance with the profile, Syncplicity does not create the folder. Repeat this step for every repository folder to be shared with Syncplicity users. EMC Syncplicity Connector for Documentum Installation Guide 21

22 Installing Syncplicity Connector for Documentum 22 EMC Syncplicity Connector for Documentum Installation Guide

23 Chapter 3 Managing the Syncplicity Connector This chapter provides the procedures to manage the Syncplicity Connector. Managing Sync Frequency Sync Frequency is the time for how long the workflow should pause before it starts the next publishing cycle. The allowed values are 1, 5, 15, 30 and 60 minutes. The default is 1 minute. You can change the Sync Frequency setting using the Connector Administrator. The setting is implemented in process template using Post-timers, as described in the Process Builder user guide. Regardless of the Sync Frequency setting, the timer job, dm_wfmstimer, must be kept to 1 minute. Checking the Log To enable the logging, prior to deployment, modify the log4j.xml file within the connector WAR. The file can be found at WEB-INF/classes/log4j.xml within the WAR. Change the level of the com.emc.syncplicity logger from info to debug. This enables all logging statements. By default, the log4j.xml is configured to log only to the console, which is viewable from the Connector Administrator. To log to a file, uncomment the following line within the file: <!-- <appender-ref ref="rollingfile" /> --> It is configured to create a log file named syncagent.log in c:/documentum/logs. You can change the name and location of the file by changing the param name and value for the rollingfile appender in the following line: <param name="file" value="c\:/documentum/logs/syncagent.log" /> Error Messages The following message may appear in the log after logging in to the Connector Administrator: 'DFC_API_W_ATTEMPT_TO_USE_DEPRECATED_CRYPTO_API' If this appears, it means that the DFC global registry password is not using FIPS encryption and that it could be more secure. You do not need to change the password, but you can increase security by EMC Syncplicity Connector for Documentum Installation Guide 23

24 Managing the Syncplicity Connector re-encrypting the password with v7 DFC tools. The password is located in the dfc.properties file in syncpconfig.war. Managing Repository Folders Make sure that those repository folders sharing content with Syncplicity are not moved or deleted. If this occurs, the log will show a paused activity error, such as: :57:36,856 INFO [STDOUT] (http ) :57:36, 856 ERROR [http ] [com.emc.syncplicity.bpm.method.orderfolders.orderfoldersmethod] - null in Process Template: 'Connector Create Folders' - Activity: 'Order folders'. Workitem: '4a003a db' Workflow: 'Create folders; Watch folder - 0b003a Syncpoint ' - '4d003a ' Activity: 'Order folders' - '4c003a b2b' Process: 'Connector Create Folders' - '4b003a b13' Managing a C2 Configuration Dynamic C2 configurations for viewing, printing, and exporting content do not store renditions in the repository, and therefore any content generated by dynamic C2 configurations is not subject to publication by the Syncplicity Connector. For example, when an administrator creates a dynamic export configuration that adds a password to a PDF document, the resulting document is not a stored rendition; it is created on demand for viewing. The Syncplicity Connector does not interact with such a document in any way. Because the Syncplicity Connector and C2 do not interact, publication via the Syncplicity Connector could bypass C2 processing that the configuration normally applies when documents are accessed via D2. Therefore, it is important to ensure that the publishing rules associated with shared folders do not enable synchronization of content which is normally accessible only via C2. Alternatively, the administrator can define a static C2 configuration in D2-Config. This allows users to create renditions using the Create Rendition command. Normally, such renditions have a c2pdf format. Therefore, you can set up the publishing rules for the Syncplicity Connector to only allow publishing of these renditions while excluding the source documents. Managing Paused Workflows Changing the Syncplicity Connector Account password can cause a running workflow to fail with an HTTP 401 error. If this occurs, perform the following: 1. If not done already, on the application server, find the directory where syncagent-encryption- <version>.jar, resides and run the following command to encrypt the Connector password: java -cp syncagent-encryption-<version>.jar com.emc.syncplicity.connector.util.encryption.passwordutils <password> 2. In DA, open the paused task from Inbox. 24 EMC Syncplicity Connector for Documentum Installation Guide

25 Managing the Syncplicity Connector 3. Click the Process Variables tab. 4. Look for process variable name, connector_connection_info and XPath, password. 5. Change the value to the new encrypted password. 6. Rerun the failed task. Managing Network Connections The Connector requires access to the Syncplicity cloud, a database, and Documentum components, including Process Integrator, Content Server, and Java Method Server. This section lists the networks connections used by the Connector and how to test for each connection. The following lists the network connections used by the Connector Administrator (syncpconfig.war): Connector Engine. When logging in, an administrator enters the Connector Engine URL in the first login screen, which generally has the form as described in Configuring the Connector, page 20. From the machine where the Connector Administrator is deployed, open a web browser and enter the Connector Engine URL. A version page should display. Documentum repository. Make sure that the docbroker configured in dfc.properties is accessible. The following lists the network connections used by the Connector Engine (syncagent.war): Database. If using the Derby database, open a web browser on the machine where syncagent.war is installed and enter the URL to Derby, which has the form For other databases, please see your database documentation. Syncplicity cloud REST APIs, which are used to verify Syncplicity credentials and retrieve authentication tokens. The URIs for the APIs used by the Connector Engine are all hosted from The Connector Engine uses the credentials entered into the Connector Administrator to access APIs which require authentication. From the machine where the Connector Engine is installed, open a web browser and enter Process Integrator. This is the URL that an administrator enters into the second login screen of the Connector Administrator. From the machine where the Connector Engine is installed, open a web browser and enter this URL with /versions.jsp appended. For example, if the URL is then use If successful, a screen showing the software version information displays. The following lists the network connections used by the Connector Agent for Documentum (portion running within the Documentum Java Method Server): Connector Engine. This is the URL entered into the first login screen of the Connector Administrator, which generally has the form From the machine where Method Server is installed, open a web browser and enter the Connector Engine URL. A version page should display. Syncplicity cloud REST APIs dealing with synchronization. These set of URIs for the APIs used are hosted from From the machine where Method Server is installed, open a web browser and enter Syncplicity cloud. In your web browser, enter You should see a page with the word, pong. EMC Syncplicity Connector for Documentum Installation Guide 25

26 Managing the Syncplicity Connector Uninstalling the Syncplicity Connector Perform the following to remove the Connector: 1. Use the Connector Administrator to delete all Syncplicity folders. 2. Wait until the Connector agent (workflow processes) has a chance to clean up information in the repository. This should remove the relations containing sync state information. 3. Uninstall syncagent.war and syncpconfig.war by undeploying them from the application server. 4. If Derby was used, uninstall derby.war by undeploying it from the application server. Afterwards, delete the folder created for Derby database storage. 5. Undo the application server configuration changes which were made to support derby.war and syncagent.war. For example, delete the tcserver or Tomcat instance. 6. On the Content Server, perform the following steps for each repository: a. Remove the dmc_sync_admin user using the following DQL statement: DELETE dm_user OBJECTS WHERE user_name= dmc_sync_admin b. Delete all instances of dmc_relation_sync_status using the following DQL statement: DELETE dmc_relation_sync_status OBJECTS c. Drop the dmc_relation_sync_status type using the following DQL statement: DROP TYPE dmc_relation_sync_status d. Remove the dmc_sync_users group using the following DQL statement: Drop Group dmc_sync_users e. Delete the previously created process templates. Note: The following cleanup steps are optional. 7. Perform the following to clean up processes. a. List all the processes: select r_object_id, object_name from dm_process where FOLDER('/Connector Processes', DESCEND) For example: API>?,c,select r_object_id, object_name from dm_process where FOLDER('/Connector Processes', DESCEND) r_object_id object_name b01e ecb Connector Create Folders 4b01e eca Connector delete object 4b01e ecd Connector Delete Syncplicity Objects... b. For a returned process, abort all workflows by uninstalling then reinstalling the process with the option to abort halted workflows. For example: API> uninstall,c,4b01e ecb... OK API> install,c,4b01e ecb,t,f 26 EMC Syncplicity Connector for Documentum Installation Guide

27 Managing the Syncplicity Connector... OK c. List the activities in the process: API>?,c,select r_act_def_id from dm_process where r_object_id = <processid> d. Use the following commands to uninstall, invalidate, and destroy the process and its activities: API>uninstall,c,<processid> API>invalidate,c,<processid> API>destroy,c,<processid> For example: API>?,c,select r_act_def_id from dm_process where r_object_id = '4b01e ecb' r_act_def_id c01e edc 4c01e edb 4c01e eda 4c01e ed9 4c01e ed8 (6 rows affected) API> uninstall,c,4b01e ecb... OK API> invalidate,c,4b01e ecb... OK API> destroy,c,4b01e ecb... OK API> uninstall,c,4c01e edc... OK API> invalidate,c,4c01e edc... OK API> destroy,c,4c01e edc... OK // repeat for rest activities e. Destroy the aborted workflows and orphaned SDT parent objects: Run dm_dmclean job with argument -clean_aborted_wf TRUE and -clean_wf_template TRUE f. Repeat this procedure for all returned processes. 8. Perform the following procedure to clean up each of the following BOF modules, which are installed in the repository: com.emc.syncplicity.bpm.method.createqueueitemonfailuremethod com.emc.syncplicity.bpm.method.doesobjectmetrulesmethod com.emc.syncplicity.bpm.method.orderfolders.orderfoldersmethod com.emc.syncplicity.bpm.method.splitvirtualpathandfilenamemethod com.emc.syncplicity.bpm.method.virtualpathconstructormethod EMC Syncplicity Connector for Documentum Installation Guide 27

28 Managing the Syncplicity Connector ConnectorFuntionsModule GetRenditionDesigntimeModule GetRenditionRuntimeModule HTTPAdvancedOutboundDesignModule HTTPAdvancedOutboundRuntimeModule RemoveDuplicateEntriesModule SyncplicityUploadDesigntimeModule SyncplicityUploadRuntimeModule a. Fetch a module:?,c,select r_object_id, object_name, r_folder_path from dmc_module where object_name='<module object name>' b. For each dmc_module fetched, find all the dmc_jars and then unlink and destroy each of them. API>?,c,select r_object_id, object_name from dmc_jar(all) where FOLDER('/System/Modules/<module object name>') API> unlink,c,<objid>,/system/modules/<module object name>'... OK API> destroy,c,<objid>... OK API> 9. Perform the following procedure to clean up each of the following dm_methods, which are installed in the repository: CreateQueueItemOnFailureMethod DoesObjectMetRulesMethod OrderFoldersMethod SplitVirtualPathAndFileNameMethod VirtualPathConstructorMethod a. For each method, run this command:?,c,select r_object_id, object_name from dmc_module where object_name='<method name>' b. Destroy the dm_method. destroy,c,<object_id> 28 EMC Syncplicity Connector for Documentum Installation Guide