1 Technical Guide Using EMC Documentum with Adobe LiveCycle ES Table of contents 1 Deployment 3 Managing LiveCycle ES development assets in Documentum 5 Developing LiveCycle applications with contents in Documentum 15 Accessing LiveCycle ES processes within Documentum 16 Conclusion Adobe LiveCycle ES Connector for EMC Documentum (the EMC Connector) provides seamless integration between LiveCycle ES solution components and your Documentum system. It enables developers to rapidly and easily develop a content-driven transactional or persuasive application. Examples of those applications include new account opening, invoice processing, and litigation support or industry-specific processes like medical records, mortgage origination, claims processing, or loan approval. By combining the LiveCycle ES technologies and Documentum s capability, you can transform your document-intensive business processes into dynamic interactions that enhance customer service, accelerate transaction cycles, reduce document management costs, maximize the value of your investment in your Documentum system, and improve productivity throughout the enterprise. The EMC Connector enables developers to manage LiveCycle ES design assets, including forms, fragments, images, and other content assets, which are stored in the EMC Documentum system. It enhances the collaboration and increases efficiency when developing a content-centric application by allowing developers to access those assets directly within LiveCycle Workbench ES. The EMC Connector includes service operations to enable LiveCycle ES applications and processes to retrieve content objects, including forms or documents, as well as their content attributes or properties, directly from the Documentum content server. These service operations also enable LiveCycle ES applications and processes to archive contents, such as user submitted form data and converted PDF files, directly into the Documentum content server, with full control of their attributes and relationships with each other. With service operations provided by the EMC Connector, you can flow form data directly into other business processes, enable full-text or index search capabilities through the ECM system, meet regulatory and compliance requirements, and let your end users participate in business processes inside or outside of the Documentum system. This technical guide provides you guidance and tips on how to effectively leverage the capabilities that the LiveCycle ES Connector for EMC Documentum offers to build your content-centric applications. Deployment Typical deployment LiveCycle ES Connector for EMC Documentum is a service component hosted by the LiveCycle service container. Therefore, it is deployed along with other solution components in the same LiveCycle ES server or clustering environment. While LiveCycle ES supports many combinations of operating systems, databases, and application servers, you may want to run EMC Documentum Content Server on a different platform supported by Documentum. The EMC Connector enables you to deploy your systems in a heterogeneous environment where LiveCycle ES and Documentum Content Server run on totally different operating systems, databases, and application servers.
2 Examples: Table 1 shows a few examples of deployment combinations that the EMC Connector supports. Please refer to product documents for LiveCycle ES and EMC Documentum for detailed information on their supported platforms respectively. LiveCycle ES EMC Documentum Content Server Windows 2003/JBoss 4/SQL Server 2005 Windows 2003/DB2 9.1 AIX 5.3/WebSphere 6.1/DB2 9.1 Windows 2003/SQL Server 2005 Red Hat 4.0/JBoss 4/MySQL 5 Solaris 10/Oracle 10.2 Solaris 10/WebLogic 9.2/Oracle 10g Red Hat 4.0/Oracle 10.2 Table 1. Examples of platform combinations between LiveCycle ES and Documentum. User management and authentication LiveCycle ES Connector for EMC Documentum includes an authentication provider service that you can use to authenticate the access of LiveCycle applications, such as Workbench or Workspace, through Documentum user management. With this, end users will have the same login username and password among LiveCycle ES and Documentum. If you have a directory server set up for Documentum, you can let LiveCycle ES synchronize with the same directory server. Examples: In a typical configuration, you will create an enterprise domain in the Domain Management settings of LiveCycle Administration Console. In this domain, you will add a custom authentication provider EMC Documentum Authentication Provider (see Figure 1). You may also want to add the directory server that Documentum uses into the same enterprise domain. You can skip the directory server setup if you have only local users who are not in any directory server and will access LiveCycle ES and Documentum. In this case, you need to make sure that you have the exact same credentials (username and password) for the same user in both LiveCycle ES and Documentum. Once you set up the enterprise domain for Documentum, you can log into LiveCycle Workbench ES, or any other LiveCycle application, to access Documentum repositories. Figure 1. Documentum authentication provider. 2
3 In the configuration setting of the EMC Connector in LiveCycle Administration Console, you must provide a principal credential for the default Documentum repository. You may also add credentials for superusers with other Documentum repositories in the Repository Credentials Settings. The principal credential allows LiveCycle users in the super administrator role to access any Documentum repository even if there is no superuser credential set up for that repository. It is also used as the system credential when LiveCycle services or processes require system access and when the property editor of Content Repository Connector (CRC) operations (see Figure 5 later in this document) gets ECM metadata, such as class types or repositories, from Documentum. Tip: You can log in to Workbench ES and other LiveCycle ES applications two ways. First, you can log in with a username. This gives you access to the default repository, defined in the Configuration Settings. In Workbench, this lets you see the default repository in the Resources view. Another way to log in is to use the format This format enables you to access a specific repository. In Workbench, the Resources view shows the cabinets for that particular repository. Table 2 shows how the login format, authentication provider, and directory server are connected. Login format Credentials used Repository in Resources view or to be accessed Authentication provider required? Directory provider required? LiveCycle super admin user System credential Default repository No No LiveCycle super admin repository1 System credential Repository1 Yes No Local user User credential Default repository Yes No LDAP user User credential Default repository Yes Yes Local User credential Repository1 Yes No LDAP User credential Repository1 Yes Yes Note: The system credential is the principal credential or the repository credential if it is set up in the Repository Credentials Settings. Table 2. Understanding the login format. Managing LiveCycle ES development assets in Documentum LiveCycle ES Connector for EMC Documentum enables developers to access a Documentum repository directly within LiveCycle Workbench ES. This feature is enabled by setting EMC Documentum Repository Provider as your current repository service provider (see Figure 2). Figure 2. Choose the repository provider. 3
4 Once you have done this setup, you can log into Workbench to manage and access your LiveCycle assets in the Documentum repository through the Resources view. Depending on how you log in (see Table 2), the designated Documentum repository is shown under the server name. You can browse all cabinets and content objects within that repository (see Figure 3). Figure 3. Documentum objects shown in Resources view. From here, you can leverage your Documentum repository when you design and develop your LiveCycle ES application. Here are some examples of what you can do: View and edit your form design, which is stored in the Documentum repository, using LiveCycle Form Design perspective. Create and save your form design directly into the Documentum repository. Share your form design with other developers and business owners, abiding by Documentum s access control. Create and use the form fragments library in your Documentum repository. Use content assets, such as images or text, created by non Workbench tools from other members when you design your forms. Access the Documentum repository in the resource picker, which is used in property setup for some variables and service operations (see Figure 4). 4
5 Figure 4. Resource picker shows Documentum contents. Developing LiveCycle applications with contents in Documentum When you are developing an application using LiveCycle and Documentum, you have many choices. Each has its pros and cons. You need to consider several factors in order to decide which one to choose. Build your own integration layer using EMC s Documentum Foundation Classes (DFC) or Documentum Foundation Services (DFS). For example, you can write your own operation and its property editor to be used in LiveCycle Workbench. Another example is that you can write a set of Java APIs or web services to reflect a content transaction by calling DFC or DFS directly. Pros: You will have access to Documentum s API in its lowest granularity level. You can choose to use DFC or DFS. Cons: You must maintain a team who has expertise in both LiveCycle and Documentum. You need to build your own LiveCycle components for Documentum so that you can visually design and configure them during LiveCycle process and application design. Use a repository URL through EMC Documentum Repository Provider. The repository provider is one of the major components in LiveCycle ES Connector for EMC Documentum. It enables developers to use a repository URL (repository ://) to represent the location in Documentum from which a content object is accessed. You can use the provider with or without Content Repository Connector service. Pros: You will be able to use many LiveCycle ES data types, such as xfaform, which inherently use a repository URL as their resource property. You can also leverage fragments in your forms as they are also built to use a repository URL. You can use a repository URL to represent form designs or other contents in some service operations, such as renderpdfform. Cons: You can only access the latest version of forms or contents through the repository URL. You will not be able to access or set properties for those contents stored in the Documentum repository. Use operations in CRC. This is another major component in LiveCycle ES Connector for EMC Documentum. This component provides a set of service operations that you can use in Workbench to integrate Documentum into a LiveCycle process or application. Pros: You have full control over how and what you want to access from the Documentum repository. This includes the versioning, the relationship, content properties, and the authentication option. These operations give developers a visual design and configuration on the content services provided by Documentum. 5
6 Cons: You may not have access to all the Documentum functions you want to use, and you may need to augment your applications with separate DFC or DFS calls. It s worth noting that Repository Provider and CRC do not depend on each other. You can choose to use either or both of them. Using Repository Provider Repository URL syntax If you use EMC Documentum Repository Provider as your current repository provider, you can use a repository URL to access the latest version of documents in the Documentum repository. The root node of the URL path is the name of the Documentum repository. The second level node is the name of the cabinet. The rest of the nodes represent folders and objects. For example: /Samples/DevSample/Forms/SimpleLoanApplication.xdp In this example, the URL points to a content object that has a document named SimpleLoanApplication.xdp. This object is under the Forms folder in the DevSample cabinet of the Samples repository. Workspace ES application Without worrying about how to get the right assets from Documentum, you can quickly build a Workspace application a using repository URL for the needed resources. These resources are stored in a Documentum repository, but developers do not need to worry about the lower level of integration mechanism between LiveCycle and Documentum. Tip: If you follow the Creating Your First LiveCycle ES Application tutorial (www.adobe.com/ support/documentation/en/livecycle), the only additional step needed to make the application work with forms in Documentum is to set the current repository provider to be EMC Documentum Repository Provider. No code change and no recompilation are needed. Content Repository Connector Adobe LiveCycle ES Connector for EMC Documentum includes a set of service operations to enable developers to visually design and configure the Documentum integration within a LiveCycle process or application. These operations are grouped as the Content Repository Connector as shown in the Services view in Workbench (see Figure 5). Figure 5. Service operations in the Content Repository Connector. 6
7 Each service operation has an extensive property editor to enable developers to control and configure different aspects of the operations. Figure 6 shows the property editor for the Store Content operation. Figure 6. Property editor for the Store Content operation. 7
8 Authentication in the service operations You have three authentication choices for each service operation (see Figure 7). Figure 7. Authentication options in the service operation. Use the credential from the LiveCycle process context if this operation is part of a long-lived LiveCycle process and the operation should be subject to access control from Documentum for the owner of the current activity. This is a typical option for CRC operations in a LiveCycle Workspace application. Use the user credential that needs to be input using the username and password fields in the property editor. You may want to use this, for example, when you want all Documentum accesses to be under a single common user representing a system process. Use a Documentum session ticket when you want current activity to be executed under the access control list (ACL) of the current Documentum DFC session. This is a typical option when you call the LiveCycle process through a Documentum client, such as Webtop. This ticket is only valid for a single CRC operation. Therefore multiple CRC operations require multiple DFC session tickets. 8
9 Control of content versions In the Store Content operation, you can specify the versioning behavior (see Figure 8). Figure 8. Versioning options in the Store Content operation. Tip: This operation also maintains the check-out status of the content object. Table 3 describes the different versioning behaviors. Version prior to the operation Checked out prior to the operation Version type Version after the operation Checked out after the operation 1.1 Yes Keep same version 1.1 Yes 1.1 Yes Increment major version 1.1 Yes Increment minor version 2.0 Yes 1.2 Yes 1.1 No Keep same version 1.1 No 1.1 No Increment major version 1.1 No Increment minor version 2.0 No 1.2 No Table 3. Versioning behaviors in CRC operations. 9
10 Accessing and setting values of content properties Using service operations, developers have direct access to the properties of Documentum content objects. You have two ways to access the content properties: Visual mapping shows properties for a class type when you select the repository name in the property editor and select the class type from that repository (see Figure 9). Once you see the list of content properties, you can associate process variables by opening up the XPath Builder when you click the grid in the value column. In this mode, you need to use literal value for both Repository Name and Document Class Type. You can either select from the drop-down list or type in the literal value of the repository name or class type. This mode is best used when the repository and class type are known and predetermined within the application. Figure 9. Visual mapping of content properties.
11 Dynamic mapping enables developers to access and set content properties based on the repository and class type used during the runtime (see Figure 10). It enables developers to build a versatile process for handling a complex logic based on real-time business rules. In this mode, a process variable of the map data type is used to contain the mapping between process variables and content properties. You can use the setvalue operation to construct the mapping dynamically. Figure 10. Dynamic mapping of content properties. Example: Figure 11 shows how to set the value of the CurrentStatus field in an XDP form into the formstatus property of a Documentum content object. The first line sets the value of that form field to a process variable. The second line sets the value of the process variable to the value of a key-value pair in a map variable where the key is the name of the Documentum content object property. It is worth noting that you need to put quotes around the expression This is necessary so that the connector operation can interpret it correctly. This example also shows how you can map an XDP form field to a content object property. Figure 11. Map form field to content property. 11
12 Figure 12 shows how to get the value of the content object property formstatus and set it into the process variable formcurrentstatus. The process variable attributemap is used in the Attribute Name Value Map property of the retrieve content operation. Figure 12. Set value of a content property to a process variable. Associating submitted data to the form design In a typical data capture application, submitted data from a form is stored separately as an XML object in Documentum. This XML object can then be used as part of the Documentum XML application or workflow process. To render the submitted XML data correctly, you need to maintain a proper relationship with the form design. You can use Create Relationship (see Figure 13) to establish the relationship between two Documentum content objects, and you have full control of the versioning behavior of this relationship. The Get Related operation, on the other hand, allows you to get the related documents from the source content object (see Figure 14). Figure 13. Creating a relationship between two content objects. 12
13 Figure 14. Get a list of IDs of the related content objects. Managing PDF attachments In many business applications, users need to send supporting documents or images when submitting the form. In many cases, they are included as PDF attachments in the form. When the form is processed, you may want to store its attachments in Documentum so you can index or search them and manage them properly. This can be done by using a combination of connector service operations. Figure 15 shows a snippet of a process that is handling the submitted form with PDF attachments. Figure 15. Process snippet that handles submitted forms with PDF attachments. 13
14 Figure 16 shows a snippet of process that pulls related attachments from Documentum and sends them along with form data for form services to render. Figure 16. Process snippet to render a form with attachments stored in Documentum. Classifying form data into the appropriate folders Starting with ES Service Pack 1, LiveCycle ES Connector for EMC Documentum introduces a service operation for dynamically creating a folder tree in Documentum (see Figure 17). By combining this service operation with other solution components operations, you can develop a process that stores form data into an appropriate folder based on the value of the data. One business example is when customer requests are sent in, a LiveCycle process can extract the data from the submitted form, store the form data into a regional cabinet based on the zip code that customers filled in on the form, and trigger a process to the right regional call center. Figure 17. Create a folder tree in Documentum. 14
15 Accessing LiveCycle ES processes within Documentum Accessing from Webtop All LiveCycle processes generate, by default, both SOAP and EJB endpoints. You can choose either protocol to call LiveCycle processes from the Webtop application. Example: In a typical data capture application, one would browse to the Webtop folder, open a form, fill it out, and submit it back. The submitted form, then, is archived in the appropriate places inside Documentum. Tip: One way to implement this is to construct two LiveCycle processes render service and submit service. The two processes then are exposed as web services or EJB endpoints. A custom action can be added into Webtop along with new menu items (see Figure 18). This action calls LiveCycle processes for rendering and submitting services, and passes the DFC session information, as well as the form location or other necessary attributes, to the LiveCycle process. Figure 18. A customer Webtop action to call LiveCycle services. Integrating with a Documentum workflow Once the form data is stored in Documentum, you can develop a Documentum workflow to relay it through a review and approval process. Just like the implementation described in the Accessing from Webtop section of this guide, developers can expose LiveCycle processes as web services or EJB endpoints, and call those processes directly from the Documentum workflow. 15
16 Conclusion LiveCycle ES Connector for EMC Documentum provides a unified development experience by extending LiveCycle Workbench ES to access and manage content assets stored in the Documentum content server. Developers can create, modify, and store the forms or other contents in Documentum directly. It makes development collaboration much easier than before. The EMC Connector also includes service operations to help developers build a robust, content-centric application. To provide a rapid development environment, the EMC Connector provides basic content repository services, such as content retrieval, content storage, content relationship, and content properties access, through service operations. Without any coding, developers can easily set and retrieve values between the properties of a Documentum content object and LiveCycle ES assets attributes, such as form fields in LiveCycle Forms ES, control attributes of LiveCycle Reader Extensions ES, or properties of LiveCycle PDF Generator ES. Whether you just want to use Documentum as a content repository or as a platform to host ECM-related applications, LiveCycle ES Connector for EMC Documentum can assist you to quickly build a robust application to enhance the engagement experiences of your end users. Technical guide feedback We welcome your comments. Please send any feedback on this technical guide to Adobe Systems Incorporated 345 Park Avenue San Jose, CA USA Adobe, the Adobe logo, LiveCycle, and Reader are either registered trademarks or trademarks of Adobe Systems Incorporated in the United States and/or other countries. AIX is a trademark of International Business Machines Corporation in the United States, other countries, or both. Windows is either a registered trademark or a trademark of Microsoft Corporation in the United States and/or other countries. Red Hat is a trademark or registered trademark of Red Hat, Inc. in the United States and other countries. Java and Solaris are trademarks or registered trademarks of Sun Microsystems, Inc. in the United States and other countries. All other trademarks are the property of their respective owners Adobe Systems Incorporated. All rights reserved. Printed in the USA /08