docDocument Lifecycle
download 
Report Transcription
Document Lifecycle
EMC ® Documentum ® for Life Sciences Version 4.0 Administration Guide EMC Corporation Corporate Headquarters Hopkinton, MA 01748-9103 1-508-435-1000 www.EMC.com Legal Notice Copyright © 2012-2016 EMC Corporation. All Rights Reserved. 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. Adobe and Adobe PDF Library are trademarks or registered trademarks of Adobe Systems Inc. in the U.S. and other countries. All other trademarks used herein are the property of their respective owners. Documentation Feedback Your opinion matters. We want to hear from you regarding our product documentation. If you have feedback about how we can make our documentation better or easier to use, please send us your feedback directly at [email protected] Table of Contents Preface Chapter 1 Chapter 2 ................................................................................................................................ 13 Life Sciences Solution Fundamentals ......................................................... 17 Overview ......................................................................................................... 17 Document Domains .......................................................................................... 18 Roles ............................................................................................................... Administrators ............................................................................................. Document Approvers ................................................................................... Document Auditors ...................................................................................... Document Authors ....................................................................................... Document Contributors (for eTMF only) ........................................................ Document Coordinators ................................................................................ Document Quality Organization Approvers (for Q&M only) ........................... Document Readers ....................................................................................... Document Reviewers .................................................................................... Managers (Product, Project, Trial, Study, Regulatory) ...................................... Controlled Printers (for Q&M only) ............................................................... Global External Participants (for eTMF only) .................................................. Inspectors (for eTMF only) ............................................................................ Investigators (for eTMF only) ........................................................................ Solution-Specific User Roles .......................................................................... User Roles in Documentum eTMF ............................................................. Cross-functional User Groups ............................................................... Reporting Groups ................................................................................. Clinical User Groups ............................................................................ External Trial Participant Roles .............................................................. External Trial Participant Groups ........................................................... User Roles in Documentum Q&M.............................................................. Cross-functional User Groups ............................................................... Reporting Groups ................................................................................. User Roles in Documentum R&D............................................................... Cross-functional User Groups ............................................................... Reporting Groups ................................................................................. Clinical User Groups ............................................................................ Non-clinical User Groups ...................................................................... Quality User Groups ............................................................................. Regulatory User Groups ....................................................................... Safety User Groups ............................................................................... Labeling User Groups ........................................................................... User Roles in Documentum SSV ................................................................ Correspondence User Groups................................................................ Cross-functional User Groups ............................................................... Reporting Groups ................................................................................. 20 22 22 23 23 25 25 26 26 27 27 28 29 29 29 30 30 31 32 32 33 34 36 37 37 38 40 41 41 42 42 43 43 44 45 46 47 47 Control Categories ............................................................................................ 48 Customizing D2-Based Solutions ................................................................ 51 Extending D2-Based Life Sciences Solutions ....................................................... 51 3 Table of Contents Chapter 3 Chapter 4 Chapter 5 4 Creating a Custom Application ..................................................................... Modifying or Extending a Base Configuration ................................................ Extending the Base Solution Contexts ............................................................ 52 52 53 Upgrading the Customized Solution .................................................................. Reconciling Extended Base Configurations with Solution Upgrades ................. Merging D2 Configuration XML Files ............................................................ 54 55 55 Best Practices for Team Development with D2 .................................................... 56 Extending Roles ............................................................................................... Creating Custom Roles ................................................................................. Configuring the Property Pages ..................................................................... Configuring Workflows ................................................................................ Configuring Roles (For Q&M Only) ............................................................... 57 57 57 57 58 ............................................................................ Data Model Overview ....................................................................................... Add or Modify Attributes in Existing Solution Types .......................................... Create New Types that Extend from Existing Solution Types ............................... 59 Life Sciences Data Model 59 62 62 ........................................................................................ 65 Standard Solution Implementation of the DIA EDM Reference Model .................. 66 Standard Solution Implementation of the DIA TMF Reference Model .................. 71 Reference Models Standard Solution Implementation of Quality and Manufacturing Document Models ............................................................................................ 72 Extending the Standard Reference Model Implementation (eTMF) ....................... Extending Dictionaries .................................................................................. TMF Zones ............................................................................................... TMF Sections............................................................................................ TMF Artifact Number ............................................................................... TMF Artifact Names ................................................................................. TMF Unique Artifact Names ..................................................................... Extending Taxonomies .................................................................................. TMF Artifacts by Model ............................................................................ TMF Classification by Artifact ................................................................... Creation Profile ............................................................................................ File Plans and File Plan Templates ................................................................. 74 74 74 74 75 75 76 77 77 77 78 78 Implementing a Custom Reference Model (eTMF) .............................................. Dictionaries .................................................................................................. TMF Zones ............................................................................................... TMF Sections............................................................................................ TMF Artifact Number ............................................................................... TMF Artifact Names ................................................................................. TMF Unique Artifact Names ..................................................................... Taxonomies .................................................................................................. TMF Artifacts by Model ............................................................................ TMF Classification by Artifact ................................................................... Creation Profile ............................................................................................ File Plan and File Plan Template .................................................................... 79 79 80 80 81 81 82 82 82 82 83 83 .......................................................................... Management Creation Profiles .......................................................................... Document Creation Profiles .............................................................................. Control Category Definition .............................................................................. Default Values Template ................................................................................... 85 Document Creation Profile 85 86 88 88 Table of Contents Customizing Creation Profiles ........................................................................... Creating a New Creation Profile .................................................................... Changing Creation Profile Properties ............................................................. Changing Creation Properties for an Artifact within an Existing Creation Profile ............................................................................................ Adding Artifacts to an Existing Creation Profile ............................................. Removing Artifacts from an Existing Creation Profile ..................................... Removing or Disabling an Existing Creation Profile ........................................ 90 90 91 File Naming and Versioning .............................................................................. 93 O2 Configuration for PDF and Native Annotations ............................................. 93 ...................................................................................... 95 Overview and Form Types ................................................................................ 95 Creating Custom Registration Form Types ......................................................... 97 Chapter 6 Registration Forms Chapter 7 Attribute Inheritance and Cascading Attribute Rules Chapter 8 91 91 92 92 .................................. 99 Auto-Inherited Attribute Rules .......................................................................... 99 Configuring Auto-Inherited Attribute Rules ..................................................... 100 Configuring Cascading Attribute Rules ............................................................ 106 Extended Attribute Expressions....................................................................... 110 Special Naming Conventions........................................................................... Preconfigured Cascading Attributes Rules ....................................................... 116 116 Using a Custom Attribute Inheritance Rule to Reapply D2 Configurations to Selected Objects ................................................................... 119 Workflows ................................................................................................. Workflow Roles .............................................................................................. 123 123 Workflow Diagrams........................................................................................ For Collaborative Editing (Categories 1 - 3) .................................................. Submit for Review and Approval (Category 1) ............................................. Submit for Approval (Category 1) ................................................................ Submit for Periodic Review (Category 1) ...................................................... Withdraw Document (Category 1) ............................................................... Submit to To Be Read Recipients (Category 1) ............................................... Recall Document (Category 1) ..................................................................... Submit for Review and Approval (Change Request) ..................................... Submit for Approval (Change Request) ........................................................ Submit for Review and Approval (Category 2) ............................................. Submit for Review-Format Approval (Category 2) ........................................ Submit for Approval (Category 2) ................................................................ Expiry Review (Category 2) ......................................................................... Submit for Review (Category 3) ................................................................... Submit for Delegated Approval (Category 3) ................................................ Content Template Approval ........................................................................ 124 125 125 126 127 128 128 129 130 131 131 132 133 134 134 135 136 Configuring Workflows .................................................................................. 136 Assigning Workflows to Artifacts .................................................................... 137 Modifying the Task Outcome Labels ................................................................ Configuring Workflow Messages ..................................................................... 137 138 Changing Workflow Task Performers ............................................................... Updating Workflow Task Performers ........................................................... Reassigning Roles ....................................................................................... Workflow and Non-Workflow Attributes ......................................................... 138 139 139 140 5 Table of Contents Chapter 9 Chapter 10 Chapter 11 6 .................................................................................................. Document Lifecycle ........................................................................................ Document Lifecycle Models ............................................................................ Control Category 1 Documents Lifecycle ...................................................... Control Category 2 Documents Lifecycle ...................................................... Control Category 3 Documents Lifecycle ...................................................... Trial Master File Document Lifecycle ........................................................... Control Category 4 Documents Lifecycle ...................................................... Using Uniqueness Checks to Validate Transition ............................................... Normal States and Pseudo States ..................................................................... Creating or Modifying a New Lifecycle Configuration ...................................... Custom Business Logic Using Lifecycle Actions................................................ Lifecycles ..................................................................................................... Controlled Document Foundation Security Model ............................................ Permissions .................................................................................................... Permissions in Documentum eTMF ............................................................. Permissions in Documentum Q&M .............................................................. Permissions in Documentum R&D and Documentum SSV ............................ Assignment of Control Categories ................................................................... Role-Based Access Control .............................................................................. Ownership of Category 1-3 Documents ............................................................ Folder Security ............................................................................................... TMF Dynamic Role-Based Access Control (eTMF Only) .................................... External User Registration ........................................................................... Security Configuration Tasks 141 141 143 144 144 145 147 148 148 149 149 150 151 151 152 152 155 157 159 161 161 162 162 163 .................................................................................. 165 Auditing Events ............................................................................................. Configuring Audit Events ........................................................................... 165 166 Configuring Search Criteria ............................................................................. 167 Hard Delete (Documentum eTMF)................................................................... Bulk Import-Export (Documentum eTMF) ....................................................... Lifecycle Model for Document Packages ...................................................... Configuring the Bulk Import-Export Spreadsheet ......................................... 167 169 170 171 Configuring Roles and Permissions for External Participants (Documentum eTMF) ..................................................................................... Defining External Trial Participant Roles ...................................................... Defining Permissions for External Participant Roles ...................................... Adding an External Participant Role Example .............................................. Distributed Server Method Processing ............................................................. Enabling Distributed and Multi-threaded Processing .................................... Disabling Parallel Processing for CFD Methods ............................................ 173 174 177 178 181 182 183 Change Request Configurations (LSQM) .......................................................... Disabling Change Request for Category 1 Documents ................................... Disabling Workflows for Change Requests with Non-Current Document Versions Attached ...................................................................... 184 184 Media Files .................................................................................................... D2 Mailing Configurations .............................................................................. Types of Mailing Configurations .................................................................. Configuring Mailing Configurations ............................................................ List of Task Variables .................................................................................. 185 185 185 187 188 184 Table of Contents Chapter 12 Chapter 13 Chapter 14 Chapter 15 Message Configuration ............................................................................... 189 Configuring Session Timeout .......................................................................... 191 Workspaces and Welcome Pages ............................................................. 193 Workspaces .................................................................................................... Workspace Views and Tasks ........................................................................ Workspace Mapping by User Role ............................................................... 193 193 197 Display Labels ................................................................................................ 202 Welcome Pages ............................................................................................... 202 ........................................................................... Submission Overview ..................................................................................... Electronic Common Technical Document Submission ....................................... Regional XML Files for Other Agencies ........................................................ Additional XSL Style Sheets ........................................................................ Submission History XML File .......................................................................... Supporting New eCTD XML Formats .............................................................. XML Schema Configuration Object Settings ................................................. Processing Standard XML Files ....................................................................... Transforming Non-Standard XML Files............................................................ Previewing and Processing eCTD Module 1 Regional XML Files ....................... XML Metadata Extraction ............................................................................... Example 1: US Submission to the FDA ......................................................... Example 2: EU Submission to Multiple EU Countries ................................... Non-eCTD Electronic Submission .................................................................... Submission Filestore ....................................................................................... Configuring the SSV Viewer Widget URLs ....................................................... Processing of PDFs and Inter-Document Hyperlinks ......................................... Study Tagging Files ........................................................................................ Previewing of Media Files ............................................................................... Adding Custom Format Icons ..................................................................... 205 Regulatory Submissions 205 207 207 208 208 208 210 216 218 221 224 226 228 231 231 233 241 242 245 245 Migration and Integrity Check Utilities ..................................................... D2 Configuration Migration Tool ..................................................................... Installing the D2 Configuration Migration Tool............................................. Configuring the D2 Configuration Migration Tool ........................................ 247 247 247 248 TMF Admin Integrity Checking and Repair Tool .............................................. Installing the TMF Admin Tool .................................................................... Examining Access Control Groups............................................................... Checking and Repairing the TMF Security Settings for External Users ............ Refreshing TMF Access Control Groups for Registered External Users ......................................................................................................... Purging and Deleting Specific Groups.......................................................... 249 250 250 251 Life Sciences Source Development Kit ..................................................... Overview ....................................................................................................... 255 255 Web Services Integration ................................................................................. Java Client Library ...................................................................................... 255 256 Supported Functionality in the SDK ................................................................. 256 252 253 7 Table of Contents ....................................... 259 Disabling the dm_bpm_XCPAutoTaskMgmt Job ............................................... 259 Chapter 16 Configuration Settings to Improve Performance Appendix A Configuration Planning Checklist Appendix B Troubleshooting .............................................................. 261 ........................................................................................ Log Files ........................................................................................................ D2 Log Files ............................................................................................... Life Sciences Log Files................................................................................. Underlying Products Log Files .................................................................... Content Transformation Services ............................................................. xPlore ................................................................................................... Content Server ....................................................................................... Thumbnail Server ................................................................................... Java Method Server................................................................................. Third-Party Log Files .................................................................................. eDRG..................................................................................................... Enabling Logging, Debugging, and Tracing ...................................................... Configuring Logging for D2 ........................................................................ Configuring Logging for Underlying Products ............................................. Content Server ....................................................................................... Content Transformation Services ............................................................. xPlore .................................................................................................... Thumbnail Server ................................................................................... Java Method Server................................................................................. Life Sciences SDK ................................................................................... Configuring Logging for Third-Party Products ............................................. Connection Issues ........................................................................................... Submission Viewer Timeout Issue (Documentum SSV) ..................................... Missing Icons in the Submission Viewer (Documentum SSV) ............................ 265 265 266 267 267 267 268 268 268 269 269 269 269 270 270 271 272 273 273 274 274 274 275 275 ...................................... 277 Appendix C DIA EDM and TMF Reference Model Dictionaries Appendix D Visual Representation of Attribute Cascading in Life Sciences 8 265 ................ 283 Table of Contents List of Figures Figure 1. Product and Project Registration Form Attributes ................................................. Figure 2. Cascading of Attributes in the Clinical Domain .................................................... 284 Figure 3. Cascading of Attributes in the Non-clinical Domain .............................................. 285 Figure 4. Cascading of Attributes in the Regulatory Domain ............................................... 286 Figure 5. Cascading of Attributes in the Safety and Quality Domain .................................... 287 284 9 Table of Contents List of Tables Table 1. Document domains .............................................................................................. Table 2. Top-level domain roles .......................................................................................... 21 Table 3. Objects Types for which Users can Create Documents ............................................. 61 Table 4. EDM reference model Quality domain dictionaries ................................................. 67 Table 5. DIA EDM reference model taxonomies .................................................................. 69 Table 6. TMF dictionaries .................................................................................................. 71 Table 7. TMF taxonomies ................................................................................................... 71 Table 8. Taxonomy ............................................................................................................ 73 Table 9. Extending the reference model - TMF Zones ........................................................... 74 Table 10. Extending the reference model - TMF Sections........................................................ 74 Table 11. Table 12. Extending the reference model - TMF Artifact Number ........................................... Extending the reference model - TMF Artifact Names ............................................. 75 75 Table 13. Extending the reference model - Example of multiple unique names ........................ 75 Table 14. Extending the reference model - TMF Unique Artifact Names ................................. 76 Table 15. Table 16. Extending the reference model - TMF Artifacts by Model ........................................ Extending the reference model - TMF Classification by Artifact ............................... 77 77 Table 17. Extending the reference model - sample new artifact............................................... 79 Table 18. Table 19. Management Creation Profiles .............................................................................. Required default values ........................................................................................ 85 89 Table 20. Registration form types ......................................................................................... 96 Table 21. Table 22. Comparisons between D2 inheritance and Auto Inherited Attribute Rules ............... 99 Extended attribute expressions ............................................................................ 111 Table 23. Configuring the Hard Delete feature .................................................................... 168 Table 24. Table 25. Lifecycle model for document packages ............................................................... Object Types for Configuring D2 Mailing ............................................................. 170 186 Table 26. List of Task Variables .......................................................................................... 188 Table 27. Table 28. Workspace views and tasks ................................................................................. Workspace Mapping for eTMF User Roles ............................................................ 193 198 Table 29. Workspace Mapping for Q&M User Roles ............................................................ 199 Table 30. Workspace Mapping for R&D User Roles ............................................................. 200 Table 31. Workspace Mapping for SSV User Roles .............................................................. 201 Table 32. Table 33. Configuration planning checklist ......................................................................... D2 logs on Application Server machine ................................................................ 261 265 Table 34. D2 logs on Content Server machine ..................................................................... 266 Table 35. Clinical domain dictionaries ................................................................................ 277 Table 36. Non-Clinical domain dictionaries ........................................................................ 278 Table 37. Quality domain dictionaries ................................................................................ 279 10 19 Table of Contents Table 38. Regulatory-Admin domain dictionaries ............................................................... 280 Table 39. TMF dictionaries ................................................................................................ 280 11 Table of Contents 12 Preface This guide contains information about administering, configuring, and extending the solutions that are part of the EMC Documentum for Life Sciences solution suite. The Life Sciences solution suite includes the following solutions: • EMC Documentum Electronic Trial Master File (known as Documentum eTMF) • EMC Documentum Quality and Manufacturing (known as Documentum Q&M) • EMC Documentum Research and Development (known as Documentum R&D) • EMC Documentum Submission Storage and Viewing (known as Documentum SSV) Intended Audience This guide is intended for anyone responsible for configuring, extending, or administering any products in the EMC Documentum for Life Sciences solution suite. EMC recommends completion of the following training prior to using this guide: • Technical Fundamentals of Documentum • Composer Fundamentals • D2 Configuration • Life Sciences Fundamentals • Life Sciences Trial Master File (eTMF) Information about these training courses is available on the EMC MyLearn website. Revision History Revision Date Description September 2016 Updated the diagrams in Document Lifecycle Models, page 143. July 2016 Updated the note about duplicate document names in File Naming and Versioning, page 93. 13 Preface Revision Date Description June 2016 Identified the solutions for which the workflows listed in Workflow Diagrams, page 124 are configured. Added a note about duplicate document names in File Naming and Versioning, page 93. April 2016 Added information about disabling the dm_bpm_XCPAutoTaskMgmt job in the Chapter 16, Configuration Settings to Improve Performance. Added a section Change Request Configurations (LSQM), page 184, which provides configuration steps for Change Requests. Updated the Submission Filestore, page 231 section with information about WRITE access required to access the filestore. Added the section, Disabling Parallel Processing for CFD Methods, page 183. Added the section, Configuring Session Timeout, page 191. March 2016 Updated eDRG to AMPLEXOR eDRG. February 2016 Updated the description in Recall Document (Category 1), page 129. Updated ICH DTD version in Supporting New eCTD XML Formats, page 208. October 2015 Updated the section Auto-Inherited Attribute Rules, page 99. September 2015 Added a note about JMS in Processing Standard XML Files, page 216. August 2015 Made a correction in the object model diagram in Data Model Overview, page 59. Added a new section, D2 Mailing Configurations, page 185. Added a new section, O2 Configuration for PDF and Native Annotations, page 93. 14 Preface Revision Date Description July 2015 Added the sections Previewing of Media Files, page 245 and Media Files, page 185. Removed the eDRG URLs from the section Roles, page 20. June 2015 Initial publication. 15 Preface 16 Chapter 1 Life Sciences Solution Fundamentals This chapter contains the following topics: • Overview, page 17 • Document Domains, page 18 • Roles, page 20 • Control Categories, page 48 Overview The EMC Documentum for Life Sciences solution suite (Life Sciences solution suite) helps organizations meet compliance requirements, increase productivity, and securely collaborate across the extended enterprise. The Life Sciences solution suite includes: • EMC Documentum Electronic Trial Master File (Documentum eTMF) • EMC Documentum Quality and Manufacturing (Documentum Q&M) • EMC Documentum Research and Development (Documentum R&D) • EMC Documentum Submission Storage and Viewing (Documentum SSV) The Life Sciences solution suite is built on Documentum D2 and the Documentum platform. Individual solutions rely on reusable components provided by two base layers: • Unified Solution Layer (also referred to as Controlled Document Foundation) • Life Sciences Foundation The following diagram summarizes the architecture: 17 Life Sciences Solution Fundamentals In this architecture, the lower layers have no dependencies on the higher layers. For example, the Life Sciences Foundation components do not depend on any types, configurations, java classes, and so forth defined in the Q&M, eTMF, or R&D solution layers. The Unified Solution Layer components do not depend on any components in the Life Sciences Foundation or specific solution layers. Conversely, dependencies on lower layer components are encouraged. D2 configurations are assigned to one of the following applications corresponding to the layered architecture: • EMC Controlled Document Foundation • EMC Life Sciences Foundation • Documentum Q&M solution • Documentum eTMF solution • Documentum R&D solution • Documentum SSV solution Document Domains Documents stored and managed by EMC Documentum Life Sciences solutions are categorized according to the functional area in which they are used. This top-level categorization is called the document domain. Every document is automatically assigned a domain when it is created. The domain assignment at document creation or import time is accomplished using a D2 Default Values template configuration associated with the creation profile of the document. 18 Life Sciences Solution Fundamentals The standard domains provided with each solution mirror those defined by the DIA Electronic Document Model (EDM) reference model 1.0. The DIA EDM reference model is patterned after the Electronic Common Technical Document (eCTD) standard. The DIA website provides more information about the DIA EDM reference model. The DIA EDM reference model defines the following domains: • Regulatory/Administrative • Quality • Non-Clinical • Clinical These same domains are defined in the Documentum Life Sciences solutions. In addition, the domain concept is extended to encompass other functions beyond those defined in the DIA EDM reference model or strictly related to regulatory submissions. Note: The DIA has not yet published a standard EDM reference model for Quality and Manufacturing document artifacts but the model is currently in development. The document taxonomy in the Documentum Q&M solution is designed in accordance with industry best practice and serves as the foundation from which the DIA standard model is being developed. The following document domains are provided in the respective Document Life Sciences solutions: Table 1. Document domains Solution Domain Name Description Documentum eTMF Clinical TMF Includes documents that are included within a Trial Master File. Documentum R&D Clinical Corresponds to the DIA EDM reference model Clinical domain. Documentum R&D Non-clinical Corresponds to the DIA EDM reference model Non-Clinical domain. Documentum R&D Quality Corresponds to the DIA EDM reference model Quality domain. Documentum R&D Safety Include documents that provide safety information for a drug. Documentum R&D Labeling Include documents that provide labeling information for a drug. Documentum R&D Regulatory /Administrative Corresponds to the DIA EDM reference model Regulatory/Administrative domain. Documentum SSV Correspondence Includes any form of correspondence exchanged between the pharmaceutical companies and the regulatory agencies for a particular submission. Documentum R&D General Includes uncontrolled documents such as letters, memos, and notes. Documentum Q&M Change Request Includes documents used for the purpose of change management. Documentum SSV 19 Life Sciences Solution Fundamentals Solution Domain Name Description Documentum Q&M Good Manufacturing Practices (GMP) (Governance and Procedures) Includes controlled documents relating to organizational directives, policies, and standard operating procedures (SOPs). Documentum Q&M GMP (Manufacturing) Includes documents and records related to the production of marketed products in a GMP environment including methods, specifications, and master batch records. Documentum Q&M GMP (Facility and Organization) Includes certificates, records, and drawings related to a drug manufacturing or packaging facility. Documentum Q&M GMP (Packaging and Labeling) Includes documents relevant to the packaging and labeling of drug product. Documentum Q&M GMP (Validation) Includes documents used in the validation of products, substances, materials, systems, and equipment. Documentum Q&M GMP (Reference and Training) Includes guides, manuals, reference documents, and training materials. Documentum Q&M GMP (Project Documents) Includes project deliverables such as requirements, planning, design, risk assessments, and reports. New document domains can be created to extend the solution to support additional kinds of documents. Creating a new domain requires adding an additional Documentum object type and a set of D2 configurations to support the creation of documents of that type. Note: Documentum Q&M documents all belong to the domain, GMP. However, this domain is further subdivided into categories as noted in parentheses in Table 1, page 19. Roles A role is a type of group that contains users or other groups that are assigned a specific role. Roles provide a means of defining groups that have a particular function within a system. For example, pharmaceutical companies manage their huge set of documentation the assignment of roles such as authors, reviewers, approvers, managers, and so on. Each role can have one or more people designated to perform the activity. Predefined roles are installed with the Life Sciences solutions. Administrators must add users or groups to the applicable predefined roles to ensure each user has an assigned D2 workspace and appropriate access to documents and functions. A set of roles are provided for each of the following domains: • Clinical • Non-Clinical • Quality 20 Life Sciences Solution Fundamentals • Regulatory/Administration • Safety • Labeling • Correspondence • GMP In addition, the Documentum Q&M (GMP) solution roles are assigned by Applicable Sites. Applicable Sites are defined in a dictionary and can be determined by physical manufacturing location and/or business groups. The Configuring Roles (For Q&M Only), page 58 section provides the steps to configure site-based roles. All roles are installed for all solutions. However, some roles are typically used only in a particular solution. The naming convention used for the group name for each role in the Documentum R&D solution is cd_<domain>_<role>. For example, the group name for the Author role in the Clinical domain is cd_clinical_author. The naming convention used for the group name for each role in the Documentum Q&M solution is cd_<applicable_site>_<role>. For example, the group name for the Document Coordinator role for the Boston site is cd_boston _coordinators. Some roles have default members. For example Document Coordinators are members of the Document Authors role. A top-level role for each domain is also installed. All domain roles are made members of the top-level domain role as shown in the following table. Table 2. Top-level domain roles Role Group Name Contains cd_clinical Users of Clinical documents. Users are able to access the Clinical domain documents and at least have READ permission on the same. cd_non_clinical Users of Non-clinical documents. Users are able to access the Non-clinical domain documents and at least have READ permission on the documents. cd_quality Users of Quality documents. Users in this role are able to access the Quality domain documents and at least have READ permission on the documents. cd_regulatory User of Regulatory documents. Users in this role are able to access the Regulatory domain documents and at least have READ permission on the documents. cd_gmp_all_users Users of GMP documents. cd_safety Users of Safety documents. Users in this role are able to access the Safety domain documents and at least have READ permission on the documents. 21 Life Sciences Solution Fundamentals Role Group Name Contains cd_labelling Users of Labeling documents. Users in this role are able to access the Labeling domain documents and at least have READ permission on the documents. cd_correspondence Users of Correspondence documents. Users in this role are able to access the correspondence domain documents and at least have READ permission on the documents. The predefined roles are described in the following sections. Administrators Administrators have the ability to modify most D2 dictionaries and taxonomies as well as other configuration objects, including Auto Inheritance Config and Delete Config objects. Group name cd_admingroup Contains members <none> Is a member of <none> Document Approvers Document Approvers are responsible for approving controlled documents. They perform the For Approval task in a controlled document workflow. Group name cd_clinical_doc_approvers cd_clinical_template_approvers cd_non_clinical_doc_approvers cd_non_clinical_tem_approvers cd_quality_doc_approvers cd_quality_template_approvers cd_gmp_approvers cd_regulatory_doc_approvers cd_regulatory_template_approvers cd_safety_doc_approvers cd_safety_template_approvers cd_labeling_doc_approvers 22 Life Sciences Solution Fundamentals cd_labeling_template_approvers cd_ correspondence_doc_approvers cd_ correspondence_template_approvers cd_general_template_approvers Contains members cd_admingroup Is a member of cd_<domain> (Documentum R&D, Documentum eTMF, Documentum SSV) cd_gmp_all_users (Documentum Q&M) Document Auditors Document Auditors inspect the state of documents in their respective domain for audit-readiness. Document Auditors have read-only access to Effective/Final/Released, Superseded, and Expired documents and no access to documents in other states. Group name cd_clinical_doc_auditors cd_non_clinical_doc_auditors cd_quality_doc_auditors cd_gmp_auditors cd_regulatory_doc_auditors cd_safety_doc_auditors cd_ correspondence_doc_auditors cd_labeling_doc_auditors Contains members cd_admingroup Is a member of cd_<domain> (Documentum R&D, Documentum eTMF, Documentum SSV) cd_gmp_all_users (Documentum Q&M) Document Authors Document Authors create documents and submit them for collaborative editing, review, and approval. They can self-approve documents that do not require formal review and approval. 23 Life Sciences Solution Fundamentals Group name cd_clinical_doc_authors cd_clinical_doc_authors_tmf cd_clinical_template_authors cd_general_doc_authors cd_non_clinical_doc_authors cd_non_clinical_template_authors cd_quality_doc_authors cd_quality_template_authors cd_gmp_authors cd_gmp_template_authors cd_regulatory_doc_authors cd_regulatory_template_authors cd_safety_doc_authors cd_safety_template_authors cd_correspondence_doc_authors cd_ correspondence_template_authors cd_labeling_doc_authors cd_labeling_template_authors cd_general_template_authors Contains members cd_<domain>_doc_coordinators cd_admingroup cd_regulatory_managers cd_regulatory_publisher Is a member of cd_<domain> (Documentum R&D, Documentum eTMF, Documentum SSV) cd_general_doc_authors (Documentum R&D, Documentum eTMF) cd_gmp_all_users (Documentum Q&M) Note: The cd_general_doc_authors role is not a member of any Document Coordinators role because there is no corresponding Document Coordinators role for the General domain. 24 Life Sciences Solution Fundamentals All domain Authors roles except the cd_general_doc_authors role, are members of the cd_general_doc_authors role. This enables authors in all roles the ability to create General documents. Documentum Q&M does not use cd_general_doc_authors role. Document Contributors (for eTMF only) Document Contributors upload files that originated outside of the Documentum repository to a Trial Master File (TMF) within a Documentum repository. Group name cd_clinical_doc_contributors tmf_contributors tmf_external_contributors Contains members tmf_investigators tmf_inspectors tmf_external_contributors tmf_external_reviewers Is a member of cd_clinical Document Coordinators Document Coordinators manage the release of controlled documents. They can also create documents and submit them for collaborative editing, review, and approval. Document Coordinators monitor the progress of document workflow tasks. They can change workflow task performers and stop the workflows. Group name cd_clinical_doc_coordinators cd_non_clinical_doc_coordinators cd_quality_doc_coordinators cd_gmp_coordinators cd_regulatory_doc_coordinators cd_correspondence_doc_coordinators cd_labeling_doc_coordinators cd_safety_doc_coordinators Contains members cd_product_managers cd_admingroup 25 Life Sciences Solution Fundamentals cd_non_clinical_study_managers Is a member of cd_<domain> (Documentum R&D, Documentum eTMF, Documentum SSV) cd_<domain>_authors (Documentum R&D, Documentum eTMF) cd_gmp_all_users (Documentum Q&M) Document Quality Organization Approvers (for Q&M only) Quality Organization (QO) Approvers perform the second-level of approval for controlled documents that require two-levels of approval. Group name cd_gmp_qo_approvers Contains members cd_admingroup Is a member of cd_gmp_all_users (Documentum Q&M) Document Readers Document Readers have read-only access to Effective versions of documents. They browse for, search, and read documents. Group name cd_clinical_doc_readers cd_non_clinical_doc_readers cd_quality_doc_readers cd_gmp_readers cd_regulatory_doc_readers cd_safety_doc_readers cd_labeling_doc_readers cd_correspondence_doc_readers Contains members cd_admingroup cd_regulatory_managers 26 Life Sciences Solution Fundamentals cd_regulatory_publisher Is a member of cd_<domain> (Documentum R&D, Documentum eTMF, Documentum SSV) cd_gmp_all_users (Documentum Q&M) Document Reviewers Document Reviewers review documents and edit documents using annotations. They are responsible for technical reviews during the authoring and review cycle. Reviewers complete workflow tasks and can browse and search for documents. Group name cd_clinical_doc_reviewers cd_non_clinical_doc_reviewers cd_quality_doc_reviewers cd_gmp_reviewers cd_regulatory_doc_reviewers cd_safety_doc_reviewers cd_correspondence_doc_reviewers cd_labeling_doc_reviewers tmf_external_reviewers Contains members cd_admingroup cd_regulatory_managers Is a member of cd_<domain> (Documentum R&D, Documentum eTMF, Documentum SSV) cd_gmp_all_users (Documentum Q&M) Managers (Product, Project, Trial, Study, Regulatory) Managers manage the documentation for their respective domains. They create and manage the registration forms that users use to import and create documents. They also monitor document progress. Product Managers are responsible for all documents across the regulatory applications, non-clinical studies, clinical trials, and quality projects associated with particular products. They create and manage Product Registration Forms. 27 Life Sciences Solution Fundamentals Group name cd_clinical_trial_managers cd_non_clinical_study_managers cd_product_managers cd_quality_project_managers cd_regulatory_managers cd_regulatory_activity_managers cd_correspondence_managers cd_labeling_managers cd_safety_project_managers Contains members cd_admingroup cd_product_registration_group cd_project_registration_group Is a member of cd_<domain> cd_<domain>_doc_coordinators Note: Because the cd_product_managers role spans multiple domains, this role is a member of the following roles: • cd_clinical_doc_coordinators • cd_non_clinical_doc_coordinators • cd_quality_doc_coordinators • cd_regulatory_doc_coordinators Controlled Printers (for Q&M only) The Controlled Printers group is responsible for printing controlled documents. If a user is not a member of the print managers group, a request can be made to a user in the Controlled Printers group for printing a document. Group name cd_controlled_printers Contains members cd_admingroup cd_gmp_coordinators Is a member of 28 <none> Life Sciences Solution Fundamentals Global External Participants (for eTMF only) The Global External Participants group includes external participants in a clinical study who at least have READ access to the document. Group name tmf_global_external_participants Contains members <none> Is a member of cd_<domain> (Documentum eTMF) Inspectors (for eTMF only) Document Inspectors are the users who can inspect the TMF documents uploaded to a placeholder that they have access to. Group name tmf_inspectors Contains members <none> Is a member of cd_<domain> (Documentum eTMF) Investigators (for eTMF only) TMF Investigators are the users who can import the TMF document for a placeholder of particular site, country, or trial but cannot make it Effective/Approved/Final. Group name tmf_investigators Contains members <none> Is a member of cd_<domain> (Documentum eTMF) 29 Life Sciences Solution Fundamentals Solution-Specific User Roles This section lists the defined user roles for each Life Sciences solution. User Roles in Documentum eTMF Documentum eTMF provides defined user roles that enable or restrict user access to documents and information in the system. The following table describes the user roles: User Role Groups Description Managers cd_product_managers Create and manage registration forms for each domain. For example, the Clinical Trial Managers create clinical trial, country, and site registration forms. Clinical Trial Managers also set up and maintain the file plan for a trial. cd_clinical_trial_managers Contributors cd_clinical_doc_contributors tmf_contributors Authors cd_clinical_doc_authors cd_clinical_doc_authors_tmf cd_clinical_template_authors Import and index Trial Master File (TMF) documents. TMF Contributors are able to perform inspection, reviewing, and importing of TMF documents for placeholders that they have access to. Create documents and submit them for collaborative editing and review. Authors can also import documents like the Contributors. Authors can self-approve most TMF documents. Template Authors create and manage clinical template documents. Users in the cd_clinical_doc_authors_tmf group can import Clinical files to the repository but do not author new documents. For example external TMF Investigators and external Authors belong in this role. Document Coordinators cd_clinical_doc_coordinators Manage the publication of controlled documents. Authors can act as Document Coordinators on most TMF documents. Reviewers cd_clinical_doc_reviewers Review documents using annotations and edit documents. Approvers cd_clinical_doc_approvers Responsible for approving controlled documents. cd_clinical_template_approvers 30 Life Sciences Solution Fundamentals User Role Groups Description Auditors cd_clinical_doc_auditors Have read-only access to audit logs as well as Effective/Approved/Final, Superseded, and Expired documents. Readers cd_clinical_doc_readers Have read-only access to Effective /Approved/Final versions and are considered general consumers. Investigator* tmf_investigators Clinical investigators who administer the drug or therapy to subjects (patients or volunteers) and record clinical data on each subject. Investigators typically act as contributors to the TMF. Inspector* tmf_inspectors Health authority or regulatory agency representatives who may audit a clinical trial. Inspectors are typically given read-access to Effective/Approved/Final documents in the TMF. External Contributor* tmf_external_contributors Produces documents or imports eTMF documents. For example, a member of a Contract Research Organization. External Reviewer* tmf_external_reviewers Peer reviews or participates in collaborating on documents. For example, an expert in the relevant field of medicine. Administrator cd_admingroup Accesses administrative functions but does not have access to controlled documents. *These roles are external participants. They can receive access to documents associated with a country or site. The use of the term external does not require the user to be a contractor or otherwise external to the system. It means that they do not have global access to all documents in the system and only have access to what managers specifically grant to them. Managers can grant the access for a limited time. External Trial Participant Roles, page 33 provides more information. Cross-functional User Groups The following table describes the cross-functional user groups: Groups Description cd_admingroup Administrator: • Access to administrative functions • Require Administrative client capability • Do not have access to controlled documents 31 Life Sciences Solution Fundamentals Groups Description cd_product_managers Product managers who create Product Registration Forms. cd_general_doc_authors Users in the role can create general documents (letter, memos, notes). By default, all other authors groups are members of the cd_general_doc_authors role. Reporting Groups Documentum eTMF provides an optional reporting feature for monitoring active clinical trials based on eDRG. The reports can be customized using the AMPLEXOR euroscript Documentum Report Generator (eDRG). The EMC Documentum for Life Sciences Reports Guide provides more information. In Documentum D2, users view dashboards containing report information. The following table describes the reporting groups used by the Report Generator: Groups Description report_user Report Users can generate reports and view historical data in the form of saved reports. report_builder Report Builders can manage report definitions and presentations. report_administrator Report Administrators can define categories and scheduling of reports. Clinical User Groups Use the clinical user groups for clinical and clinical trial documents. The following table describes the clinical user groups: Groups Description cd_clinical Contains all of the other cd_clinical_* groups as members. So if a user is in one of the groups in this table, they are automatically part of this group. Users should not be added directly to cd_clinical. cd_clinical_doc_approvers Clinical document approvers cd_clinical_template_approvers cd_clinical_doc_auditors 32 Clinical document auditors Life Sciences Solution Fundamentals Groups Description cd_clinical_doc_authors Clinical document authors cd_clinical_doc_authors_tmf cd_clinical_template_authors cd_clinical_doc_contributors Clinical document contributors who import files to a Trial Master File (TMF), but unlike authors, they do not author new documents from templates in the system. cd_clinical_doc_readers Clinical document readers cd_clinical_doc_reviewers Clinical document reviewers cd_clinical_trial_managers Clinical trial managers who create Clinical Trial, Country, and Site Registration Forms. External Trial Participant Roles Documentum eTMF enables you to add a named user to participate as a particular role within the eTMF system. These users, known as external participants, can receive access to a countries or sites. External participants only have access to the documents associated with the entity granted. Administrators specify document access levels when configuring the user roles. The EMC Documentum for Life Sciences Installation Guide provides more information. External trial participants require a Documentum user account (dm_user) for system access. Note: The use of the term external does not require the user to be a contractor or otherwise external to the system. It means that they do not have global access to all documents in the system and only have access to what managers specifically grant to them. Managers can register external participants for countries and sites to grant access for the specified entities. They register the external participants by adding them to the relevant site or country registration forms. By default, users who have Write access to the registration form can add external trial participants. The Access Control tab of a registration form defines the users who can update the form. For example, a clinical trial manager or a local site administrator delegated to act in this role can add external participants to registration forms. These participants receive the access specified in the registration form. The following table describes the default external participant roles: Role Description Investigator A clinical investigator responsible for administering the drug or therapy to subjects (patients or volunteers) and recording clinical data on each subject. Inspector A representative of the health authority or regulatory agency responsible for ensuring that good clinical practice is followed during the conduct of the trial. 33 Life Sciences Solution Fundamentals Role Description External Contributor A producer of specific documents or a person who can typically import eTMF documents. For example, a member of a Contract Research Organization. External Reviewer A peer reviewer or participant of specific documents. For example, an expert in the relevant field of medicine. External Trial Participant Groups The system creates user groups for providing document access to external trial participants. The following table describes the external trial participant user groups: Groups Description tmf_global_external_participants Provides access rights common to all external participants. This group is a Trial Master File (tmf) group. tmf_contributors Provides read-only and browse access to the top-level Clinical cabinet and product folders. All clinical trial participants belong to this group indirectly. tmf_external_contributors Assigns a workspace to the External Contributors. tmf_external_reviewers Assigns a workspace to the External Reviewers. tmf_inspectors Assigns a workspace to the Inspectors. tmf_investigators Assigns a workspace to the Investigators. pg_<product-code> Provides Read access to the product-level folders. (Product group) tg_<trial-ID> (Trial group) cg_<trial-ID>_<country-code> (Country group) sg_<site-ID> (Site group) Provides Read access to the top-level TMF folder for the trial. Provides Read access to the top-level country folder for the trial. Provides Read access to the top-level site folder for the trial. Each external trial participant user group is further divided into subgroups for roles with the following suffixes: • Investigator: _inv • Inspector: _insp 34 Life Sciences Solution Fundamentals • External Contributor: _contrib • External Reviewer: _rev For example, for Product XYZ, Trial 1234, Country cc, and Site ccnnnnnn, the system creates the following groups and subgroups: • pg_XYZ — PG_XYZ_inv — PG_XYZ_insp — PG_XYZ_contrib — PG_XYZ_rev • tg_1234 — tg_1234_inv — tg_1234_insp — tg_1234_contrib — tg_1234_rev • cg_1234_cc — cg_1234_cc_inv — cg_1234_cc_insp — cg_1234_cc_contrib — tcg_1234_cc_rev • sg_ccnnnnnn — sg_ccnnnnnn_inv — sg_ccnnnnnn_insp — sg_ccnnnnnn_contrib — sg_ccnnnnnn_rev Note: You should not directly add users to these groups. The system automatically populates these groups when you select Manage External Participants. 35 Life Sciences Solution Fundamentals User Roles in Documentum Q&M Documentum Q&M provides defined user roles that enable or restrict user access to documents and information in the system. The following table describes the user roles: User Role Groups Description Administrators cd_admingroup Access administrative functions but do not have access to controlled documents. Approvers cd_<applicable site>_approvers Approve controlled documents (Control Category 1 and 2). Some documents require electronic signatures. cd_gmp_template_approvers Auditors cd_<applicable site>_auditors Have read-only access to audit logs, Effective/Approved/Final, Superseded, and Expired documents. They can view document content, history, and properties. They must have a minimum extended privilege of View Audit. Authors cd_<applicable site>_authors cd_gmp_template_authors Create documents and submit them for collaborative editing, review, and approval. • Control Categories 1 and 2: Authors cannot be an Approver. • Control Category 3: Authors can approve documents and act as Document Coordinators. Document Coordinators cd_<applicable site>_coordinators Manage the release of controlled documents. • Control Category 1: Schedules release dates. Verifies that all members of the To Be Read (TBR) Distribution List have signed off on a document or rejected the task in the Submit to To Be Read recipients workflow before the document becomes Effective/Approved/Final. • Control Categories 1 and 2: Releases documents to an Effective/Approved/Final state and controls the long-term management of the document. Can submit a document to a workflow. • Control Category 3: Authors can act as Document Coordinators. 36 Life Sciences Solution Fundamentals User Role Groups Description Quality Organization Approvers cd_<applicable site>_qo _approvers Responsible for final approval of Control Category 1 documents. Readers cd_<applicable site>_readers General consumers with read-only access to Effective/Approved/Final versions. (Optional) Recipients on the To be Read (TBR) Distribution List receive notification when a Control Category 1 document is scheduled to become Effective. They confirm that they have read the document. When a Reader requests a printable PDF, the system adds them to the TBR Distribution List. Typically, PDFs are secure and do not allow local printing, editing, or annotation. Reviewers cd_<applicable site>_reviewers Review documents using annotations and edit documents. They are responsible for technical review during the authoring and review cycle. Documentum Q&M includes these defined user groups: • Cross-functional User Groups, page 47 • Reporting Groups, page 47 Cross-functional User Groups The following table describes the cross-functional user groups: Groups Description cd_admingroup Administrator: • Access to administrative functions • Require Administrative client capability • Do not have access to controlled documents Reporting Groups Documentum Q&M provides an optional reporting feature for monitoring active clinical trials based on eDRG. The reports can be customized using eDRG. The EMC Documentum for Life Sciences Reports Guide provides more information. In D2, users view dashboards containing report information. The following table describes the reporting groups used by the Report Generator: 37 Life Sciences Solution Fundamentals Groups Description report_user Report Users can generate reports and view historical data in the form of saved reports. report_builder Report Builders can manage report definitions and presentations. report_administrator Report Administrators can define categories and scheduling of reports. User Roles in Documentum R&D Documentum R&D provides defined user roles that enable or restrict user access to documents and information in the system. The following table describes the user roles: User Role Groups Description Approvers cd_regulatory_doc_approvers Approve controlled documents. Some documents require electronic signatures. cd_quality_doc_approvers cd_clinical_doc_approvers cd_non_clinical_doc_approvers cd_safety_doc_approvers cd_labeling_doc_approvers cd_<domain>_template _approvers Auditors cd_regulatory_doc_auditors cd_quality_doc_auditors cd_clinical_doc_auditors cd_non_clinical_doc_auditors cd_safety_doc_auditors cd_labeling_doc_auditors 38 Have read-only access to audit logs, Approved, and Superseded documents. They can view document content, history, and properties. They must have a minimum extended privilege of View Audit. Life Sciences Solution Fundamentals User Role Groups Description Authors cd_regulatory_doc_authors Create documents and submit them for collaborative editing, review, and approval. cd_quality_doc_authors cd_clinical_doc_authors cd_non_clinical_doc_authors cd_safety_doc_authors • Control Categories 2: Authors cannot be an Approver. • Control Category 3: Authors can approve documents and act as Document Coordinators. cd_labeling_doc_authors cd_<domain>_template_authors Document Coordinators cd_regulatory_doc_coordinator cd_quality_doc_coordinator Manage the release of controlled documents. cd_clinical_doc_coordinator • Control Category 2: Approvers can act as Document Coordinators. cd_non_clinical_doc _coordinator • Control Category 3: Authors can act as Document Coordinators. cd_safety_doc_coordinator cd_labeling_doc_coordinators Product Managers cd_product_managers Create and manage Product Registration Forms. Responsible for all documents across the studies, clinical, trials, and projects associated with particular products. Regulatory, Clinical Trial, Non-clinical Study, Quality Project, Labeling, and Safety Project Managers cd_regulatory_managers Create and manage registration forms for each domain. For example, Quality Project Managers create Project Registration Forms. cd_quality_project_managers cd_clinical_trial_managers cd_non_clinical_study _managers Responsible for related documents. cd_labeling_managers cd_safety_project_managers cd_regulatory_activity _managers 39 Life Sciences Solution Fundamentals User Role Groups Description Readers cd_regulatory_doc_readers General consumers with read-only access to Approved versions. cd_quality_doc_readers cd_clinical_doc_readers cd_non_clinical_doc_readers cd_safety_doc_readers cd_labeling_doc_readers Reviewers cd_non_clinical_doc_reviewers cd_regulatory_doc_reviewers cd_quality_doc_reviewers Review documents using annotations and edit documents. They are responsible for technical review during the authoring and review cycle. cd_clinical_doc_reviewers cd_safety_doc_reviewers cd_labeling_doc_reviewers Administrators cd_admingroup Access administrative functions but do not have access to controlled documents. Documentum R&D includes these defined user groups: • Cross-functional User Groups, page 47 • Reporting Groups, page 47 • Clinical User Groups, page 41 • Non-clinical User Groups, page 42 • Quality User Groups, page 42 • Regulatory User Groups, page 43 • Safety User Groups, page 43 • Labeling User Groups, page 44 Cross-functional User Groups The following table describes the cross-functional user groups: Groups Description cd_admingroup Administrator: • Access to administrative functions • Require Administrative client capability • Do not have access to controlled documents 40 Life Sciences Solution Fundamentals Groups Description cd_product_managers Product managers who create and manage Product Registration Forms. cd_product_registration_group Regulatory Managers who can register products and projects. cd_project_registration_group cd_general_doc_authors Users in the role can create general documents (letter, memos, notes). By default, all other authors groups are members of the cd_general_doc_authors role. Reporting Groups Documentum R&D provides an optional reporting feature for monitoring active clinical trials based on eDRG. The reports can be customized using eDRG. The EMC Documentum for Life Sciences Reports Guide provides more information. In Documentum D2, users view dashboards containing report information. The following table describes the reporting groups used by the Report Generator: Groups Description report_user Report Users can generate reports and view historical data in the form of saved reports. report_builder Report Builders can manage report definitions and presentations. report_administrator Report Administrators can define categories and scheduling of reports. Clinical User Groups Use the clinical user groups for clinical documents. The following table describes the clinical user groups: Groups Description cd_clinical Users of clinical documents. Users must be a member of this group to access information on the Product registration form. cd_clinical_doc_approvers Clinical document approvers cd_clinical_doc_auditors Clinical document auditors cd_clinical_doc_authors Clinical document authors cd_clinical_doc_readers Clinical document readers cd_clinical_doc_reviewers Clinical document reviewers 41 Life Sciences Solution Fundamentals Groups Description cd_clinical_doc_coordinators Clinical document coordinators and business-level administrator for clinical documents cd_clinical_trial_managers Clinical trial managers who create Clinical trial registration forms cd_clinical_template_authors Clinical template document authors cd_clinical_template_approvers Clinical template document approvers Non-clinical User Groups Use the non-clinical user groups for non-clinical documents. The following table describes the non-clinical user groups: Groups Description cd_non_clinical Users of non-clinical documents. Users must be a member of this group to access information on the Product registration form. cd_non_clinical_doc_approvers Non-clinical document approvers cd_non_clinical_doc_auditors Non-clinical document auditors cd_non_clinical_doc_authors Non-clinical document authors cd_non_clinical_doc_coordinators Non-clinical document coordinators cd_non_clinical_doc_readers Non-clinical document readers cd_non_clinical_doc_reviewers Non-clinical document reviewers cd_non_clinical_study_managers Non-clinical trial managers who create Non-Clinical Study Registration forms. cd_non_clinical_template_authors Non-clinical template document authors cd_non_clinical_tem_approvers Non-clinical template document approvers Quality User Groups Use the quality user groups for quality and manufacturing documents. The following table describes the quality user groups: Groups Description cd_quality Users of quality documents. Users must be a member of this group to access information on the product registration form. cd_quality_doc_approvers Quality document approvers cd_quality_doc_auditors Quality document auditors 42 Life Sciences Solution Fundamentals Groups Description cd_quality_doc_authors Quality document authors cd_quality_doc_coordinators Quality document coordinators cd_quality_doc_readers Quality document readers cd_quality_doc_reviewers Quality document reviewers cd_quality_project_managers Quality and manufacturing project managers who create Project Registration forms cd_quality_template_authors Quality template document authors cd_quality_template_approvers Quality template document approvers Regulatory User Groups Use the regulatory user groups for regulatory documents. The following table describes the regulatory user groups: Groups Description cd_regulatory Users of regulatory and administrative documents. cd_regulatory_doc_approvers Regulatory document approvers cd_regulatory_doc_auditors Regulatory document auditors cd_regulatory_doc_authors Regulatory document authors cd_regulatory_doc_readers Regulatory document readers cd_regulatory_doc_reviewers Regulatory document reviewers cd_regulatory_managers Regulatory Managers who create Regulatory Application Registration Forms cd_regulatory_publishers Regulatory publishers who assemble and publish submission documents cd_regulatory_activity_managers Regulatory Activity Managers handle regulatory activity packages cd_regulatory_activity_monitors Regulatory Activity Monitors check regulatory activity packages cd_regulatory_template_authors Regulatory template document authors cd_regulatory_template_approvers Regulatory template document approvers Safety User Groups Use the safety user groups for Safety documents. The following table describes the safety user groups: 43 Life Sciences Solution Fundamentals Groups Description cd_safety Users of safety documents. Users must be a member of this group to access information on the Product registration form. cd_safety_doc_approvers Safety document approvers cd_safety_doc_auditors Safety document auditors cd_safety_doc_authors Safety document authors cd_safety_doc_coordinators Safety document coordinators cd_safety_doc_readers Safety document readers cd_safety_doc_reviewers Safety document reviewers cd_safety_project_managers Safety project managers cd_safety_template_authors Safety template document authors cd_safety_template_approvers Safety template document approvers Labeling User Groups Use the safety user groups for Labeling documents. The following table describes the labeling user groups: Groups Description cd_labeling Users of Labeling documents. Users in this role can access the Labeling domain documents and at least have READ permission on the documents. cd_labeling_doc_approvers Labeling document approvers cd_labeling_doc_auditors Labeling document auditors cd_labeling_doc_authors Labeling document authors cd_labeling_doc_coordinators Labeling document coordinators cd_labeling_doc_readers Labeling document readers cd_labeling_doc_reviewers Labeling document reviewers cd_labeling_managers Labeling project managers cd_labelling_template_authors Labeling template document authors cd_labelling_template_approvers Labeling template document approvers 44 Life Sciences Solution Fundamentals User Roles in Documentum SSV Documentum SSV provides defined user roles that enable or restrict user access to documents and information in the system. The following table describes the user roles: User Role Group Description Regulatory Manager cd_regulatory_managers Create and manage regulatory application registration forms. Create product and project registration forms. Handles regulatory documents. Can import and view regulatory submissions. Regulatory Affairs Manager cd_regulatory_managers Creates and manages regulatory application registration forms. Creates and monitors document workflows. Imports correspondence documents and manages the lifecycle transitions of these documents. Regulatory Affairs Knowledge Worker cd_regulatory_doc_authors Imports correspondence documents and manages the lifecycle transitions of these documents. Creates and monitors document workflows. Regulatory Archivist cd_regulatory_doc_authors Imports submissions. Verifies the lifecycle status and security settings for the imported submissions. Manage the status of submission documents, that is, change the status on Effective/Approved/Final documents such as demote to Pending, change incorrect metadata, and promote to Effective/Approved/Final. Regulatory Affairs Reader cd_regulatory_doc_readers Has read-only access to submission and correspondence documents based on their permissions set by the regulatory application registration forms. 45 Life Sciences Solution Fundamentals User Role Group Description Regulatory Publisher cd_regulatory_publisher Can import submissions, if required. General Consumer cd_regulatory_doc_readers Has read-only access to submission and correspondence documents based on their permissions set by the regulatory application registration forms. cd_clinical_doc_readers cd_non_clinical_doc_readers cd_quality_doc_readers Documentum SSV includes these defined user groups: • Correspondence User Groups, page 46 • Cross-functional User Groups, page 47 • Reporting Groups, page 47 Correspondence User Groups Use the correspondence user groups for correspondence documents. The following table describes the correspondence user groups: Groups Description cd_corres Users of Correspondence documents. Users in this role are able to access the Correspondence domain documents and at least have READ permission on the documents. cd_ corres_doc_approvers Correspondence document approvers cd_ corres_doc_auditors Correspondence document auditors cd_corres_doc_authors Correspondence document authors create and edit Correspondence documents in the Draft state. cd_corres_doc_coordinators Correspondence document coordinators cd_corres_doc_readers Correspondence document readers cd_corres_doc_reviewers Correspondence document reviewers cd_corres_managers Correspondence project managers cd_ corres_template_authors Correspondence template document authors cd_ corres_template_approvers Correspondence template document approvers 46 Life Sciences Solution Fundamentals Cross-functional User Groups The following table describes the cross-functional user groups: Groups Description cd_admingroup Administrator: • Access to administrative functions • Require Administrative client capability • Do not have access to controlled documents cd_regulatory Users of regulatory and administrative documents. cd_product_managers Product managers who create and manage Product Registration Forms. cd_quality_project_managers Quality and manufacturing project managers who create Project Registration forms cd_product_registration_group Regulatory Managers who can register products and projects. cd_project_registration_group Reporting Groups Documentum SSV provides an optional reporting feature for monitoring active clinical trials based on eDRG. The reports can be customized using eDRG. The EMC Documentum for Life Sciences Reports Guide provides more information. In Documentum D2, users view dashboards containing report information. The following table describes the reporting groups used by the Report Generator: Groups Description report_user Report Users can generate reports and view historical data in the form of saved reports. report_builder Report Builders can manage report definitions and presentations. report_administrator Report Administrators can define categories and scheduling of reports. 47 Life Sciences Solution Fundamentals Control Categories The term control category refers to the level of regulation that should be applied to a document. The control category for each artifact is defined in the creation profile through the assigned Default Values template and lifecycle. The control category for a document is stored in the Category attribute. It is an integer value of either 1, 2, 3, or 4. The value of the Category attribute determines the lifecycles and workflows that are applied to a document. Documentum Life Sciences solutions provide four control categories. The common security features for all control categories: • Allow joint and collaborative authoring in Documentum D2. • Restrict access to content based on user role and lifecycle state. • Allow complete withdrawal of the document with optional retention of historic copies. The following table describes the security of the document control categories: Control Categories Security Description Category 1 Controlled documents that require formal review and approval along with signoff by the Quality Organization (QO). These documents become Effective/Approved/Final and may be sent on TBR and periodic review workflows. The workflow process includes: • Independent two person review and approval before release. • Approval with electronic signatures for specific document types. • Additional approval by the Quality Organization department before release. • Controlled release by Document Coordinators. • Controlled release that can be deferred until a specified effective date. • Effective/Approved/Final versions that automatically rescind on expiration. • Effective/Approved/Final versions that can be suspended and reinstated on demand. • Effective/Approved/Final versions that can be superseded when the next version becomes effective. • Expiration notifications. 48 Life Sciences Solution Fundamentals Control Categories Security Description Category 2 Controlled documents that require formal review and approval. They do not require signoff by the Quality Organization. The workflow process includes: • Independent two person review and approval before release. • Approval with electronic signatures for specific document types. • Documents that become effective immediately. • Effective/Approved/Final versions that can be suspended and reinstated on demand. • Effective/Approved/Final versions that can be superseded when the next version becomes effective. Category 3 Controlled documents that can be self-approved by Authors. Independent review and approval is not required. This category is typically assigned to documents that are created and/or approved outside of the system. The workflow process: • Enables self-approval by Authors. • Makes the previously Effective/Approved /Final version superseded when the next version becomes Effective/Approved/Final. • Allows the Effective/Approved/Final version to be suspended and reinstated on demand. Category 4 Non-controlled general documents that do not require formal review or approval. These documents are not allowed in regulatory submissions. Authors manage access to these documents. The following table shows the user roles and document lifecycle states associated with the document control categories: 49 Life Sciences Solution Fundamentals Control Categories User Roles Lifecycle States Category 1 Approvers Auditors Authors Document Coordinators Quality Organization (QO) Approvers Readers Reviewers Draft For Review For Approval Release Pending Effective/Approved/Final Suspended Expired Superseded Withdrawn Category 2 Approvers Auditors Authors Readers Reviewers Draft For Review For Approval Effective/Approved/Final Suspended Superseded Withdrawn Category 3 Auditors Authors Readers Regulatory Affairs Reviewers Draft For Review Reviewed Effective/Approved/Final Suspended Superseded Withdrawn Category 4 Authors Readers Not Issued Issued Historic 50 Chapter 2 Customizing D2-Based Solutions This chapter contains the following topics: • Extending D2-Based Life Sciences Solutions, page 51 • Upgrading the Customized Solution, page 54 • Best Practices for Team Development with D2, page 56 • Extending Roles, page 57 The Life Sciences solutions are configured in D2 Config. The configurations are based on life science industry best practices and stored in a set of Documentum D2 applications. Topics in this chapter describe configurable features and tasks for experienced Documentum and Documentum D2 administrators to perform to meet their business requirements. To generate a document listing the default configurations, select Specifications > Generate specifications from D2 Config. Some administrative functions are available in D2 Client. The EMC Documentum D2 Administration Guide provides more information. Extending D2-Based Life Sciences Solutions You can use all of the configuration capabilities of Documentum Content Server and D2 when you deploy the Documentum Life Sciences solution. It is important to note that future upgrades can be complicated by extensive changes to the D2 configurations of the base Life Sciences solution. This section describes procedures and best practices for extending D2-based Life Sciences solutions in a manner that will enable you to upgrade to a new version of a solution in the future and then reapply your specific extensions and modifications. Extending the Life Sciences solution involves the following key activities: 1. Creating a custom application 2. Modifying the base configuration 3. Extending the base solution context 51 Customizing D2-Based Solutions Creating a Custom Application All configuration items that are either part of the base solution but modified by the customer or newly added by the customer must be assigned a custom application. The first step when extending an existing solution is to define the custom application: 1. In D2-Config, select Tools > Applications. 2. Click New. In the example below, the new application is named, KB Pharma. All of the configurations that are either modified or added by the customer will be assigned this application. Existing EMC applications defined by the base solution should be left in the Applications list for base solution configurations as well. Assignment of a custom application enables you to easily identify your custom configurations and package them for deployment and backup. Modifying or Extending a Base Configuration For each customization, you must decide whether: • To change the base solution configuration or, • Use the base configuration as a template for creating a new configuration. You can use the Create from option to create the new configuration from the base template. In general, it is recommended to create a new configuration from the existing one rather than directly modifying the base solution configuration. However, this is not always practical because you then must change all existing references to the base configuration to instead refer to your custom configuration. This can significantly increase the number of configuration items that you must change. If there are many references to a configuration item, directly modifying it is better than copying it. Dictionaries are a good example of configurations that you should modify directly. Dictionaries and taxonomies are referenced heavily in property pages, auto-naming, auto-linking, and so on. It is easy to reconcile differences between two versions of a dictionary. 52 Customizing D2-Based Solutions Extending the Base Solution Contexts To ensure that any new custom configurations are used at runtime, extend the base solution contexts to which your new configurations apply. 1. Use Create from to create a new context with the same parameters as the existing context. 2. Assign your custom application name to the extended context. 3. In the matrix, position the extended context to the left of the context it extends so that your custom context takes precedence. 4. Assign your custom configurations to the relevant extended contexts in the configuration matrix as shown in the following image: 53 Customizing D2-Based Solutions Upgrading the Customized Solution When upgrading to a new version of the solution and you changed an existing solution configuration, you must perform a comparison of your modified configuration with the new version of the solution configuration and merge the two configurations. Merging can either be done through the D2-Config tool after importing the new version or within the configuration export XML files prior to importing them. However, this is an activity that requires a developer or consultant with extensive knowledge of D2, the base Documentum Life Sciences solution, and the customer modifications. 54 Customizing D2-Based Solutions Reconciling Extended Base Configurations with Solution Upgrades D2-Config provides the Create from capability for creating a new configuration from an existing configuration. In D2, Create from is enhanced so that a reference to the original base configuration item is maintained in the parents_config attribute of the new custom configuration. When a new version of the base configuration is imported during a solution upgrade, D2-Config reports warnings for any custom configurations in the new version that differs from the previous version. In this way, D2 identifies which of your custom configurations needs to be reconciled with the new base solution configuration. For example, assume you customize the Procedure Properties configuration by using Create from to first create a copy of this property page and then modify the copy. You name the custom property page KB Procedure Properties. D2-Config will report the following warning when importing the new version of the solution configurations: Reconciling the changes between the new version of the base configuration (in this example, Procedure Properties) and the extension (in this example, KB Procedure Properties) is a manual process that involves either: • Using a diff and merge tool on the two versions of the XML file and then importing the updated XML file, or • Using D2-Config to extend the upgraded version of the configuration and reapplying your changes. Merging D2 Configuration XML Files The format of D2 configuration files exported to the file system is enhanced in D2 to better support team development of D2-based applications and comparison between two versions of a configuration file. D2 supports the following features related to exported configuration files: • Granular files: The structure of the exported configurations is completely granular. There is a one-to-one correspondence between a configuration item and an XML file. • Consistent ordering of XML attributes and elements: The XML elements and attributes within the XML files are ordered consistently and in a more readable format to facilitate comparison between multiple versions of the file. • Un-encoded filenames: Filenames in D2 configuration export packages are not hex-encoded. The filename reflects the name of the configuration item. These improvements to the D2 configuration export packages greatly improve team development experience on D2 and are required for enabling and simplifying comparison between two versions of a configuration export package. Comparing export packages is a necessary step in the process of upgrading a solution and migrating customer extensions to the upgraded version. 55 Customizing D2-Based Solutions The Life Sciences solution suite 2.0 and below were built using D2 4.1. To compare a customized Life Sciences 2.0 configuration package, first import it to a repository using D2-Config, then re-export it. You can then compare the configurations with those in Life Sciences solution suite 3.0. The following image shows the comparison of two versions of a creation profile using a diff and merge tool: Notice that the changes are highlighted. In this case, the version of the file on the left allows for creation of two additional document types. There are also some changes in the properties of the creation profile highlighted. After you have verified the changes, you can merge the changes using the tool. Note: In some sections, there is a separation between the configuration definition and its settings. This can be seen as a “contents” folder under the main folder. While there may be no changes in the definition file, there may be changes in the content file. It is recommended that you check both files. Best Practices for Team Development with D2 You should manage the source files for all of your custom components in a source code control system that allows versioning of files, including D2 configuration files. Multiple developers can modify configurations in a shared Documentum repository or they can modify them in their own local repository that is not shared. In either case, each developer should export their modified configurations, unzip the exported configuration package, and check the individual XML files into a source code control system. Within the source code control system maintain the same directory hierarchy in which D2 exports files. Building D2 configurations can be performed by retrieving the latest configuration directory from your source code control system and rezipping them. A standard archive tool like Winzip can be used to rezip the files. 56 Customizing D2-Based Solutions Extending Roles If you require custom roles to be created in the Life Sciences solution, you can do so by extending the predefined roles that are installed with the application. Extending the roles involves making property page changes and workflow configuration changes through D2–Config. Creating Custom Roles 1. Log in to Documentum Administrator. 2. Create a new custom role. 3. Assign the users and groups to the new role. 4. Add the custom role to the existing role. For example, to create a new role for authors, create a new_authors custom role. Then, add this role as a member of the existing cd_controlled_doc_authors role. The EMC Documentum Administrator User Guide provides the steps of creating custom roles. Configuring the Property Pages The Property pages in the Life Sciences solution query and display the default roles. You must modify these queries so that the custom roles are used. For example, in the Quality Documents property page, the Process Info tab displays the users in different roles. If you want to display a custom role for authors, you must change the query by replacing cd_quality_doc_authors with the custom role. 1. Log in to D2–Config. 2. Click Go to > Property page. 3. Under Property pages, select the property page for the respective domain. 4. Under Structure, expand the Process Info folder. 5. Expand the role folder for which a custom role is created. 6. On the right pane, in the DQL Query field, replace the old role in the query with the new role. 7. Click Save. Configuring Workflows When a workflow is started, the system specifies the performers for each state of the workflow. By default, users who are members of the default roles are assigned as performers to the workflow. However, if the default roles are extended with custom roles, the query that assigns the performers must be modified. 1. Log in to D2–Config. 57 Customizing D2-Based Solutions 2. Click Go to > Workflow. 3. Under Workflow List, select a workflow. 4. Under Participant’s Structure, select the default role. 5. In the DQL query for the role, change the default role to the custom role. 6. Click Save. Configuring Roles (For Q&M Only) Out-of-the-box, Documentum Q&M provides a list of site-based roles as defined in the Applicable Sites dictionary. Follow these steps configure the your own sites and user roles according to your environment and requirements. 1. Log in to D2–Config. 2. In the filter on the main toolbar, select All elements. 3. On the Data menu, click Dictionary. 4. Under Dictionaries, select GMP Applicable Sites. 5. On the Languages tab, you can add or remove the required sites. 6. On the Alias tab, under each roles, define the respective user group for the respective site. For example, for the Boston site, under authors, type cd_boston_authors. 7. Click Save. 58 Chapter 3 Life Sciences Data Model This chapter contains the following topics: • Data Model Overview, page 59 • Add or Modify Attributes in Existing Solution Types, page 62 • Create New Types that Extend from Existing Solution Types, page 62 Data Model Overview The Life Sciences data model serves two functions: • It defines attributes that support all of the features provided by the Life Sciences solutions such as controlled document management, TMF planning and tracking, regulatory application management, and so on. • It implements, as a Documentum object model, the taxonomy and metadata described in the DIA EDM reference model 1.0 and the DIA TMF reference model 2.0. Users in the appropriate roles can create any document artifact defined in these two standard reference models or in the Quality and Manufacturing document categories. The following diagram depicts the Life Sciences object type hierarchy: 59 Life Sciences Data Model 60 Life Sciences Data Model Two base types, cd_controlled_document and cd_common_ref_model, define metadata that pertains to all subtypes. Users do not directly create instances of these two types. Types with the _info suffix represent registration forms. Registration forms are created and managed by the Business Administrators in each respective domain, that is, Product Managers, Clinical Trial Managers, Non-Clinical Study Managers, Project Managers, and Regulatory Managers. Note: Registration forms are not currently used in the Documentum Q&M solution. Users in each respective domain in the appropriate roles can create instances of the types listed in the following table. Table 3. Objects Types for which Users can Create Documents Type Domain Created By Solution(s) cd_change_request Change Request Readers from all domains Documentum Q&M cd_clinical Clinical Clinical Authors Documentum R&D cd_clinical_tmf_doc Clinical TMF Clinical Authors and Contributors Documentum eTMF cd_non_clinical Non-Clinical Non-Clinical Authors Documentum R&D cd_general General Authors from all domains Documentum R&D cd_non_clinical Non-Clinical Non-Clinical Authors Documentum R&D cd_quality Quality Quality Authors Documentum R&D cd_reg_admin Regulatory /Administrative Regulatory/ Administrative Authors Documentum R&D cd_quality_gmp GMP All GMP authors Documentum Q&M 61 Life Sciences Data Model You can extend the data model in the following ways: • Add or modify attributes in existing solution types • Create new types that extend from the existing solution types Add or Modify Attributes in Existing Solution Types If an attribute that represents metadata required for your organization’s documents is not available in the standard data model, you can alter the existing types by following these recommendations: • Use your own naming convention for custom attributes so that you can easily identify them. For example, if KB Pharmaceuticals requires additional attributes on the cd_quality_manufacturing_sop documents for equipment type, physical location, and process step, name these attributes as kb_equipment_type, kb _physical_location, and kb_process_step respectively. • Do not add or move a standard attribute to a higher level in the type hierarchy. If an existing attribute is required on additional object types, add a new attribute to those object types instead. Moving a standard attribute from a lower-level object type to a higher-level type can cause installation errors during future upgrades of the base solution. • You can increase the length of string attributes if needed. When upgrading, the longer length is retained. However, ou cannot change an attribute from repeating to single or from single to repeating. • After adding new attributes, you must extend the relevant property page configurations and any other D2 configurations in which you want to use the new attributes. For example, you may choose to define new auto-naming or auto-linking configurations that use the new attributes. Create New Types that Extend from Existing Solution Types If there is no standard object type that represents your documents, you can create a new object type that extends from an existing solution type. • Use your organization’s naming convention for the type name. Do not use the cd_ or ls_ prefixes. • After adding new types, you must add D2 configurations that enable users to create and manage instances of the new type. Typically, the following D2 configurations are needed to support a new object type: — Dictionary used in a creation profile — Default Values template used in a creation profile — Property page — Creation profile 62 Life Sciences Data Model — Auto-naming — Auto-linking • You may also need to create content templates for the new object type. Caution: Extending the object model with additional levels can affect the performance of the system. 63 Life Sciences Data Model 64 Chapter 4 Reference Models This chapter contains the following topics: • Standard Solution Implementation of the DIA EDM Reference Model, page 66 • Standard Solution Implementation of the DIA TMF Reference Model, page 71 • Standard Solution Implementation of Quality and Manufacturing Document Models, page 72 • Extending the Standard Reference Model Implementation (eTMF), page 74 • Implementing a Custom Reference Model (eTMF), page 79 A document management reference model defines the following: • The kinds of documents that are managed by the document management system • The metadata that is used to describe each kind of document • An organizational structure for documents The DIA EDM and TMF reference models are industry standard models developed by a consortium of Life Sciences industry and vendor experts. The DIA EDM and TMF reference models provide an excellent starting point for implementing a Life Sciences document management system because they are based on industry experience and best practices. The Documentum Life Sciences solutions include a complete implementation of the DIA EDM reference model. The eTMF solution includes a complete implementation of the TMF reference model as well. After installing a solution, you can immediately create and manage any of the documents (referred to as artifacts) defined by the reference models. The reference models are implemented using D2 configurations. Dictionaries, taxonomies, creation profiles, property pages, auto link, and auto naming configurations for all documents in the DIA EDM Regulatory/Administrative, Quality, Non-Clinical, and Clinical domains are provided in all solutions. The eTMF solution provides D2 configurations for creating and managing all document artifacts defined in the DIA TMF reference model. The Documentum Q&M solution provides D2 configurations for creating and managing document artifacts related to the quality and manufacture of marketed product. The configurations have been derived from industry best practice and are closely aligned with the DIA reference model that is currently in development for Q&M documents. You can use the standard solution implementation of these models out-of-the-box. You can also extend the standard implementation to support additional kinds of documents and metadata. Or you can use the standard solution implementation as a pattern for implementing a completely different model. 65 Reference Models Standard Solution Implementation of the DIA EDM Reference Model The DIA EDM reference model is defined in an Excel spreadsheet that is available on the DIA website. The spreadsheet contains tabs for each of the four document domains: Regulatory/Administrative, Quality, Non-Clinical, Clinical. Each tab lists the document artifacts for that domain and the metadata for the documents. The documents are categorized according to group and subgroup. The following image is a small snippet of the DIA EDM reference model spreadsheet: The Artifact Name column lists the individual document artifacts for the given domain. In the snippet, artifacts for the Quality domain are shown. The Group and Sub-Group columns show how each artifact should be categorized. The columns to the right of Artifact Name, list the metadata for documents in the given domain. An “M” in the cell indicates, the attribute is mandatory for the associated artifact. This model is implemented in the Life Sciences solution using D2 dictionaries and taxonomies. D2 property pages enforce mandatory attributes as defined in the model. For the purpose of explanation, the Quality Domain dictionaries are used as an example. The complete set of D2 dictionaries that list the groups, subgroups, and artifacts defined in the DIA EDM and TMF model are described in Appendix C. The Quality Domain dictionaries used in the implementation of the DIA EDM reference model are listed in the table below. Notice that these dictionaries map to the columns of the DIA EDM reference model spreadsheet. 66 Reference Models Table 4. EDM reference model Quality domain dictionaries Dictionary Name Description Quality Groups List of values in the Group column on the Quality domain tab of the DIA EDM reference model spreadsheet. These values are the logical groupings or CTD modules in the Quality domain. Quality Subgroups List of values in the Sub-Group column on the Clinical domain tab of the DIA EDM reference model spreadsheet. Within the Quality domain, categories of documents within a group, usually based on CTD module subsets. Quality Artifact Names Complete list of Quality artifacts defined in the Artifact Name column on the Quality domain tab of the DIA EDM reference model spreadsheet. Quality Adventitious Agents Artifact Names List of artifacts in the Adventitious Agents group on the Quality tab of the DIA EDM reference model spreadsheet. Quality Drug Product Artifact Names List of artifacts in the Drug Product group on the Quality tab of the DIA EDM reference model spreadsheet. Quality Drug Substance Artifacts Names List of artifacts in the Drug Substance group on the Quality tab of the DIA EDM reference model spreadsheet. Quality Facility Artifact Names List of artifacts in the Facilities and Equipment group on the Quality tab of the DIA EDM reference model spreadsheet. Quality Information Artifact Names List of artifacts in the Quality Information group on the Quality tab of the DIA EDM reference model spreadsheet. Quality Literature Reference Artifact Names List of artifacts in the Literature References group on the Quality tab of the DIA EDM reference model spreadsheet. Quality Medical Device Artifact Names List of artifacts in the Medical Device group on the Quality tab of the DIA EDM reference model spreadsheet. Quality Overall Summary Drug Product Artifact Names List of artifacts in the Quality Overall Summary group/Drug Product subgroup on the Quality tab of the DIA EDM reference model spreadsheet. Quality Overall Summary Drug Substance Artifact Names List of artifacts in the Quality Overall Summary group/Drug Product subgroup on the Quality tab of the DIA EDM reference model spreadsheet 67 Reference Models These dictionaries are used in D2 creation profile configurations to enable users to create specific document artifacts. In the following creation profile screenshot, the Quality Facility Artifact Name dictionary is used in a creation profile to enable users to create Facilities and Equipment documents: D2 taxonomy configurations use these dictionaries and those in Appendix C DIA EDM and TMF reference model Dictionaries to define the Group/Subgroup/Artifact organizational structure defined by the DIA EDM reference model. The following screenshot shows the Quality Classification by Group dictionary in D2-Config: 68 Reference Models The following table lists the complete set of taxonomies in the Documentum Life Sciences solutions that are used to implement the DIA EDM reference model. Table 5. DIA EDM reference model taxonomies Taxonomy Name Description Dictionaries Clinical Classification by Artifact Organization of Clinical documents according to artifact/subgroup/group as defined by the DIA EDM Reference model. Clinical Groups Organization of Clinical documents according to group/subgroup/artifact as defined by the DIA EDM Reference model. Clinical Groups Organization of Non-Clinical documents according to artifact/subgroup/group as defined by the DIA EDM Reference model. Non-Clinical Groups Clinical Classification by Group Non-Clinical Classification by Artifact Clinical Subgroups Clinical Artifact Names Clinical Subgroups Clinical Artifact Names Non-Clinical Subgroups Non-Clinical Artifact Names 69 Reference Models Taxonomy Name Description Dictionaries Non-Clinical Classification by Group Organization of Non-Clinical documents according to group/subgroup/artifact as defined by the DIA EDM Reference model. Non-Clinical Groups Organization of Quality documents according to artifact/subgroup/group as defined by the DIA EDM Reference model. Quality Groups Organization of Quality documents according to group/subgroup/artifact as defined by the DIA EDM Reference model. Quality Groups Organization of Regulatory/Administrative documents according to artifact/region/subgroup/group as defined by the DIA EDM Reference model. Regulatory-Admin Artifact Names Organization of Regulatory/Administrative documents according to group/subgroup/region/artifact as defined by the DIA EDM Reference model. Regulatory-Admin Groups Quality Classification by Artifact Quality Classification by Group Regulatory-Admin Classification by Artifact Regulatory-Admin Classification by Group Non-Clinical Subgroups Non-Clinical Artifact Names Quality Subgroups Quality Artifact Names Quality Subgroups Quality Artifact Names Geographic Regions Regulatory-Admin Subgroups Regulatory-Admin Groups Geographic Regions Regulatory-Admin Subgroups Regulatory-Admin Artifact Names The above taxonomies are used in D2 property page configurations to provide Taxonomy-based value assistance. If an artifact is selected, the list of valid subgroups and groups is filtered using the appropriate taxonomy as shown in the following screenshot: 70 Reference Models Standard Solution Implementation of the DIA TMF Reference Model The DIA TMF reference model is a standard that describes the documents that might be included in a Trial Master File. Some of the artifacts defined in the Clinical domain of the DIA EDM reference model overlap with those defined in the DIA TMF reference model. The following table lists the dictionaries that map to the columns of the DIA TMF reference model. Table 6. TMF dictionaries Dictionary Name Description TMF Models Name and version of the TMF reference model that is supported as listed in the DIA TMF reference model spreadsheet. TMF Artifact Names List of values in the Artifact name and Alternate name columns of the DIA TMF Reference model spreadsheet. TMF Sections List of values in the Section column of the DIA TMF Reference model spreadsheet. TMF Unique Artifact Names List of values in the Artifact name and Alternate name columns of the DIA TMF Reference model spreadsheet. TMF Zones List of values in the TMF Zone column of the DIA TMF Reference model spreadsheet. The following D2 taxonomies are used to implement the zone/section/artifact organizational structure defined by the DIA TMF Reference model. Table 7. TMF taxonomies Taxonomy Name Description TMF Artifacts by Model Dictionaries TMF Models TMF Unique Artifact Names TMF Classification by Artifact For each reference model, defines 1-1 mappings between unique artifact names and other artifact properties in the Trial Master File (TMF). TMF Models TMF Unique Artifact Names TMF Artifact Names TMF Zones TMF Sections TMF Artifact Numbers TMF Inclusion Requirement States 71 Reference Models Taxonomy Name Description Dictionaries TMF Investigator Required Flags TMF Subject Required Flags TMF Submissible Flags TMF Investigator Access TMF Inspector Access TMF External Contributors TMF External Reviewers TMF Zones and Sections Enables TMF zones and sections to be selected for scoping bulk export operations. TMF Models TMF Zones TMF Sections Standard Solution Implementation of Quality and Manufacturing Document Models Life Sciences solutions enable the creation and management of other document types besides the standard DIA reference model artifacts that have been established for R&D and eTMF. The following D2 dictionaries and taxonomies are used for documents in the Quality and Manufacturing document models: • GMP Categories • GMP Groups • GMP Subgroups • GMP Artifacts The following screenshot shows the GMP Artifacts taxonomy in D2-Config: 72 Reference Models The following table lists the taxonomy properties for the D2 dictionaries in D2-Config. Table 8. Taxonomy Taxonomy Name Description Used Dictionaries GMP Artifact Hierarchy and classification for all Q&M documents. GMP Categories, GMP Groups, GMP Subgroups, GMP Artifacts 73 Reference Models Extending the Standard Reference Model Implementation (eTMF) Documentum eTMF maintains its reference model in several configuration components within the system: • Dictionaries: Contain information about sets of acceptable values in the reference model • Taxonomies: Contain information about sets of dictionary values • Creation profile: Contain information about the creation of placeholders. When placeholders are created, this is the creation matrix that is consulted. • File plan and file plan templates: Configured to activate artifacts within studies. Each artifact to be activated must be contained within the file plan for the study. The file plan template enables you to add new artifacts in the new study file plans, and be imported when study plans are reloaded. Each of these components must be configured with the new artifacts that are to appear in the system. Extending Dictionaries In Documentum eTMF, you must extend the following dictionaries. TMF Zones TMF Zones contains all the zones in use. The following table lists the artifacts in this dictionary. Table 9. Extending the reference model - TMF Zones Name Language /Alias Key English Description Name of the zone L Name of the zone For each new zone (not yet in use), add the appropriate row to this dictionary. TMF Sections TMF Sections contains all the sections in use. The following table lists the artifacts in this dictionary. Table 10. Extending the reference model - TMF Sections Name Language /Alias Key English Description Name of the section L Name of the section For each new section (not yet in use), add the appropriate row to this dictionary. 74 Reference Models TMF Artifact Number TMF Artifact Number contains all the artifact numbers in use. The following table lists the artifacts in this dictionary. Table 11. Extending the reference model - TMF Artifact Number Name Language /Alias Description Key Artifact number For each new number (not yet in use), add the appropriate row to this dictionary. TMF Artifact Names TMF Artifact Names contains the base name of the artifact. The following table lists the artifacts in this dictionary. Table 12. Extending the reference model - TMF Artifact Names Name Language /Alias Description Key English Base name of the artifact L Base name of the artifact For each artifact base name, add the appropriate row to this dictionary. In certain circumstances, there is a base name and several unique names for an artifact. For example, Filenote as a base artifact name has the following values as unique artifact names. Table 13. Extending the reference model - Example of multiple unique names Base Artifact Unique Artifact Name Document Zone/Section/Artifact Filenote (Central Trial Documents) Central Trial Documents General 2.4.4 Filenote (Centralized Testing) Centralized Testing General 8.3.4 Filenote (Data Management) Data Management General 10.5.4 Filenote (IP and Trial Supplies) IP and Trial Supplies General 6.7.4 Filenote (IRB-IEC and other Approvals) IRB-IEC and other Approvals General 4.4.4 Filenote (Regulatory) Regulatory General 3.4.4 Filenote (Safety Reporting) Safety Reporting General 7.3.4 Filenote (Site Management) Site Management General 5.5.4 75 Reference Models Base Artifact Unique Artifact Name Document Zone/Section/Artifact Filenote (Statistics) Statistics General 11.5.4 Filenote (Third parties) Third parties General 9.3.4 Filenote (Trial Management) Trial Management General 1.5.4 The name of the artifact from this table appears in the tmf_artifact_name of the document and placeholders based on this artifact. In other cases, there will merely be a one-to-one relationship. TMF Unique Artifact Names TMF Unique Artifact Names contains the unique name of the artifact. The following table lists the artifacts in this dictionary. Table 14. Extending the reference model - TMF Unique Artifact Names Name Language /Alias Key Description Unique name of the artifact. English L Unique name of the artifact. Zone A Name of the zone where this artifact appears. Section A Name of the section where this artifact appears. Artifact-No A The number of this artifact (Zone/Section/Artifact) – not zero padded. Artifact-Name A Name of the base artifact that this artifact is associated with. Numbered-Artifact-Name A A concatenation of the Artifact-No and the Section. Special Naming Convention A The naming convention to be applied to documents of this artifact type through the CDFSetAttributes method. Trial Conditions A A filter condition on the trial that prevents the placeholders for this artifact from being created if the condition is not met. By design, the artifact number, zone, section, and base artifact name information appears in this dictionary. The Numbered-Artifact-Name is constructed by concatenating the artifact number and the section name. It is currently not used. The special naming convention is applied when the CDFSetAttribute method is called with the appropriate parameters (currently in the document 76 Reference Models lifecycle transitions as it is processed) The trial conditions are evaluated during placeholder reconciliation processing to determine if the artifact is appropriate for the study and whether or not a placeholder should exist. For each artifact unique name, add the appropriate row to this dictionary. Extending Taxonomies Each taxonomy can be represented by a table, similar to a dictionary, but the values allowed in each column is determined by the values within a dictionary. In Documentum eTMF, you must extend the following taxonomies. TMF Artifacts by Model The following table lists the artifacts in this taxonomy. Table 15. Extending the reference model - TMF Artifacts by Model Name Description TMF Models Name of the model that this artifact belongs to. The product comes with a single DIA TMF 2.0 reference model. While it is possible to support multiple models, for simplicity, extending the DIA TMF 2.0 reference model is described. TMF Unique Artifact Names Unique name of the artifact. For each unique artifact name, add the appropriate row to this taxonomy with DIA TMF 2.0 in the TMF Models column. TMF Classification by Artifact The following table lists the artifacts in this taxonomy. Table 16. Extending the reference model - TMF Classification by Artifact Dictionary Name Description TMF Models Name of the model that this artifact belongs to. TMF Unique Artifact Names Unique name of the artifact. TMF Artifact Names Base name of the artifact this artifact belongs to. TMF Zones The zone this artifact belongs to. TMF Sections The section this artifact belongs to. TMF Artifact Numbers Artifact number of this artifact (zero padded). TMF Inclusion Requirement States Default inclusion rule for the artifact. This can be overridden in the fileplan spreadsheet. 77 Reference Models Dictionary Name Description TMF Investigator Required Flags Flag to indicate if investigator metadata should be required on documents. TMF Subject Required Flags Flag to indicate if subject metadata should be required on documents. TMF Submissible Flags Flag to indicate if document is submissible (not currently used). TMF Investigator Access Role access to give investigators. TMF Inspector Access Role access to give inspectors. TMF External Contributors Role access to give external contributors. TMF External Reviewers Role access to give external reviewers. For each unique artifact name, add the appropriate row to this taxonomy with DIA TMF 2.0 in the TMF Models column and the appropriate values in the remaining columns. Creation Profile To include new artifacts in placeholders, you must extend the TMF Documents by TMF Unique Artifacts creation matrix. This creation matrix is based on TMF Unique Artifact Names as the dictionary that drives list of artifacts. For each unique artifact name, add the appropriate row to this matrix. Generally using the same values for the settings as the existing rows in the matrix. File Plans and File Plan Templates A file plan is a Microsoft Excel spreadsheet specifying the expected artifacts in each filing area. The file plan specifies whether artifacts are required (must-have), recommended (should-have), or optional (could-have) documents. In Documentum eTMF, the TMF File Plan Templates - Trial-level Excel spreadsheet is used as the base when file plan templates are created. Each new artifact needs to be placed in the file plan to be activated. If the artifact is to be included in every study, you can place it in the master template. Alternately, it can be placed in a specific template or file plan as any artifact within the system. The EMC Documentum Electronic Trail Master File User Guide provide more information about file plans. 78 Reference Models Implementing a Custom Reference Model (eTMF) To implement a custom reference model in Documentum eTMF, follow these steps: 1. Update the dictionaries. 2. Update the taxonomies. 3. Update the creation profile matrix. 4. Update the master file plan template, and any file plans templates if required. 5. Restart the Java Method Server. As an example, assume that we are adding the following new artifact to the reference model. Table 17. Extending the reference model - sample new artifact Artifact Name Value Base Artifact Name Base One Zone New Zone 1 Section New Section 1 Artifact Number 20.20.01 Using this example, we will modify the dictionaries, taxonomies, creation profile, and file plans. Dictionaries The simplest way of modifying the dictionaries is to export the values as an Excel spreadsheet and then import them back. After importing the spreadsheet, click the Update repository button to ensure the changes are available. The first column should be set to “1” to indicate “Enabled.” 79 Reference Models TMF Zones Add the new zone “New Zone 1” in the dictionary spreadsheet. TMF Sections Add the new section “New Section 1” in the dictionary spreadsheet. 80 Reference Models TMF Artifact Number Add the new artifact number 20.20.01 in the dictionary spreadsheet. TMF Artifact Names Add the base name, Base One, to the dictionary. 81 Reference Models TMF Unique Artifact Names Add the artifact name, Demo Artifact One, to the dictionary. Taxonomies When importing an updated taxonomy, if you get a message that a value does not exist in the dictionary, it might be because the repository has not been updated. Navigate back to the dictionary and click the Update repository button. TMF Artifacts by Model Add the unique artifact to the taxonomy. TMF Classification by Artifact Add the unique artifact to the taxonomy using appropriate values for the other columns. 82 Reference Models Creation Profile Add the new artifact to the TMF Documents by TMF Unique Artifacts creation matrix For large creation matrices, it might be simpler to export the configuration, modify the XML and re-import it. File Plan and File Plan Template Add the new artifact to the affected file plans. You may have to refresh the schema of the file plan for the new artifact to appear. Alternately, you can edit the schema with the new artifacts. In this example we modify the file plan of a specific study and add the artifact. By refreshing the study, we can then see the artifact placeholders added to the folder structure. After you restart the Java Method Server, you must refresh the study in the D2-Client. Note that the placeholder uses the tmf_artifact_name Base One. 83 Reference Models The artifact_name is set to Demo Artifact One. 84 Chapter 5 Document Creation Profile This chapter contains the following sections: • Management Creation Profiles, page 85 • Document Creation Profiles, page 86 • Control Category Definition, page 88 • Default Values Template, page 88 • Customizing Creation Profiles, page 90 • File Naming and Versioning, page 93 • O2 Configuration for PDF and Native Annotations, page 93 The Life Sciences solutions provide several D2 creation profiles to enable users to create and import documents and registration forms. There are one or more creation profiles for each Documentum R&D and Documentum eTMF domain. There is no manager role in Documentum Q&M as registration forms are not currently used in this solution. Management Creation Profiles Management creation profiles enable users in a manager role to create registration forms and other management related documents, such as content templates and Trail Master File (TMF) bulk import/export packages, in the manager’s domain. Table 18. Management Creation Profiles Creation Profile Available to Role Clinical Trial Management Artifacts cd_clinical_trial_managers Clinical Template Management Artifacts cd_clinical_template_authors Non-Clinical Study Management Artifacts cd_non_clinical_study_managers Non-Clinical Template Management Artifacts cd_non_clinical_template_authors Product Management Artifacts cd_product_managers Quality Project Management Artifacts cd_quality_project_managers Quality Template Management Artifacts cd_quality_template_authors 85 Document Creation Profile Creation Profile Available to Role Regulatory-Admin Management Artifacts cd_regulatory_managers Regulatory Template Management Artifacts cd_regulatory_template_authors Safety Template Management Artifacts cd_safety_template_authors TMF Clinical Trial Management Artifacts (eTMF solution only) cd_clinical_trial_managers TMF Clinical Template Management Artifacts (eTMF solution only) cd_clinical_template_authors GMP Template Management Artifacts cd_gmp_template_authors Document Creation Profiles Multiple document creation profiles, for each document domain, enable end users to create or import documents for the applicable domain. The DIA EDM reference model categorizes documents according to the taxonomy, domain/group/subgroup/artifact. For the creation profiles relevant to the DIA EDM reference model domains: Regulatory/Admin, Quality, Non-Clinical, and Clinical, there is a creation profile for each DIA EDM group within the applicable domain. Note: One creation profile per DIA EDM Ref Model group is a general pattern used within the solutions but there are exceptions. For example, the Regulatory/Admin groups are Applicant Information and Administrative Information. Artifacts for both of these groups are defined within 86 Document Creation Profile a single creation profile: Regulatory Documents by EMD Artifact Name. There is not a separate creation profile for each group. Within each creation profile, the individual document types map to artifacts. Each creation profile has an associated D2 dictionary that defines the document types (that is, artifacts) for the relevant domain and group. For Quality and Manufacturing domains, the individual document types within each creation profile map to groups rather than artifacts. 87 Document Creation Profile Control Category Definition The control category for each artifact is defined within the creation profile through the assigned Default Values template and lifecycle. The Default Values template and lifecycle must always refer to the same control category number. In the example, the Directive artifact in the Q&M Governance and Procedures domain will be created as a Control Category 1 document. The assigned Default Values template ensures that the category attribute is assigned the value 1. The document then matches contexts with the condition, category=’1’. This ensures the correct Control Category 1 configurations are applied to the document at runtime. Default Values Template A pertinent Default Values template is assigned to each document type within the creation profiles. The following screenshot is an example of a Default Values template, which is assigned to Control Category 1 Quality Drug Product artifacts: 88 Document Creation Profile The Life Sciences solutions depend on correct default values to function correctly. The following table lists attributes that must have default values when a document is created. Table 19. Required default values Attribute Default Value Runtime Use authors User creating document Used in security configuration to ensure that the user that created the document continues to have WRITE access to the Draft document. category Control Category 1,2,3, or 4 Determines the lifecycle and workflows available for the document. domain Document domain (for example, Quality, Clinical, Non-Clinical, Regulatory) Used along with artifact_name to look up applicable content templates. 89 Document Creation Profile Attribute Default Value Runtime Use group_name Group prefix corresponding to domain (for example, cd_quality, cd_clinical, cd_non_clinical, and so on) Used in value assistance queries for role attributes on the document and for potential workflow performers. primary_group Required for artifacts within DIA EDM reference model group-specific creation profiles. The value is the applicable DIA EDM reference model group. Ensures that the primary_group is defaulted during creation based on the user’s selected creation profile. Customizing Creation Profiles You can customize creation profiles in the following ways: • Create a new creation profile. • Change creation profile properties. • Change creation properties for an artifact within an existing creation profile. • Add additional artifacts to an existing creation profile. • Remove artifacts from an existing creation profile. • Remove or disable an existing creation profile. Prior to adding additional artifacts to a new or existing creation profile, you must create any of the following configurations that will be referenced in the creation profile: • Object types • Dictionaries or added dictionary values • Property pages • Inheritance configurations • Default values templates • Lifecycles Creating a New Creation Profile 1. In D2-Config, click Creation > Creation profile. 2. Click New. 3. Under Properties, enter the profile details, such as name, description, list of applications, and dictionary properties. 4. Click Save. 90 Document Creation Profile Changing Creation Profile Properties 1. In D2-Config, click Creation > Creation profile. 2. Under Profiles, select the creation profile you want to update. 3. Under Properties, change the relevant properties. 4. Click Save. Changing Creation Properties for an Artifact within an Existing Creation Profile 1. In D2-Config, click Creation > Creation profile. 2. Under Profiles, select the creation profile you want to update. 3. Add your custom application name to the Applications list. 4. In the Dictionary table, update the rows for a particular artifact. 5. Click Save. Adding Artifacts to an Existing Creation Profile 1. In D2-Config, click Creation > Creation profile. 2. Select the creation profile you want to modify and make a note of the dictionary that is used to define the documents that can be created. For example, the Quality Drug Product Artifact Names dictionary is used as an example: 3. Edit the dictionary. Add the names and labels of your new artifacts to this dictionary. 4. Reopen to the creation profile. 5. Add your custom application name to the Applications list. 91 Document Creation Profile 6. In the table, create a new row for each new artifact and select the following values in their respective columns for each new row: a. First column: Select a dictionary item from those you added in step 3. b. Type column: Select the object type for the new document that will be created when a user selects this item in the creation profile. If you created your own custom type, you can specify the custom type. c. 02 config column: Leave blank. d. Property pages column: Select the property page configuration that should be displayed during creation or import for this item. e. Version column: Typically, you should select 0.1. This value ensures that the first effective version of the document is version 1.0, while all draft or pre-effective versions are 0.x. f. Inheritance column: Select an appropriate D2 inheritance configuration. If you created your own inheritance definition, select the custom inheritance definition. g. Default Values Template column: Select a Default Values template that corresponds to the specific artifact, its domain, and/or its group and the desired control category. h. Lifecycle column: Select the lifecycle corresponding to the desired control category for the document. This must correspond to the Default Values template. If you created your own lifecycle definition, select the custom lifecycle definition. i. 7. Workflow column: Leave blank. Click Save. Removing Artifacts from an Existing Creation Profile 1. In D2-Config, click Creation > Creation profile. 2. Add your custom application name to the Applications list. 3. Remove the unwanted rows from the table at the bottom of the page. 4. Click Save. Removing or Disabling an Existing Creation Profile 1. In D2-Config, click Creation > Creation profile. 2. Under Profiles, select the creation profile that you want to delete. 3. In the Confirmation message box, click OK. 92 Document Creation Profile File Naming and Versioning The document name is automatically assigned based on the naming schema: <artifact name> - <document ID> Where the artifact name is 230 characters and the document ID is a 9 digit incremental number. The naming rules ensure that documents are named consistently. For example, when the artifact name is Cover Letter and the document ID is 000000001, the name displayed in the D2 Client workspace is: Cover Letter - 000000001 Caution: The system generates the document_id from a 9-digit counter, which allows 100 million unique document IDs. In D2-Config, the size of the counter can be increased by editing the _Document_ID auto naming configuration. However, the document_id attribute in the cd_controlled_doc object type is a ten character string. When the digits are increased above 10, the cd_controlled_doc object type must also be changed. If the counter value on the _Document_ID auto naming configuration is reset after creating documents, subsequent document IDs might not be unique. Consequently, you should not reset this counter value in a production repository. If two autonaming configurations have the same prefix, the system does not validate the configurations for existing documents. This can result in duplicate document names in the system. For example: • QUA - Quality • QUA - Qualitative Use Assessment You can avoid this by defining a different prefix for the document in the respective Prefixes dictionary in D2-Config. Document versions are minor (v 0.1) until they are made effective. Documents in an Effective/Approved/Final state have major version numbers (v 1.0). O2 Configuration for PDF and Native Annotations If you use PDF annotations in your documents, you must avoid using O2 trigger events other than the Checkout/Checkin event. This is because O2 events update the content and, if PDF annotations exist on the document, these updates cause the annotations to be deleted prior to the author being able to view them. In addition, when a user updates a document’s properties, the updated properties will not be in sync with the content of the object until the user checks out the document and checks it back in. By default, the Life Sciences solution supports only the Checkout/Checkin O2 trigger events. Other O2 trigger events or updating the content during lifecycle transitions will only work with native annotations and not PDF annotations. For example, updating the last periodic review date on an 93 Document Creation Profile Approved document or updating the Product Code that then cascades down to the documents. The EMC Documentum D2 Installation Guide provides information about O2 configurations. 94 Chapter 6 Registration Forms This chapter contains the following topics: • Overview and Form Types, page 95 • Creating Custom Registration Form Types, page 97 Overview and Form Types When document Authors create a new document, they associate it with an existing registration form. The registration form specifies the product codes, trial IDs, project names, default role assignments, and other property values that can be selected in the new document’s properties dialog box. Each R&D and eTMF document type that can be directly created by users has a corresponding registration form subtype. This does not apply to Q&M documents or Change Requests. Registration forms can be associated with a document in one of two ways: • The user selects the registration form before importing or creating a document. • The user selects the ID (for example, product_code, clinical_trial_id, project_name, and so on) of the registration form in the properties dialog for the new document during creation or import. Documents can inherit from multiple registration forms. Chapter 7, Attribute Inheritance and Cascading Attribute Rules provides more information about how to configure documents to inherit properties from registration forms. Most registration forms are contentless documents with the exception of the TMF Clinical Trial Registration Form. In this case, the content of the registration form is the TMF File Plan spreadsheet. Registration forms have their own lifecycle and security configurations. Registration forms serve the following purposes: • Define the product code names, trial ID numbers, project names, and so on, that can be selected in document properties dialog boxes (on the Classification tab) when a new document is created or imported. • Provide default metadata that can be inherited by the relevant documents. This simplifies the document creation process for the Authors and reduces the amount of metadata to be filled-in by the end-user. • Define default role assignments (for example, Reviewers, Approvers, Coordinators, and so on) to apply to the relevant documents. 95 Registration Forms • Enable the overall status of a product, trial, or project to be indicated by the appropriate Managers. • Enable an entire product, trial, or project to be locked down if necessary, in order to prevent additional documents from being made “Effective” (perhaps temporarily). Registration forms are set up by the high-level Management team, that is, Product Managers, Regulatory Managers, Clinical/Non-Clinical Trial Managers, Project Managers in the R&D Quality area, and Corporate Administrators. Only these users can create and modify the forms. In general, these forms provide an overarching governance mechanism that can be used at the Management level, over and above the role-based access controls applied at the individual document level. The following table shows the available registration forms, the registration form object type, and the type of object that inherits properties from this kind of registration form. Table 20. Registration form types Registration Form Name Registration From Type Target Object Type(s) Inherit from Registration Form Country Registration Forms (eTMF solution only) cd_clinical_country_info cd_clinical_tmf_doc Site Registration Forms (eTMF solution only) cd_clinical_site_info cd_clinical_tmf_doc Clinical Trial Registration Forms cd_clinical_trial_info cd_clinical Non-Clinical Study Registration Form cd_non_clinical_study_info cd_non_clinical Product Registration Forms cd_product_info cd_clinical_tmf_doc cd_clinical_tmf_doc cd_clinical cd_non_clinical cd_quality cd_reg_admin Project Registration Forms cd_quality_project_info cd_quality Regulatory Application Registration Forms cd_reg_admin_info cd_reg_admin Regulatory Activity Package Registration Form cd_reg_admin_activity_info cd_reg_admin 96 Registration Forms In most cases, each registration form object type extends the relevant target object type (that is, the document object type to which the form pertains) for the following reasons: • Optimizes query performance since there are usually fewer instances of registration forms than documents, so the queries used to populate the product, trial, or project codes work efficiently. • Facilitates D2 configuration, enabling D2 contexts to be used to restrict certain configuration elements to registration forms (for example, attachment of property screens, lifecycles, and security models). • Provides the ability to add attributes specific to the registration form but not the target documents. It is possible to extend the configuration to support other types of registration forms if necessary. Creating Custom Registration Form Types You can create a custom registration form type for a new type of document or to support an additional level of inheritance to existing document types using the following steps: 1. Create a new object type for the registration form type. By convention, the object type name should have the _info suffix and as a best practice, the object type name should be prefixed according to your organization’s naming convention. For example, if you are adding a registration form for marketing materials for KB Pharmaceuticals, name the target object type kb_marketing and the registration form subtype kb_marketing_info. The object type should also have an attribute that can be used as an identifier. This will be the key attribute when associating a document with the registration form. 2. Add the registration form name to a D2 dictionary. This dictionary value is used in a creation profile to enable users to create instances of the registration form. For example, create a dictionary, Marketing Management Artifacts, with a key value and language label value: Marketing Registration Form. Alternatively, if you are adding the registration form to an existing creation profile, modify the existing dictionary that is associated with the existing creation profile. 3. Create a property page configuration for the registration form. 4. Create an inheritance configuration to be used during creation of the new registration form if needed. This step refers to inheriting configurations from an existing registration form to your new registration form. For example, the Marketing Registration Form might inherit from a selected Product Registration Form. You can also use a standard solution inheritance configuration rather than create a custom one. 5. Create a D2 inheritance configuration that defines the attributes that will be inherited from the new registration form to target documents. 6. Create a Default Values template to be used during creation. Ensure that all of the mandatory default properties described in the Default Values Template, page 88 are defined. 97 Registration Forms 7. Create a lifecycle configuration for the new registration form type if desired. You can also use an existing registration form lifecycle if it applies. 8. Create a creation profile that enables creation of the new registration form type. Alternatively, add the new registration form to an existing creation profile. Customizing Creation Profiles, page 90 provides more information. 98 Chapter 7 Attribute Inheritance and Cascading Attribute Rules This chapter contains the following topics: • Auto-Inherited Attribute Rules, page 99 • Configuring Auto-Inherited Attribute Rules, page 100 • Configuring Cascading Attribute Rules, page 106 • Extended Attribute Expressions, page 110 • Special Naming Conventions, page 116 • Preconfigured Cascading Attributes Rules, page 116 • Using a Custom Attribute Inheritance Rule to Reapply D2 Configurations to Selected Objects, page 119 Auto-Inherited Attribute Rules The Life Sciences solutions use standard D2 inheritance configurations but they also introduce a flexible mechanism called Auto-Inherited Attribute Rules. The following table summarizes the differences between these two mechanisms. Table 21. Comparisons between D2 inheritance and Auto Inherited Attribute Rules D2 Inheritance Auto-Inherited Attribute Rules Configured in D2-Config. Configured in D2-Client by creating an Auto-Inherited Attribute Rules (cd_auto_inherit_config) object and setting its properties. cd_auto_inherit_config does not delete empty folders or update versions other than the current one. When configuring auto-inheritance and cascading attribute rules, run the following DQL to set the immutable flag on the type. This is applicable for all the types for which the rules 99 Attribute Inheritance and Cascading Attribute Rules D2 Inheritance Auto-Inherited Attribute Rules are being configured. A sample DQL query for the "cd_non_clinical" object type with the attribute swy_study_category is as follows: alter type cd_non_clinical modify swy_study_category(set ignore_immutable=-1) publish; Requires the user to preselect the source document before initiating a new or import operation. Inheritance is based on the product code, trial id, study id, project name, and so on, that the user selects in the Properties dialog box during creation or import. The source object for inheritance is identified through a query defined within the Auto-Inherited Attribute Rules object. Therefore, it is not necessary to preselect a source document. Documents can only inherit from the selected document. Documents can inherit from more than one document. They inherit from all documents that match a configured source query qualification. Applied by the D2 runtime before displaying the Properties dialog box during document creation or import. Applied by the Life Sciences solution server-side logic after the document is created and the initial lifecycle state actions executed. Therefore, the inherited attribute values will not be shown in the Properties dialog box during creation or import. Consider configuring the property page such that fields that will be inherited through this approach are not visible during creation. Allows copying an attribute value from the selected document to a new document. Provides for configurable inheritance rules. Documents can inherit attributes from multiple sources. You can merge or override attributes, can transfer attributes to different attributes, and can apply conditional inheritance rules, depending on the object type and/or properties of the target object. Configuring Auto-Inherited Attribute Rules 1. Log in to D2-Client as a user in the cd_admingroup role. 2. Click New > Content. 3. Select the System Administration creation profile. 4. In the System Administration list, select Auto Inherited Attributes Rule and click Next. 5. In the Name field, type a name for the configuration. 6. On the Rule applicability tab, configure the following fields. 100 Attribute Inheritance and Cascading Attribute Rules Option Description Enabled Check if this auto-inheritance configuration is enabled. If unchecked, it is ignored at runtime. Automatically applies to new objects Check if this auto-inheritance configuration should be applied automatically whenever objects of the specified types are created. If unchecked, the configuration is only applied if it is explicitly called from a lifecycle action. Order of precedence Specifies the order of precedence for this rule in relation to other rules that may be applicable. Rules are applied in increasing order of precedence that is, a precedence value of 0 denotes the highest precedence, 1 is the next highest; and so on. When two or more applicable rules have the same level of precedence, they are applied in alphabetical order of object_name. The order in which the rules are applied and if a subsequent rule depends on a value being already set can be significant. For example, if two or more rules are configured to set default values, the first rule will override any subsequent rules. 7. Applies to object_types Defines the optional list of target object types that this rule can apply to. Where defined, if the target object is not one of the specified object types (including subtypes), it is ignored. If undefined, the rule can apply to any target object. Condition qualifier (optional) Specifies an optional DQL qualifier that must be satisfied for the target object in order for the rule to apply. For example, the condition product_code is not null ensures the rule only applies to documents that have defined product_code values. On the Inherit from tab, configure the following fields. Option Description Inherit from Specifies the source object(s) that are used to provide the values to be inherited. The object(s) are in terms of a DQL qualifier. This can refer to attribute values of the target object using the $value(...) notation within the qualifier, as in standard D2 configurations. For example, cd_product_info where product_code = ‘$value(product_code)’ uses a cd_product_info source object with a product_code value matching that of the target object. The $quotedvalue(...) notation can also be used to safely refer to attributes that could potentially have embedded quotes in them. For example, the preceding qualifier could also be written as follows: 101 Attribute Inheritance and Cascading Attribute Rules Option Description cd_product_info where product_code = $quotedvalue(product_code) If you use the $quotedvalue(...) form, the value is quoted automatically, with internal quotes doubled-up so that the DQL clause is syntactically-correct. If the specified attribute is a repeating attribute, you can use the plural form $quotedvalues(...) to generate a series of comma-delimited, safely-quoted strings, which can be referenced in a DQL “in” clause. For example, cd_non_clinical_trial_info where any study_num in ($quotedvalues(study_num)) If the resulting DQL qualifier identifies multiple source objects, the inheritance rules are applied to each source object in turn, in the order in which they are returned by the qualifier. Use an order by clause in the qualifier if necessary, to ensure the source objects are taken in the appropriate order. To implement folder-based inheritance, a qualifier of the following form can be used: <folder_object_type> where r_object_id in ($quotedvalues(i_folder_id)) Where <folder_object_type> is the appropriate object type. This enables the target object to inherit attribute values from the parent folder(s) after it has been created and auto-filed in the repository. However, if the target object is linked to multiple parent folders, the order in which the parent folders are retrieved is not deterministic, and the target object may inherit values from the wrong folders as a result. To counter this, the source parameter can be set to the special value PARENT_FOLDERS, which applies parent folder inheritance in strict order, so that the primary folder is used first, followed by any secondary folders. The special value PRIMARY_PARENT_FOLDER can also be used to enforce folder inheritance from the primary folder link only. 8. 102 On the Inherit to tab, configure the following fields. Attribute Inheritance and Cascading Attribute Rules 9. Option Description Inherit to Specifies the target object(s) on which the inheritance rules are to be applied. The default setting is SELECTED. This enables attribute inheritance to be applied to one or more objects related to the selected object (the object specified by the –id argument) as opposed to the selected object itself such as its parent folders. For example, to propagate attributes from the currently-selected object to its parent folders along the folder path towards the cabinet level, set source to SELECTED and target to ALL_FOLDERS for the tmf_folder object type . For checked-out objects Specify how currently checked-out items should be handled. If you use the Bypass lock temporarily option, the existing check-out locks are reinstated after the update, enabling users to continue to work on checked-out documents. On the Attributes tab, configure the following fields. Option Description Attributes Specifies the list of attributes to be inherited from the source object(s) to the target object. Each entry is of the form: [<update-mode> ]<targetAttribute> [= <sourceAttribute> | :<literal-value>] where <update-mode> is: default – apply the inheritance only if the current target attribute value is undefined (for example, a blank string) or zero. merge – merge the attributes of the source and target, avoiding duplicates. (This only applies to repeated attributes – if applied to single-valued attributes, the effect is the same as default.) replace – (default) discard the existing target attribute value(s), if any, and replace it with the source attribute values. This is the only valid option if batch update mode is used. Update Mode Specifies how the identified target objects are to be updated: Serial (default) – target objects are processed in sequence, in the defined order. Parallel – target objects are processed in parallel using the concurrent method handling framework. Batch DQL – target objects are updated as a group using a DQL update query. This option is only valid if a single source object is specified, the target objects are specified in terms of a DQL qualifier, and the attributes list specifies only replace operations. 103 Attribute Inheritance and Cascading Attribute Rules 10. On the Folder updates tab, configure the following fields. Option Description Update Folders Specifies a set of folders that should be moved or renamed after updating the attributes of the target object, in the form <source-folder-path>|<DQL-qualifier> => <new-folder-path>|<new-folder-name>. Attribute expression functions prefixed by the “$” symbol can be used to refer to attributes of the context object (the first source object, by default). For example, /Clinical/$arg(old_value)=$new_value renames a product-level folder in the Clinical cabinet. Attribute expression functions prefixed by “@” can also be used in the right-hand side of the expression to refer to attributes of the existing folder. For example, dm_folder where folder('/Clinical Trial Library/$arg(new_value)', descend) and object_name like '$arg(old_value) -%' => @replace("@value(object_name)","$arg(old_value) -","$arg(new_value) -") renames all sub-folders below /Clinical Trial Library/<new-value> beginning with “<old-value> -”, replacing <old-value> with <new-value> in the existing folder names. If a folder path is specified in the right-hand side, the existing folder is renamed if necessary and then moved into the specified target folder, which is created automatically if necessary. For example, /Clinical/$arg(old_value)/$value(product_code)=> /Clinical/$arg(new_value)/$value(product_code) moves an existing product-level folder to a new parent folder. The folder type can also be specified in curly braces in the right-hand path if necessary. For example, /Clinical/$arg(old_value)/$value(product_code)= /Clinical/{tmf_folder}$arg(new_value)/$value (product_code) creates a new folder of type tmf_folder below the Clinical cabinet if necessary, instead of using the default folder type (dm_folder). Renaming and moving existing folders in this way can remove the requirement to apply D2 auto-linking rules to the individual subordinate objects. Multiple folders to be renamed can be specified; if the specified source folder does not exist, the setting is logged as a warning and disregarded. 11. On the Deletion tab, configure the following fields. 104 Attribute Inheritance and Cascading Attribute Rules Option Description Delete Empty Folders Select this option if you want to delete empty folders after applying D2 auto-linking or deleting objects, that is, where a document is moved from its current folder to some other location, and there are no other documents in the original folder. Delete Target Objects Where Use this setting to selectively remove redundant objects identified in terms of a DQL qualifier or Boolean attribute expression (that is, an attribute expression returning a ’’true’’ or ’’false’’ value). For example, either the DQL qualifier r_object_type = ’cd_product_info’ or the attribute expression @eq(@value(r_object_type),cd_product_info) can be used to delete Product Registration Forms. If the update mode is set to Bulk DQL, a DQL qualifier must be specified here; otherwise, it is more efficient to use an attribute expression. Within the attribute expression, use expressions to refer to attributes of the context object (the first source object, by default) and @value() expressions to refer to attributes of the target object in each case. The wildcard symbol * refers to all target objects. Note that the selection is made before inherited attributes are applied, so the DQL qualifier or attribute expression should refer to the current object values, not the new values. 12. On the Post-processing tab, configure the following fields. Option Description Reapply D2 Auto-Naming Where Specifies a sub-set of the modified target objects that should be auto-named after updating them, in terms of either a DQL Qualifier or a rule expression (i.e. an expression that evaluates to either true or false, as appropriate). As for update_folders, “$” or “@” function prefixes can be used within the rule expression to refer to attributes of the context object or modified target object, respectively. For example, @endswith(@value(r_object_type),_info) causes D2 auto-naming to apply to all modified target objects with an object type ending in “_info”; that is , all registration form object types, but not others. The wildcard value * can be used to apply D2 auto-naming to all modified target objects. If null or undefined, D2 auto-naming is not applied to any of the modified objects, unless –apply_d2_configs true is specified explicitly in the method arguments. Reapply D2 Auto-Linking Where Specifies a sub-set of the modified target objects that should be auto-linked after updating them. 105 Attribute Inheritance and Cascading Attribute Rules Option Description Reapply D2 Security Where Specifies a sub-set of the modified target objects that should have D2 security configurations applied after updating them. Apply Custom Processing Where Specifies a sub-set of the modified target objects that should have custom processing applied after updating them. Class Path of Custom Plug-in The post-processing plug-in class to invoke for each qualifying object, if any. Specify the fully-qualified class path. For example, com.documentum.cdf.plugins .MyPluginClass. Additional plug-in arguments Specifies additional arguments for the custom plug-in. 13. Click Next. The EMC Documentum Controlled Document Foundation Developer API Javadocs provides more details. Configuring Cascading Attribute Rules During document creation or import, a document inherits a set of attributes from a corresponding registration form. For example, if you create a non-clinical document, the system requires you to associate the document to a Non-clinical Study Registration Form. The individual document inherits a set of product and study information from the registration form. But what happens if the information on the registration form changes after you create the document? The Life Sciences solution Cascading Attributes functionality enables you to update existing documents for searching and reporting purposes. You also have the option to leave existing documents unchanged for compliance reasons. For example, there may be cases where you want the related documents to take on the new attribute value from the registration form, such as the addition of a generic name to a product registration. There may be other cases where you do not want the existing documents to take on the new value of the attribute, but only new documents, such as the changing of a Principal Investigator at a trial site. And there may still be other cases where you not only want the attribute to be saved on the existing documents, but you would like to have business logic invoked to properly represent the change to the registration form. See Appendix D, Visual Representation of Attribute Cascading in Life Sciences for a visual representation of how the attributes are cascaded from the registration forms to the documents. This section defines how to configure the Cascading Attribute rules. By default, the Life Sciences solutions come with preconfigured cascading attribute rules. Preconfigured Cascading Attributes Rules, page 116 provides more information. To configure the Cascading Attributes rules: If you modify the cascading attribute rule settings (the cd_auto_inherit_config objects in the /System/CDF/Auto Attribute Inheritance Config folder), restart the Documentum Java Method Server service on each Content Server node in order to pick up the changes. 1. Log in to D2 Client as a member of cd_admingroup. 2. From the Repository browser, navigate to System/CDF/Auto Attribute Inheritance Config. 106 Attribute Inheritance and Cascading Attribute Rules 3. Right-click an auto inheritance configuration object in the folder, such as Change Product Code, and select Properties. 4. Select Enabled to enable this configuration rule or clear the check box to disable it. 5. On the Rule applicability tab, configure how to apply the rule to object types as described in the following table: Field Description Automatically applies to new objects Select whether the system applies the rule automatically when users create the specified object type. Clear this option if the rule applies explicitly as part of a lifecycle transition action. For example, in the Change Product Code function. Order of precedence Select the order of precedence for this rule when there are other applicable rules. The system applies rules with the highest order of precedence first. If two or more applicable rules have the same order of precedence, the system applies the rules in alphabetical order by object_name. The order in which the rules apply can be significant. For example, if two or more rules set default values, the first rule overrides any subsequent rules. 6. Applies to object types Select the object type or types that apply to this rule. For example, Change Product Code applies to the cd_product_info object type. Condition qualifier (optional) Type an optional DQL qualifier to satisfy before applying the rule to the object type. For example, the condition product_code is not null ensures that the rule only applies to objects with defined product-code values. On the Inherit from tab, in the Inherit from field, type the source objects that provide the inherited values: • SELECTED: Inherit values from the currently selected object. • PRIMARY_PARENT_FOLDER: Inherit values from the immediate primary parent folder of the selected object. • PARENT_FOLDERS: Inherit values from each immediate parent folder of the selected object, starting with the primary folder. • ALL_FOLDERS [<DQL-qualifier>]: Inherits values from all direct and indirect parent folders, from the first parent folder to the cabinet level, that match the specified conditions, if any. For example, ALL_FOLDERS tmf_folder where product_code != ’ ’ inherits values from all direct and indirect parent folders of type tmf_folder with non-blank product_code values. • <DQL-qualifier>: Inherits values from the specified objects in terms of a DQL qualifier. You can use $-expressions within the DQL qualifier to refer to attribute values of the selected object, if necessary. For example, the Inherit Clinical Trial Registration Form Info rule 107 Attribute Inheritance and Cascading Attribute Rules uses the DQL qualifier: cd_clinical_trial_info where clinical_trial_id = $quotedvalue(clinical_trial_id) If you leave this field blank, the system uses SELECTED as the default. 7. On the Inherit to tab, configure target object inheritance as described in the following table: Field Description Inherit to Type the target objects that inherit the relevant attribute values. The selection options are the same as for the source objects in the Inherit from field. For checked-out objects 8. Select how to handle checked-out items. On the Attributes tab, configure attribute inheritance as described in the following table: Field Description Attributes Specify the list of attributes to inherit from the source to the target objects. In each case, specify: • default: where the attribute value should be set by default, if it does not currently have a value. • replace: if the attribute value should always overwrite the current value. • merge: With repeated attributes, it enables the current values to combine with new inherited values, without duplicates. For example, to combine values from two or more registration forms. For example, merge keywords adds keywords from the source object or objects that are not currently listed in the keywords repeated attribute. If default, replace or merge is not specified, the system uses replace. It is also possible to inherit attributes from a different attribute of the source object if necessary, by appending =<source-attribute>. For example, replace title=study_title copies the value of study_title from the source object to the title attribute of the target object. A literal value can also be specified using the :<value> notation. For example, replace log_entry:Created by user $USER. You can use $-expressions in the value to refer to attributes of the source object. You can modify the predefined rules if necessary to include custom attributes, where you have added them 108 Attribute Inheritance and Cascading Attribute Rules Field Description to the standard object model. For example, the Inherit Clinical Trial Registration Form Info rule defines the attributes inherited from Clinical Trial Registration Forms. Update mode Select the update mode to use to process the target objects. Serial update mode processes the target objects one at a time. Use this option if there is only one target object, or a small number of target objects to update. Parallel update mode processes the target objects concurrently. Use this option if there could potentially be many target objects to update and the attribute list contains default or merge entries. Batch DQL update mode processes the target objects as a group using a DQL update query. Use this option if there could be many target objects to update and the attribute list contains only replace entries. You can only use this update mode to replace (overwrite) attribute values. The following example shows the Attributes field for the Inherit Clinical Trial Registration Form Info automatic inheritance configuration object: 9. On the Folder Updates tab, specify the list of folders to move or rename. To move a folder and its contents to another location, specify <current-folder-path> => <new-folder-path> To rename a folder, specify <current-folder-path> => <new-folder-name>. In both cases, you can use $-expressions to refer to attributes of the source object, and you can use @-expressions to refer to attributes of the target folder. You can also use a DQL qualifier to specify the source folder if necessary. The following example shows the Folder updates field for the Change Product Code automatic inheritance configuration object: 109 Attribute Inheritance and Cascading Attribute Rules This example is for the Change Product Code rule. In the example, $arg(old_value) and $arg(new_value) refer to the old and new product code values, respectively. 10. On the Deletion tab, configure how to delete objects as described in the following table: Field Description Delete empty folders Select whether to the empty folders that remain after moving documents and folders to new locations. Delete target objects where Type a DQL qualifier or a Boolean attribute expression to remove redundant objects. 11. On the Post-processing tab, you can selectively apply Documentum D2 autonaming, autolinking, security, and custom post-processing to modified objects. Type a DQL qualifier, Boolean attribute expression, or the wildcard symbol * in the applicable fields. For example, in the Change Product Code rule, the system applies Documentum D2 autonaming to the relevant Product Registration Form and its associated Clinical Trial Registration Forms using the following DQL qualifier: r_object_type in (’cd_product_info’, ’cd_clinical_trial_info’) You can apply Documentum D2 autonaming, autolinking, and security selectively to the affected objects using this technique. The system applies the DQL qualifier to identify the target objects before applying the inherited attributes, but applies the Documentum D2 configurations after the objects update. (If there are multiple target objects to update, they process in parallel, regardless of the Update Mode setting.) It is also possible to apply custom processing to selected target objects using the Apply custom post-processing where field. For example, to apply custom autonaming to the affected objects, you can write a Java plug-in and install it in the Java Method Server lib directory. The EMC Documentum Controlled Document Foundation Developer API Javadocs provides details. 12. Click OK. Extended Attribute Expressions D2 supports a number of built-in functions for referencing attribute values within configuration settings such as $value(attribute). However, in some cases, additional functions are required. 110 Attribute Inheritance and Cascading Attribute Rules The Controlled Document Foundation (CDF) Layer, therefore, supports extended attribute expressions. These can be used in the following cases: • In various method arguments passed to CDF server methods in Apply Method lifecycle actions (for example, the –value argument to CDFSetAttributeMethod). • In the Source and Target DQL qualifiers of cd_auto_inhert_config objects, used in the CDFApplyAttributeInheritanceMethod The following extended attribute expression functions are supported. Table 22. Extended attribute expressions Extended Attribute Expression Functions Description $user Returns the context username. This is the name of the user who caused this function to be invoked. This is not necessarily the same as the session user name, as the method could be running as a privileged server method on behalf of the user. In this case, the D2 username should be passed to the method in the -context_user argument so that it can be passed to this method for use in this function. $value(<attribute>) Extracts the value of the specified attribute of the context object. For repeated attributes, a value index can be specified. For example, $value(r_version_label[0]) refers to the version number of the object in Documentum. If an index is not specified, a comma-delimited list of repeated attribute values is returned. $quotedvalue(<attribute>) Similar to $value(<attribute>), with the value(s) being surrounded by single-quotes and with internal quotes doubled-up. Use this form when referring to attributes that may have embedded quotes in them in DQL statements. $dqlvalue(<query>) Runs the specified DQL query and returns the result in the first row/column position, if any. Else, returns a blank string. For example, $dqlvalue(select count(*) from ls_tmf_doc where clinical_trial_id = $value(clinical_trial_id) and artifact_name = $quotedvalue (artifact_name) and is_placeholder = false returns the current number of documents of the same type as the document/placeholder itself in the same trial. 111 Attribute Inheritance and Cascading Attribute Rules Extended Attribute Expression Functions Description $datevalue(<attribute>, <format>) Returns a date/time attribute value in the specified format. In the format pattern, use MM to denote the month in year, and mm to denote the minute in the hour. The time part can be omitted if necessary. For example, $datevalue(r_modify_date,MM/dd/yyyy) returns the last modify date in US-style date format. $upper(<str>) Converts <str> to upper-case. $lower(<str>) Converts <str> to lower-case. $firstupper(<str>) Converts <str> to first-upper format, or proper-case; that is, the first letter of each word is capitalized. For instance, $firstupper("an example subject") returns “An Example Subject”. $left(<str>,<n>[,<suffix>]) Extracts the leftmost <n> characters from <str>, and appends the optional <suffix> (if specified) if the string is truncated. For example, $left("ABCDEFG",3,"...") returns “ABC...”. $right(<str>,<n>) Extracts the rightmost <n> characters from <str>. $before(<str>,<separator>) Extracts the left part of <str> up to but not including the sub-string <separator>. For example, $before("ABC.DEF",".") returns "ABC". $after(<str>,<separator>) Extracts the right part of <str> after but not including the sub-string <separator>. For example, $after("ABC.DEF",".") returns "DEF". $trim(<str>) Removes leading/trailing spaces from <str>. $length(<str>) Returns the number of characters in <str>. $maxlength(<attr>) Returns the maximum number of characters permitted for the specified string-valued attribute <attr> according to the object model. Not valid for non-string data types. $substring(<str>,<start>[,<n>]) Extracts up to <n> characters from <str> starting from position <start>, indexed from 1. If the third parameter is omitted, all characters from the specified start position to the end of the string are extracted. For example, $substring("ABCDEFG",3) returns "CDEFG", and $substring("ABCDEFG",3,2) returns "CD". 112 Attribute Inheritance and Cascading Attribute Rules Extended Attribute Expression Functions Description $replace(<str>,<find>,<replace>) Replaces all occurrences of <find> with <replace> in <str>. For example, $replace("ABC.DEF.GHI",".","-") returns "ABC-DEF-GHI". $if(<dql-qualifier>,<true-value>[,<false-value>]) Evaluates a condition expressed as <dql-qualifier> against the context object, and returns either <true-value> or <false-value> depending on whether or not the condition is satisfied. If the third parameter is omitted, either <true-value> or a blank string is returned, as appropriate. For example, $if("is_placeholder = true","Placeholder","Document") returns "Placeholder" if the context object is a placeholder, or "Document" if it is a document. $integervalue(<str>) Returns the numeric integer value of <str>; 0 if <str> is not a numeric value. This can be used to remove leading zeroes from a string of digits. For instance, $integervalue("0000256") returns "256". $inc(<n>) Returns the integer value n+1. $dec(<n>) Returns the integer value n-1. $add(<a>,<b>) Returns the sum of the integer values of a and b. For example, $add("256","1") is "257". $subtract(<a>,<b>) Returns the difference of the integer values of a and b. For example, $subtract("256","1") is "255". $position(<str>,<substr>) Returns the first position of <substr> in <str> in a left-to-right scan, indexed from 1; zero if the specified substring is not found. For example, $position("ABRACADABRA","BR") is "2". $lastposition(<str>,<substr>) Returns the first position of <substr> in <str> in a right-to-left scan, indexed from 1; zero if the specified substring is not found. For example, $lastposition("ABRACADABRA","BR") is "9". 113 Attribute Inheritance and Cascading Attribute Rules Extended Attribute Expression Functions Description $pad(<str>,<n>[,<padding-chars>]) pads <str> to <n> characters by inserting the first character of the specified <padding-chars> string (which defaults to the digit 0) at the start of the string as many times as necessary; for example, $pad("123","6") returns "000123". If <padding-chars> comprises two characters, then the second character is used to signify an overflow if the string exceeds the specified length. For example, $pad("100","2","0*") returns "**". $default(<str>,<default-value>) Returns <default-value> if <str> is a blank string; otherwise it returns <str>. For example, $default($value(title),"Title is undefined") returns the value of the title attribute if it is non-null, otherwise it returns "Title is undefined". $lookup(<str>,<dictionary>,<alias|locale>) Retrieves the value of <str> from the specified D2 dictionary, using the specified alias or locale code to retrieve the value. Use this function to convert strings to localized values or encoded values via D2 dictionaries. For example, $lookup("FR","TMF Countries","en") checks the en locale value (that is, English language value) of the country code FR in the TMF Countries dictionary. In this case, the result is "France". $list(<attribute>,<expression>[,<separator>]) Evaluates the specified expression for an attribute value or series of repeating attribute values and combines the results into a list. Within the expression string, the "~" (tilde) character must be used to prefix embedded attribute expression functions instead of the "$" (dollar) character. This is to prevent the attribute expression functions from being evaluated prematurely. Use ~item or ~item() to refer to the list item value in each case. The expression string must also be quoted if it contains embedded commas. For example, $list(keywords,"~upper (~left(~item,3))",",") takes the first three characters of each keyword attribute value defined for the context object, and converts them to uppercase, combining the values into a comma-separated list. If a separator is not defined, the values are concatenated without separators. 114 Attribute Inheritance and Cascading Attribute Rules Extended Attribute Expression Functions Description $case(<expression>,<matching-pattern -list>,<result-list>) Selects the ith value from <result-list>, where the value of <expression> matches the ith value in <matching-pattern-list>, comprising a comma-delimited list of literal values or regular expressions. If no matching pattern is found, a blank string is returned. If the last item in <matching-pattern-list> is “*” (the wildcard character), it will match any expression; in this way, the last value of <result-list> is returned by default. For example, $case($value(domain),’Clinical,Non -Clinical,*’,’Clinical Trial,Pre -Clinical Study,Other’) returns “Clinical Trial” if domain = Clinical, “Pre-Clinical Study” if domain = Non-Clinical, and “Other” if domain is some other value. Extends the dictionary lookup function to $lookup(<key -path>,<taxonomy>,<dictionary>[,<alias|locale>] retrieve a value from a D2 taxonomy. The first parameter begins with the path prefix character ) “/”, and specifies the location of a parent node in the taxonomy as a series of key values separated by “/” characters. The path “/” denotes the root node in the taxonomy. The second parameter is the D2 taxonomy configuration name. The third parameter denotes the subordinate D2 dictionary name used in the taxonomy for the required value, which may be several levels below the parent node, provided that the intervening levels in the taxonomy contain only one value. If multiple values are defined at the specified level, only the first value is returned. If an alias or locale is not specified in the fourth parameter, the subordinate key value itself is returned. For example, to lookup the corresponding artifact number for a particular TMF artifact in the DIA TMF 2.0 reference model, use $lookup(‘/DIA TMF 2.0/$value(artifact_name)’,TMF Classification by Artifact,TMF Artifact Numbers). Characters outside of function calls remain unchanged. Function names are not case-sensitive. Nested subexpressions can be specified in function argument lists, which are then evaluated recursively. There is no defined limit on the level of nesting that can be used. Function arguments should be quoted if they contain embedded commas, so that they are parsed correctly. Either matching single or double quotes can be used for these. For example, specify $substring(’$value(object_name)’,10,20) or $substring("$value(object_name)",10,20) if the object_name attribute value can 115 Attribute Inheritance and Cascading Attribute Rules potentially contain commas. Unrecognized functions are not processed, and are passed into the resulting string unchanged. Method arguments containing attribute expressions can be specified in D2 lifecycle configurations. However, D2 evaluates them where functions are recognized (for example, $value(...) and $dqlvalue(...) expressions) prior to passing the argument values to the method. To prevent D2 from doing this, the alternative function prefix symbol “@” is supported – for example, "@dqlvalue(select ... where ...)”. These expressions are not recognized by D2 and are passed to the method unresolved, so they can be evaluated by the method itself. The EMC Documentum Controlled Document Foundation Developer API Javadocs provides more details. Special Naming Conventions The Special Naming Conventions alias is supported in the TMF Unique Artifacts dictionary configuration in D2. The alias can be used to override the default naming conventions for placeholders and/or documents on a per-artifact basis. The alias values are applied in the following ways: • By the reconciliation process when placeholders are generated. • By document lifecycle actions when TMF documents are created, as and where applicable. If an alias value is not defined for a particular artifact, the standard D2 auto-naming rules apply. The specified naming convention can be applied later so that it can include references to properties generated by D2 auto-naming, such as document ID numbers. The uses_special_naming_conv flag is also set to true for these items to enable subsequent D2 auto-naming to be suppressed for these documents. Preconfigured Cascading Attributes Rules The following table describes the preconfigured cascading attribute rules included in Documentum eTMF, Documentum R&D, and Documentum SSV: Configuration Rule Name Solution Modules Description Parameters (Method Arguments) Change Product Code Documentum eTMF Invokes through the Change Product Code lifecycle action for Product Registration Forms. It propagates product code changes to the relevant documents and registration forms. $arg(old_value) = previous product code value Documentum R&D Documentum SSV 116 $arg(new_value) = new product code value Attribute Inheritance and Cascading Attribute Rules Configuration Rule Name Solution Modules Description Parameters (Method Arguments) Combine Product Codes Documentum eTMF Invokes through the Combine Product Codes lifecycle action for Product Registration Forms. It merges documents and associated registration forms for one product into another, and deletes the current Product Registration Form. $arg(old_value) = previous product code value Invokes automatically whenever a new Documentum R&D Control Category 1-3 Clinical or Clinical TMF document is created. It copies trial-related attributes from the relevant Clinical Trial Registration Form to the new document. None Documentum R&D Documentum SSV $arg(new_value) = new product code value Inherit Clinical Trial Registration Form Info Documentum eTMF Inherit Non -Clinical Study Registration Form Info Documentum R&D Invokes automatically whenever a new Documentum R&D Control Category 1-3 Non-clinical document is created. It copies non-clinical project-related attributes from the relevant Non-clinical Study Registration Form to the new document. None Inherit Product Registration Form Info Documentum eTMF Invokes automatically whenever a new Control Category 1-3 document is created in any domain. It copies product-related attributes from the relevant Product Registration Form to the new document, where applicable. None Documentum R&D Documentum R&D Documentum SSV Inherit Quality Project Registration Form Info Documentum R&D Invokes automatically whenever a new Documentum Q&M Control Category 1-3 document is created. It copies project-related attributes from the relevant Quality Project Registration Form to the new document, where applicable. None Inherit TMF Placeholder Info Documentum eTMF Invokes automatically whenever a new Clinical Trial Master File (TMF) Control Category 1-3 document is created. It copies attributes from the relevant placeholder to the new document, where applicable. None 117 Attribute Inheritance and Cascading Attribute Rules Configuration Rule Name Solution Modules Description Parameters (Method Arguments) Merge Product Info to PRF Documentum eTMF Invokes as part of the Combine Product Codes lifecycle action for Product Registration Forms. It copies product-related information from one Product Registration Form to another. $arg(old_value) = source product code value Invokes through the Reassign to Product lifecycle action for Clinical Trial Registration Forms. It enables a set of clinical trial documents to be moved to a different product. $arg(old_product_code ) = previous product code value Documentum R&D Documentum SSV Move Clinical Trial to New Product Move Site Registration to New Location Documentum eTMF Documentum R&D Documentum eTMF Invokes through the Change Site Location lifecycle action for Site Registration Forms. It updates a TMF site registration to refer to a different country. $arg(new_value) = target product code value $arg(new_product _code) = new product code value $arg(site_id) = site identifier code $arg(site_name) = site name / label $arg(old_country_code ) = previous country code value $arg(old_area_code) = previous area code (U.S. state code, where applicable) $arg(new_country _code) = new country code value $arg(new_area_code) = new area code (U.S. state code, where applicable) Move TMF Site Documents to New Location 118 Documentum eTMF Same as Move Site Registration to New Location. (It is part of the same operation.) Same as Move Site Registration to New Location. Attribute Inheritance and Cascading Attribute Rules Configuration Rule Name Solution Modules Description Parameters (Method Arguments) Rename Site Documentum eTMF Invokes through the Change Site Name lifecycle action for Site Registration Forms. It updates a TMF site registration to refer to a different site name. $arg(site_id) = site identifier code $arg(old_site_name) = previous site name / label $arg(new_site_name) = new site name / label Rename Site-level TMF Documents Documentum eTMF Same as Rename Site. (It is part of the same operation.) Same as Rename Site. Update Clinical Trial Info Documentum eTMF Invokes through the Update Trial Info lifecycle action for Clinical Trial Registration Forms. It reapplies updated inherited clinical trial information to the relevant documents. None Invokes through the Update Product Info lifecycle action for Product Registration Forms. It reapplies updated inherited product information to the relevant documents and associated registration forms. None Documentum R&D Update Product Info Documentum eTMF Documentum R&D Documentum SSV Using a Custom Attribute Inheritance Rule to Reapply D2 Configurations to Selected Objects Occasionally it may be necessary to reapply D2 configurations, such as autonaming, autolinking, and security, to existing objects in the repository. For example, after you change the auto-filing rules or upgrade from a previous release of the Life Sciences Solution that uses new auto-filing rules. To reapply the D2 configurations, you can create a custom attribute inheritance rule and invoke it through a DQL statement. 1. To create a custom attribute inheritance rule, log in to D2 Client as a member of the Controlled Document Administrators group (cd_admingroup) or the installation owner (for example, dmadmin). 2. Select New > Content from the menu bar. 3. In the Creation profile field, select System Adminstration. 4. In the Document Type field, select Auto Inherited Attributes Rule and click Next. 119 Attribute Inheritance and Cascading Attribute Rules 5. On the Edit properties page, in the Configuration name field, type a name for the attribute inheritance rule. For example, Reapply D2 Configurations. Type an optional description to explain its purpose. The system automatically enables the rule by default. 6. On the Rule applicability tab, configure the rule as described in the following table: Field Description Automatically applies to new objects Do not select this option. You should only enable it for rules that the system automatically applies when users create documents. For this rule, you invoke it only when necessary using a DQL query. Order of precedence Leave this option set to 1- High. You can ignore this option because it only applies when multiple rules apply to the same object to ensure that the rules apply in the appropriate order. Applies to object types Select the wildcard symbol * (any object type). This field defines the scope of the rule by identifying the documents in the repository that apply to the rule. When you execute the rule, you specify the cabinet and folder path of the top-level folder containing the relevant documents explicitly in a –folder_path method argument. It is not necessary to specify an –id argument (a context object) in this field. 120 Attribute Inheritance and Cascading Attribute Rules 7. Skip the Inherit from tab. This tab specifies the source objects used for copying inherited attributes and this rule does not apply inherited attributes. 8. On the Inherit to tab, specify the target objects to process as described in the following table: Field Description Inherit to Type a DQL qualifier (of the form <object-type>[(all )] where <criteria>) that identifies the target objects to update. For this rule, type: cd_controlled_doc(all) where folder(’$arg (folder_path)’, descend) which selects all controlled documents at or below a specified folder including historic versions. (You specify the folder in the –folder_path method argument when you execute the rule.) To only update the CURRENT versions, omit (all) after the object type. For checked-out objects Specify how to handle checked-out documents. For this rule, select Skip update (default). Any currently checked-out documents do not update until the relevant users check them in. At that time, Documentum D2 reapplies the configurations. You can also elect to force check-ins or temporarily bypass the check-out locks for these documents. If you use the force check-in or bypass options, they could impact users who are currently working on those documents. 9. Skip the Attributes and Folder updates tabs. They do not apply to this rule. 10. On the Deletion tab, select Delete empty folders. When documents auto-file to new locations, the system deletes any remaining empty folders automatically, including any empty parent folders along the chain towards the cabinet level. 11. On the Post-processing tab, type the wildcard symbol * in the following Reapply D2 configurations fields: • Reapply D2 autonaming where • Reapply D2 autolinking where • Reapply D2 security where Leave the Custom processing fields blank. 12. Click Next. The system creates the rule in the /System/CDF/Auto Attribute Inheritance Config folder with the other rules. 13. To execute the rule, log in to Documentum Administrator or IDQL as the repository installation owner (for example, dmadmin) and issue a DQL statement of the following form: 121 Attribute Inheritance and Cascading Attribute Rules execute do_method with method = 'CDFApplyAttributeInheritanceMethod', arguments = '-docbase_name <repository-name> -user_name dmadmin -password "" -auto_inherit_config "Reapply D2 Configurations" -folder_path "<repository-folder-path>' You do not need a password if you execute the query from the Documentum Content Server as the installation owner. For example: execute do_method with method = 'CDFApplyAttributeInheritanceMethod', arguments = '-docbase_name documentum -user_name dmadmin -password "" -auto_inherit_config "Reapply D2 Configurations" -folder_path "/Clinical/Cardiology-Vascular/Vasonin"' The method should return a success code when it is completed. The Java Method Server Applications log file provides additional details. For example: %DOCUMENTUM%\jboss5.1.0\server\DctmServer_MethodServer\logs\ ServerApps.log You can tune the performance of the method by adjusting the max_threads and content_servers settings in the Documentum D2 System Parameters dictionary. provides more information. 122 Chapter 8 Workflows Workflows comprise tasks that provide business logic to the lifecycle phases and pass content from one state to another. This chapter contains the following topics: • Workflow Roles, page 123 • Workflow Diagrams, page 124 • Configuring Workflows, page 136 • Assigning Workflows to Artifacts, page 137 • Modifying the Task Outcome Labels, page 137 • Configuring Workflow Messages, page 138 • Changing Workflow Task Performers, page 138 • Workflow and Non-Workflow Attributes, page 140 Workflow Roles The Life Sciences solution provides a number of predefined, generic workflow templates and associated D2 workflow configurations to process controlled documents. The number of states and workflow task performers depends on each workflow. Note: In Life Sciences 4.0, workflow availability is determined by the type of document. The typical workflow initiator for a workflow is a Document Author or Coordinator. A workflow initiator is also the workflow supervisor. When an initiator starts a workflow, a dialog box appears where the workflow task performers must be specified. It is not possible to start a workflow without specifying the performers. The workflow task performers must be of the following roles: • Document Author • Reviewer • Approver • QO Approver 123 Workflows • Coordinator • TBR Reader Workflow Diagrams The Life Sciences solutions provide generic workflows to process Control Category 1–3 documents. Workflows are composed of tasks that provide business logic to the lifecycle phases and pass content from one state to another. This section contains the following topics: • For Collaborative Editing (Categories 1 - 3), page 125 • Submit for Review and Approval (Category 1), page 125 • Submit for Approval (Category 1), page 126 • Submit for Periodic Review (Category 1), page 127 • Withdraw Document (Category 1), page 128 • Submit to To Be Read Recipients (Category 1), page 128 • Recall Document (Category 1), page 129 • Submit for Review and Approval (Change Request), page 130 • Submit for Approval (Change Request), page 131 • Submit for Review and Approval (Category 2), page 131 • Submit for Review-Format Approval (Category 2), page 132 • Submit for Approval (Category 2), page 133 • Expiry Review (Category 2), page 134 • Submit for Review (Category 3), page 134 • Submit for Delegated Approval (Category 3), page 135 • Content Template Approval, page 136 124 Workflows For Collaborative Editing (Categories 1 - 3) Use this workflow to send a Control Category 1-3 document for collaborative editing before sending it to one of the review and approval workflows. This workflow is configured for all solutions. The system automatically performs the tasks indicated by the perform the tasks with the icon. Users with specific roles icon. Users perform the tasks described in the following table: User Task Description Edit document Reviewers review and edit the document. Incorporate changes Authors incorporate the changes from each Reviewer. Submit for Review and Approval (Category 1) Use this workflow to send Control Category 1 documents for formal review and approval. This workflow is configured for LSQM only. An Author cannot be an Approver on the same document. Users perform the tasks described in the following table: User Task Description Review Reviewers review and annotate the content. 125 Workflows User Task Description Draft Authors review feedback on the document. After the Approver demotes the document to Draft, the Author can skip the review task after making the changes and can send the document directly for approval. Draft – Do not allow skip Authors review feedback on the document and resend the edited draft document for another round of review. Authors cannot skip the review of the document. For Approval Approvers approve the document. The document must be electronically signed on approval. For Approval no Sig Approvers approve the document. Electronic signature is not required on approval. QO Approval Quality Organization (QO) Approvers approve the document. Ready to Make Effective/Approved/Final After all of the reviewing and approving tasks are finished, the Document Coordinator releases the document to the Effective/Approved/Final state. Submit for Approval (Category 1) Use this workflow to send Control Category 1 documents directly for approval and skip the formal review. This workflow is configured for LSQM only. An Author cannot be an Approver on the same document. Users perform the tasks described in the following table: 126 Workflows User Task Description Draft Authors review feedback received from Approvers on the document. For Approval Approvers approve the document. The document must be electronically signed on approval. For Approval no Sig Approvers approve the document. Electronic signature is not required on approval. QO Approval Quality Organization (QO) Approvers approve the document. Ready to Make Effective/Approved/Final After all of the reviewing and approving tasks are finished, the Document Coordinator releases the document to the Effective/Approved/Final state. Submit for Periodic Review (Category 1) Use this workflow to send Control Category 1 documents that are in the Effective state for a periodic review. This workflow is configured for LSQM only. User Task Description Coordinator When the workflow is triggered on the defined periodic review date, the assigned Document Coordinator receives a notification to initiate the review process. The Document Coordinator assigns the list of reviewers for the periodic review and initiates the review process. 127 Workflows User Task Description Review Reviewers review the document. All reviewers in the list of participants must review the document and accept the task for the review to complete successfully. If any of the Reviewers reject the document, it returns to the Author in the Draft state for revision. The Author needs to make the necessary changes and send the document to the Submit for Review/Approval or Submit Directly for Approval workflow to make the document Effective/Approved/Final. Acknowledge Author accept the document rejected by the Reviewers and acknowledge that revisions need to be made to the document, which is in Draft state. Withdraw Document (Category 1) Use this workflow to send Control Category 1 documents that are in the Effective state for approval before being Withdrawn. This workflow is configured for LSQM only. User Task Description Approvers The list of Approvers must approve the withdrawal of a document and provide the withdrawal reason before the document can be Withdrawn. If any one Approver rejects the task, the document does not change to the Withdrawn state and the workflow completes. Submit to To Be Read Recipients (Category 1) This optional workflow notifies users in the To be Read (TBR) Distribution List of a Control Category 1 document that it is time to read the document. Use this workflow for Release Pending documents that require users to understand a process or procedure. Users with specific roles can also reissue a task at any time for Release Pending documents so that new users can read and understand the documents. This workflow is configured for LSQM only. 128 Workflows When starting the workflow, the initial list of recipients contains the members of the TBR Distribution List for the selected document. The Document Coordinator can add and remove users from this list. The system adds new users to the TBR Distribution List, but does not remove any users. Each time the Document Coordinator starts the workflow, the Document Coordinator selects recipients from the members of the latest TBR Distribution List. Users perform the tasks described in the following table: User Task Description Read Confirmation Sends a document to the members of the selected distribution list. Recipients review and electronically sign the documents. All members electronically sign to indicate that their document review is complete. When all of the Recipients sign off on the document or reject the task, the workflow returns to the Document Coordinator. If a recipient rejects the task, the issuer receives a notification. Read Completed The Document Coordinator receives a confirmation notification that the To Be Read distribution list for the document is complete. The Document Coordinator can accept the task to finish the workflow process. Recall Document (Category 1) This is a workflow that applies only when a Control Category 1 document that was printed is no longer Effective. In that case, the Recall Document workflow process begins the process of recalling documents. For example, documents are recalled if the Document Coordinator changes the status of the document from Effective to Suspended. The controlled print recall functionality requires BROWSE access. This workflow is configured for LSQM only. 129 Workflows Users perform the following task: • Recall Document: Sends a task message to the user who requested the print-out as well as to the user who can print out documents to delete all printed or exported copies of a printed document. After destroying the documents, users accept the task to indicate the destruction of all electronic and physical versions. Submit for Review and Approval (Change Request) Use this workflow for Change Requests. This workflow is configured for LSQM only. Users perform the tasks described in the following table: User Task Description Review CR Document Coordinators review the Change Request. When finished, Document Coordinators promote or reject the document. Edit CR Authors review the Change Request rejected by the Coordinator, make the necessary changes, and promote the document for a re-review or directly for approval. Approve CR Document Approvers review the Change Request. When finished, Document Approvers approve or reject the document. Acknowledge Changes Users assigned as Acknowledgers can acknowledge that the Change Request is approved and accepts the task to complete the workflow. The state of the Change Request changes to CIP. 130 Workflows Submit for Approval (Change Request) Use this workflow for Change Requests. This workflow is configured for LSQM only. Users perform the tasks described in the following table: User Task Description Approve CR Document Approvers review the Change Request. When finished, Document Approvers approve or reject the document. Edit CR Authors review the Change Request rejected by the Approver, make the necessary changes, and promote the document for approval. Acknowledge Changes Users assigned as Acknowledgers can acknowledge that the Change Request is approved and accept the task to complete the workflow. The state of the Change Request changes to CIP. Submit for Review and Approval (Category 2) Use this workflow to send Control Category 2 documents for formal review and approval. This workflow is configured for all solutions. An Author cannot be an Approver on the same document. Users perform the tasks described in the following table: 131 Workflows User Task Description Draft Authors review the feedback on the document. After the Approver demotes the document to Draft, the Author can skip the review task after making the changes and send the document directly for approval. Draft – Do not allow skip Authors review the feedback on the document and resend the edited draft document for another round of review. Authors cannot skip the review of the document. Review Reviewers review the content. Approval Approvers approve the document. The document must be electronically signed on approval. For Approval no Sig Approvers approve the document. Electronic signature is not required on approval. Document has been issued After the reviewing and approving tasks are complete, the Author receives a notification to set the review dates. Submit for Review-Format Approval (Category 2) Use this workflow to send Control Category 2 documents for review, format review, and approval. This workflow is configured for LSTMF, LSRD, and LSSSV. An Author cannot be an Approver on the same document. Users perform the tasks described in the following table: 132 Workflows User Task Description Draft Authors review the feedback on the document. After the Format Reviewer demotes the document to Draft, the Author can send the document to the Reviewer, Format Reviewer or Approver. After the Approver demotes the document to Draft, the Author can skip the review task after making the changes and send the document directly for approval. Draft – Do not allow skip Authors review the feedback on the document and resend the edited draft document for another round of review. Authors cannot skip the review of the document. Review Reviewers review the content. Format Review Format reviewers review the content. Approval Approvers approve the document. The document must be electronically signed on approval. For Approval no Sig Approvers approve the document. Electronic signature is not required on approval. Submit for Approval (Category 2) Use this workflow to send Control Category 2 documents directly for approval. This workflow is configured for all solutions. An Author cannot be an Approver on the same document. Users perform the tasks described in the following table: 133 Workflows User Task Description Approval Approvers approve the document. The document must be electronically signed on approval. For Approval no Sig Approvers approve the document. Electronic signature is not required on approval. Draft Authors review the feedback on the document. Document has been issued After the approving tasks are complete, the Author receives a notification to set the review dates. Expiry Review (Category 2) Use this workflow to send Control Category 2 documents for an expiry review. This workflow is configured for LSTMF, LSRD, and LSSSV. Users perform the tasks described in the following table: User Task Description Review Document Coordinator reviews the document and can withdraw the document, expire the document, or send it to the Author for revision. Acknowledge Author acknowledges that revisions are required for the document, which is in the Draft state. Submit for Review (Category 3) Use this workflow to process a Control Category 3 document. This workflow is configured for all solutions. 134 Workflows Users perform the tasks described in the following table: User Task Description For Review Authors or Reviewers review the document. Draft Authors review the feedback on the document. Submit for Delegated Approval (Category 3) Use this workflow to send reviewed Control Category 3 documents directly for approval. This workflow is configured for all solutions. Users perform the tasks described in the following table: User Task Description Draft Authors review the feedback from Approvers on the document. Delegated Approval Delegated Approvers approve the document. The document must be electronically signed on approval. Delegated Approval – no Sig Delegated Approvers approve the document. Electronic signature is not required on approval. 135 Workflows Content Template Approval Use this workflow to send a newly created content template for approval. This workflow is configured for all solutions. Users perform the tasks described in the following table: User Task Description Draft Domain-specific template Authors review the feedback on the document. For Approval Domain-specific template Approvers approve the document. The document must be electronically signed on approval. Configuring Workflows Each workflow has a workflow template and a corresponding configuration in D2-Config. To configure a workflow, follow these steps: 1. Log in to D2-Config. 2. Click Go to > Workflow. 3. Select the workflow you want to configure. 4. In the Task configuration section, you can update the following field: 136 Field Description Subject Subject of the task that appears in the inbox of the performer. Message Detailed message that explains the task. Manual acquisition Acquire the task with or without a click action from the user. Electronic signature Include an electronic signature with the message. Workflows Field Description Audit Enable or disable auditing. Task follow up Task duration can be defined on the this tab. Reminder notifications can be configured by specifying the number of days before which the reminder has to be sent and to whom. Assigning Workflows to Artifacts You can assign workflows for specific artifacts through taxonomies. The following screenshot explains the parts of the taxonomy sheet where you can assign workflows: In the screenshot, the highlighted header row indicates the various workflow dictionaries for each Control Category. For an artifact, a dictionary value for the workflow can either be N (No) or Y (Yes). For example, for the Debarment Certification artifact, the Collaboration workflow for Category 1 documents is set to N, indicating that the workflow is not enabled. If the value is set to Y, when you right-click the document in the D2 Client, the Collaboration workflow option appears in the menu. To assign workflows: 1. Log in to D2 Config as an administrator. 2. On the main toolbar, select All elements in the filter list. 3. Click Data > Taxonomy. 4. Under Taxonomies, select a Classification by Group taxonomy. 5. In the dialog box, select Modify and save a copy of the sheet on your machine. 6. In the taxonomy Excel sheet, enable or disable the workflow dictionaries for the required artifacts by setting the values as N or Y. 7. Import the updated sheet. 8. Click Save. Modifying the Task Outcome Labels The Life Sciences solution uses a set of predefined labels configured out of the box to replace the default ‘Accept’ and ‘Reject’ labels for the various workflows. The user guides for each of the solutions provides a list of these preconfigured task labels for each of the workflows. However, you can change these labels in D2 Config according to your specific requirements. To modify the workflow task outcome labels, follow these steps: 137 Workflows 1. Log in to D2 Config as an administrator. 2. On the main toolbar, select All elements in the filter list. 3. Click Go to > Workflow. 4. In the Workflow List, select a workflow for which you want to modify the labels. 5. Under Task configuration, select a task. 6. On the Task parameters tab, under Workflow labels, in the Replace “Accept” with and Replace “Reject” with fields, replace or add the new labels. 7. Click Save. Configuring Workflow Messages To meet business requirements, Administrators can modify when task participants receive workflow reminder messages in D2 Config. 1. Log in to D2 Config as an administrator. 2. Select EMC Controlled Document Foundation from the configuration filter. 3. Select Go to > Workflow from the menu bar. 4. In the Workflow List, select the workflow to change. 5. Navigate to the Task configuration area and select the task to modify. 6. On the Task follow up tab, modify these settings and the messages as needed: • Task duration in days: Type the total number of days allotted to the task. • Remaining days before the end of task: Type the number of days remaining in the task to send a workflow message. When the number of days remaining until the task deadline reaches the entered number, the selected notification recipients receive a workflow message. 7. Save the configuration. Changing Workflow Task Performers After a workflow starts, it is often necessary to change the performer of a workflow task. For example, a reviewer may not be available to complete a review inbox task. In this case, the reviewer can delegate the task to another workflow task performer. Workflow task performers can delegate the tasks in their inboxes to other workflow task performers. Workflow supervisors can change the workflow task performers in the following ways: • Delegate a task that is in the inbox of any workflow task performer. For example, a workflow supervisor can delegate a task because an employee left the company or is out of the office on 138 Workflows sick leave. You can delegate only the tasks that are in the inbox of workflow task performers, not future tasks. • Stop a workflow and send a document to a new workflow to add additional performers to a current task. For example, a workflow supervisor sends a document to the Review workflow and the workflow creates a task for Reviewer 1. The workflow supervisor can stop the workflow and then resend the document for review to Reviewers 1, 2, and 3. There are two sets of performers for a document. One set is the performers defined on the Process Info tab of the document properties. The other set is the performers that actually participate in the workflow. When a workflow starts, the workflow task performers are set based on the performers listed on the Process Info tab. Any change in the workflow performers using the Update performers, Send to workflow, or Reassign Roles menu options changes only the actual workflow performers. It does not change the performers shown on the Process Info tab. These workflow performers have access to the documents only when they are the current performers, that is, they have a task in their inbox. Updating Workflow Task Performers 1. Log in as a workflow supervisor. 2. Navigate to the document for which you are updating performers. 3. In the Document list, select the document and click Workflow overview. If you do not have a Workflow overview tab, click the + tab and select the Workflow overview widget. 4. In the Workflow overview widget, right-click a workflow with the Running state and select Update performers. 5. Update the performers as needed and click OK. You can update the performers of all activities other than the Document Coordinator. Reassigning Roles 1. Log in as a member of a Document Coordinator or Author group. Only document coordinators can reassign roles for Category 1 and 2 documents. Authors and document coordinators can reassign roles for Category 3 documents. 2. Right-click a document and select Reassign Roles. Change the user groups assigned to the roles as needed. Each tab represents a different user role. For example, on the Approvers tab, you can replace the Approvers listed for that role. 3. Click OK. 139 Workflows Workflow and Non-Workflow Attributes Each workflow task performer value is stored as an attribute of the document. When the workflow is started, values from the these attributes are used to populate the workflow properties. These attributes are referred to as non-workflow attributes or document attributes. In addition to task performers stored in the document attributes (Author, Reviewer, and so on), another set of attributes are provided, which are unique to workflows. These attributes include a “wf” prefix such as wf_authors, wf_reviewers, wf_approvers, and so on. These attributes are referred to as the actual workflow performers. The non-workflow performers or attributes do not include the “wf” prefix. When a workflow is started, the non-workflow attribute values are copied to the corresponding actual workflow attributes. Thereafter, these new attributes take part in the workflow. Any change to the actual workflow attributes does not affect the corresponding non-workflow attributes. The actual workflow performers have the necessary permissions on the document only when the document is in the state where the performer can perform the task. You can use the Update performers and Reassign Roles options to update the actual workflow attributes. The modified values are not stored in the non-workflow attributes and cannot be viewed in the document properties. Instead, they are stored only as part of the workflow attributes for the workflow. 140 Chapter 9 Lifecycles This chapter contains the following topics: • Document Lifecycle, page 141 • Using Uniqueness Checks to Validate Transition, page 148 • Normal States and Pseudo States, page 149 • Creating or Modifying a New Lifecycle Configuration, page 149 • Custom Business Logic Using Lifecycle Actions, page 150 Document Lifecycle A document created within the Life Sciences solution has predefined states in which it can be present at any given point of time. These states, as a whole define the lifecycle of the document. Lifecycles are a very important part of this solution, as security and workflows are directly linked to it. Standard D2 lifecycle configurations are provided as part of the CDF layer to support each of the four security categories (Category 1-4). Additionally, lifecycles are defined for Change Request, Product and Project registration forms, and so on. The lifecycle models for Category 1-3 controlled documents are designed to support the authoring, review, approval, and controlled release of documents, and also post-release management operations such as suspension, expiry, superseding, and withdrawal of previously-released versions. They are closely-related to the corresponding review / approval workflows. The following table describes the document lifecycle states and the applicable control categories: Lifecycle State Control Category Description Draft 1, 2, 3 Indicates new documents and versions added and prepared by Authors. For Review 1, 2, 3 Indicates documents submitted for review by Reviewers. Reviewed 3 Indicates that the review phase is completed. For Approval 1, 2 Indicates documents submitted for sign-off by Approvers. 141 Lifecycles Lifecycle State Control Category Description Release Pending 1, 2 Indicates documents that have been signed-off by all designated Approvers. Document Coordinators make the document Effective. Effective /Approved/Final 1, 2, 3 Indicates documents that are approved for use and current. Indicated by a major version number. Readers can view the Effective version of documents. Suspended 1, 2, 3 Indicates an Effective document that was changed to Suspended by a Document Coordinator. This state prevents the document from being used while a modified version is being prepared, reviewed, and approved. Suspended documents can be reinstated to Effective if necessary, or changed to Superseded when the next version or replacement document becomes Effective. Alternatively, the entire document can be Withdrawn. Superseded 1, 2, 3 Indicates a previously-Effective version of a document that was replaced by a more recent version that was Reviewed, Approved, and made Effective. In general, Superseded versions are not recommended because they are, by definition, out-of-date. However, it is useful to retain them as historical records. Expired 1 Indicates a document that was previously Effective but is now past its expiration date. Typically, Expired documents are not used, as they can be invalid. Before they expire, the documents are reviewed and expiration date is rescheduled or revised to generate a new version. 142 Lifecycles Lifecycle State Control Category Description Withdrawn 1, 2, 3 Indicates retired documents. All versions are withdrawn together. Cannot be versioned, but can be copied to create a document. Document Coordinators can withdraw a document at any time, which affects all versions. Users are not allowed to create new versions of a Withdrawn document. However, it can be reverted to Draft if necessary, to enable its content to be reused, or deleted. Retain Withdrawn documents as historical records. Not Issued 4 Indicates a work-in-progress version of an uncontrolled document that Authors are preparing and is not yet ready for general consumption. Like the Draft state of Control Categories 1-3 documents. Default state for all new versions of Control Category 4 documents. Issued 4 Indicates a Control Category 4 document that is ready for general consumption by the Readers. This state is like the Approved state of Control Category 1-3 controlled documents. Historic 4 Indicates a Control Category 4 document that is obsolete. This state is like the Withdrawn state of Control Category 1-3 documents. Authors can delete these documents or retain them as historic copies. Document Lifecycle Models This section describes the state transitions for the control category documents. This section contains the following topics: • Control Category 1 Documents Lifecycle, page 144 • Control Category 2 Documents Lifecycle, page 144 • Control Category 3 Documents Lifecycle, page 145 143 Lifecycles • Trial Master File Document Lifecycle, page 147 • Control Category 4 Documents Lifecycle, page 148 Control Category 1 Documents Lifecycle The following figure illustrates the lifecycle state transitions in the Control Category 1 Documents Lifecycle Model: Control Category 2 Documents Lifecycle The following figure illustrates the lifecycle state transitions in the Control Category 2 Documents Lifecycle Model: 144 Lifecycles Control Category 3 Documents Lifecycle The following figure illustrates the lifecycle state transitions in the Control Category 3 Documents Lifecycle Model: 145 Lifecycles 146 Lifecycles Trial Master File Document Lifecycle The following figure illustrates the lifecycle state transitions in the Trial Master File (Control Category 3) Documents Lifecycle Model: 147 Lifecycles Control Category 4 Documents Lifecycle The following figure illustrates the lifecycle state transitions in the Control Category 4 Documents Lifecycle Model: Using Uniqueness Checks to Validate Transition Documents go through state transitions very often. A draft document may become Effective (so that its available for everyone to read) whereas an Effective might be required to be withdrawn when it goes out-of-date. The state transitions can be defined in the D2 lifecycle configuration for each and every state. There might be large number of states of a document, but from a given state, the states a document can transition to is defined in the “Next States” section of the lifecycle configuration. The “Next State” section is available for all states of the document. User can click on the “+” sign to add a new transition state. The following options are possible in the next state configuration: • The actions to perform, for example, check-in and check-out • The transition type, for example, Promote, Demote • The label to be displayed for the transition (all possible lifecycle states can be viewed by right-clicking the state) • Inclusion of electronic signature, if required • If there is a need to launch a property pages on transition, that can be defined in a dialog box • Inclusion of a confirmation message, if required 148 Lifecycles The transition to any state can be restricted with the help of different checks. Uniqueness checks, which are conditions, can be posed to a document, such as “validate document is not checked out”. Any number of uniqueness checks can be created and restrictions can be applied based on any of them. There are two types of checks available: • Entry Condition: This is a generic check that can be applied to enter a state. In order to enter this target state, the checks specified in the ‘Entry conditions” section must be met. Here, the source state is any other state. • Transition Condition: This is a specific check that can be applied from a fixed source state to a fixed target state. This option is present at the bottom of the lifecycle configuration page. First the target state has to be selected from the “Next State” section, and then the transition condition can be selected from the drop-down list. Normal States and Pseudo States Normal states are the states which are set to a_status attribute of the document. These are visible in the UI and are used where the document state actually changes. Pseudo states are not the actual states. These are not set to the a_status attribute and are not shown in the UI. They are used to perform actions that do not require a state change on the document For example: if you want to update the security of a document, you can create a pseudo lifecycle action such as “(Update Security)”. The pseudo state will be added as the “Next State” for the normal states. In the “Action Type” section of the lifecycle configuration, you can specify some actions. Also in the Dialog box field, you can launch a property page that displays the current security settings. Users can change the security and save it. All these changes does not change the actual state of the document. Pseudo states are enclosed within brackets. Creating or Modifying a New Lifecycle Configuration There are two ways of creating a new lifecycle: • By using the New button: From the D2-Config home page, click Go To > Lifecycle. Click the New button. A blank lifecycle creation page appears. You can provide the details required in the configuration on this page. • By using Create from button: This is a simpler way of creating a new lifecycle configuration. You can select an existing lifecycle and click the Create from button. The entire configuration from the selected lifecycle is copied to the new one; only the name needs to be different. You need to change the configuration based on the requirements. This option is useful when there are common things between different lifecycle configurations. After the lifecycle is created, it needs to be associated to the correct set of documents. You can click on the Matrix button so that home page of D2-Config is presented. In the rows section, expand the lifecycle group. In columns section, locate the desired context. Once both are located, double-click the box that marks the intersection of the desired row and the column. Save the changes. 149 Lifecycles Custom Business Logic Using Lifecycle Actions Custom methods can be called from lifecycle actions. Follow these steps to configure custom business logic for lifecycle actions: 1. Create a custom method. 2. Compile it and create a JAR file. 3. Place the JAR file in the serverapps.ear/lib directory of the Java Method Server. 4. Log in to Documentum Administrator. 5. Go to Methods. 6. On the File menu, click New method. 7. Specify the name, verb, and other fields, and then save the changes. The newly added method appears in the “Apply Method” list in the lifecycle configuration page in D2-Config. 8. Select the method and pass the necessary arguments in the Extra Arguments field. 9. Click Save. The Life Science solution provides two JAR files that has several dm_methods built in. Refer to the javadocs and use any of them based on their requirements. 150 Chapter 10 Security This chapter contains the following topics: • Controlled Document Foundation Security Model, page 151 • Permissions, page 152 • Assignment of Control Categories, page 159 • Role-Based Access Control, page 161 • Ownership of Category 1-3 Documents, page 161 • Folder Security, page 162 • TMF Dynamic Role-Based Access Control (eTMF Only), page 162 Controlled Document Foundation Security Model The CDF Security Model applies security at four different levels: • At the document level, through Role-Based Access Controls (RBAC) and Role-Based Lifecycle Operations (RBLO). Depending on the role of the user on a particular document (if any), and the current state of the document in its lifecycle, the user has a specified level of access to that document, and may or may not be able to carry out certain operations on it, such as making the document “Final”. Without a defined role, the user cannot access the document. • At the group level, through control groups. Control groups are used to restrict the users and subgroups that can be assigned to particular roles on a document. For instance, in order for a user to act as an Approver for a clinical document, the user must belong to the cd_clinical_doc_approvers control group. • At the project, study, trial ,or procedure level, through Registration Forms. The Managers of these forms can change the status of the registration to an Inactive state if necessary. This prevents documents from being made Final, temporarily freezing the current set of Final documents. The Manager can reactivate the registration form to enable documents to be made Final again. • At the product level, through Product Registration Forms. Products can have multiple active projects, studies, or trials associated with them. Product Managers can make product registrations inactive to prevent documents from being made Final across all projects, studies, or trials. 151 Security Permissions The Life Sciences solutions configure the permissions of documents based on the user role and the document category. Permissions are defined for each item in the repository. Permissions identify the security level needed for a group or user to access the item and their allowed actions. The basic permissions in D2 are: • NONE: Cannot access any object or object attributes. • BROWSE: Can view the properties of the object. • READ: Can view the properties of the object and content. • RELATE: Same as READ, plus users can add object annotations. • VERSION: Same as RELATE, plus users can change object content. • WRITE: Same as VERSION, plus users can alter attributes and change content without updating the version. • DELETE: Same as WRITE, plus users can delete any object. The EMC Documentum D2 User Guide provides additional information on permissions. The following topics describe the permissions that are available in the Life Sciences solution suite: • Permissions in Documentum eTMF, page 152 • Permissions in Documentum Q&M, page 155 • Permissions in Documentum R&D and Documentum SSV, page 157 Permissions in Documentum eTMF The Documentum eTMF permissions for TMF documents (Control Category 2 and 3) are listed in the following table for the contributors, authors, document coordinators, and reviewers roles: State Contributors Authors Document Reviewers Coordinators Format Reviewers (Cat 2 only) Approvers (Cat 2 only) Index DELETE DELETE WRITE WRITE WRITE NONE Draft DELETE DELETE WRITE WRITE WRITE NONE For Review (Cat 2 only) RELATE RELATE RELATE RELATE NONE NONE Reviewed (Cat 3 only) VERSION VERSION READ READ NONE NONE For Approval (Cat 2 only) READ READ READ READ READ READ Format Review (Cat 2 only) RELATE RELATE RELATE RELATE RELATE NONE 152 Security State Contributors Authors Document Reviewers Coordinators Format Reviewers (Cat 2 only) Approvers (Cat 2 only) Release Pending (Cat 2 only) VERSION VERSION READ READ READ READ Effective /Approved /Final VERSION VERSION READ READ READ READ Expired (Cat 2 only) VERSION VERSION READ READ READ READ Superseded READ READ READ READ READ READ Suspended VERSION VERSION READ READ READ READ Withdrawn READ READ READ READ READ READ RELATE Required /Recommended /Omitted /Optional (Clinical TMF only) WRITE WRITE NONE NONE NONE RELATE Required /Recommended /Omitted /Optional (Non -repeatable, for example, Clinical TMF) WRITE DELETE NONE NONE NONE RELATE Required /Recommended /Omitted /Optional (Repeatable, for example, Clinical TMF) RELATE DELETE NONE NONE NONE The Documentum eTMF permissions for TMF documents (Control Category 2 and 3) are listed in the following table for the readers and auditor roles: State Readers Auditors Index NONE NONE Draft NONE NONE For Review (Cat 2 only) NONE NONE 153 Security State Readers Auditors Reviewed (Cat 3 only) NONE NONE For Approval (Cat 2 only) NONE NONE Format Review (Cat 2 only) NONE NONE Release Pending (Cat 2 only) NONE READ Effective/Approved/Final READ READ Expired (Cat 2 only) NONE READ Superseded NONE READ Suspended NONE READ Withdrawn NONE NONE Required/Recommended /Omitted/Optional (Clinical TMF only) NONE NONE Required/Recommended /Omitted/Optional (Non-repeatable, for example, Clinical TMF) NONE NONE Required/Recommended /Omitted/Optional (Repeatable, for example, Clinical TMF) NONE NONE The permissions for Product Registration Forms are listed in the following table: State Managers User Groups Default In Development DELETE RELATE NONE Active DELETE RELATE NONE Suspended DELETE RELATE NONE Withdrawn DELETE RELATE NONE The permissions for Clinical Trial Registration Forms are listed in the following table: State Managers User Groups Default Planning DELETE RELATE NONE Active DELETE RELATE NONE Completed DELETE RELATE NONE Suspended DELETE RELATE NONE Locked DELETE RELATE NONE 154 Security The permissions for Clinical Trial Country and Site Registration Forms are listed in the following table: State Managers User Groups Default Active DELETE RELATE NONE Inactive DELETE RELATE NONE Permissions in Documentum Q&M The permissions for Control Categories 1–3 documents are listed in the following table for the authors, document coordinators, reviewers, and approvers roles: State Authors Document ReviewCoordinators ers Approvers (Cat 1-2 only) Format Reviewers (Cat 2 only) QO Approvers (Cat 1 only) Draft DELETE WRITE WRITE NONE WRITE NONE For Review (Cat 1 and 2 only) RELATE RELATE RELATE NONE NONE NONE Reviewed (Cat 3 only) VERSION READ READ NONE NONE NONE For Approval (Cat 1 and 2 only) READ READ READ READ READ READ Format Review (Cat 2 only) RELATE RELATE RELATE NONE RELATE NONE Release Pending (Cat 1 and 2 only) VERSION READ READ READ READ READ Effective (Effective /Approved /Final) VERSION READ READ READ READ READ Expired (Cat 1 only) VERSION READ READ READ READ READ Superseded READ READ READ READ READ READ Suspended VERSION READ READ READ READ READ Withdrawn READ READ READ READ READ READ The permissions for Control Categories 1–3 documents are listed in the following table for the recipients, readers, and auditors roles: 155 Security State Recipients – TBR List (Cat 1 only) Readers Auditors Draft NONE NONE NONE For Review (Cat 1 and 2 only) NONE NONE NONE Reviewed (Cat 3 only) NONE NONE NONE For Approval (Cat 1 and 2 only) NONE NONE NONE Format Review (Cat 2 only) NONE NONE NONE Release Pending (Cat 1 and 2 only) READ NONE READ Effective (Effective /Approved/Final) READ READ READ Superseded BROWSE NONE READ Suspended BROWSE NONE READ Withdrawn BROWSE NONE NONE The permissions for Change Requests (CRs) are: State Authors Document Coordinators Reviewers Approvers Readers Auditors Regulatory Affairs Notification User Draft DELETE DELETE RELATE NONE NONE NONE NONE NONE For Review READ READ WRITE NONE NONE NONE NONE NONE For Approval READ READ NONE READ NONE NONE NONE NONE CIP READ READ READ READ READ READ READ READ Closed READ READ NONE NONE NONE NONE NONE READ 156 Security Permissions in Documentum R&D and Documentum SSV The permissions for Control Categories 2–3 documents are listed in the following table for the Authors, Reviewers, and Approvers roles: State Authors Document Coordinators Reviewers Approvers (Cat 2 only) Format Reviewers (Cat 2 only) Draft DELETE WRITE WRITE NONE WRITE For Review (Cat 2 only) RELATE RELATE RELATE NONE NONE Reviewed (Cat 3 only) VERSION READ READ NONE NONE For Approval (Cat 2 only) READ READ READ READ READ Format Review (Cat 2 only) RELATE RELATE RELATE NONE RELATE Release Pending (Cat 2 only) VERSION READ READ READ READ Effective /Approved/Final VERSION READ READ READ READ Expired (Cat 2 only) VERSION READ READ READ READ Superseded READ READ READ READ READ Suspended VERSION READ READ READ READ Withdrawn READ READ READ READ READ The permissions for Control Categories 2–3 documents are listed in the following table for the Readers, Auditors, and Regulatory Affairs roles: State Readers Auditors Regulatory Operations (cd_regulatory _publisher) Draft NONE NONE WRITE For Review (Cat 2 only) NONE NONE WRITE Reviewed (Cat 3 only) NONE NONE WRITE For Approval (Cat 2 only) NONE NONE WRITE 157 Security State Readers Auditors Regulatory Operations (cd_regulatory _publisher) Format Review (Cat 2 only) NONE NONE NONE Release Pending (Cat 2 only) NONE READ WRITE Effective/Approved /Final READ READ WRITE Expired (Cat 2 only) NONE READ READ Superseded NONE READ READ Suspended NONE READ READ Withdrawn NONE NONE READ The permissions for Control Category 4 documents are listed in the following table: State Authors Readers Not Issued DELETE NONE Issued VERSION READ Historic READ BROWSE The permissions for Registration Forms are listed in the following table: Access Control Groups Registration Form Permission Managers WRITE User Groups RELATE Default NONE These permissions apply to the access control groups on all registration forms. Form managers define the access control groups on the Access Control tab of the Registration Form properties. To manage the registration form, the manager must be listed on the Managers list. For example, in the Product Registration Form, the Product Managers product_mgr1, product_mgr2, and product_mgr3 have the DELETE permission. To access the registration form, the user group must be on the Primary User Groups list. The cd_clinical, cd_non_clinical, and cd_quality groups have the RELATE permission. Users or groups not listed on the Access Control tab of the Registration Form have the NONE permission. 158 Security Assignment of Control Categories Each document type (or artifact) that can be created in the repository is assigned an appropriate control category automatically. This is done by setting the category attribute (which is defined for the cd_controlled_doc object type) to the relevant value, 1-4, in the default value template. Examples of this can be found in the Clinical Documents creation matrix. This contains a row for each artifact in the DIA Reference Model: for example, Clinical Literature References is assigned to Category 2 through the Clinical Cat 2 Default Values template as shown in the following figure: You can reconfigure the security categories for the various artifacts by changing the Default values template settings in the creation matrix. However, you must ensure that the corresponding lifecycle model is assigned in the Lifecycle column in each case. After the correct category value is assigned, the corresponding lifecycle and security model can be applied through the configuration matrix as shown in the following figure: 159 Security Note that there are four separate lifecycle configurations defined for each of the four control categories, but only two control configurations are defined: one for Category 1-3 controlled documents and a separate one for Category 4 documents. This simplifies the reconfiguration process and maintains a consistent security model, so that access to documents in specific lifecycle states is defined uniformly. For example, Authors always have DELETE permits on “Draft” documents, irrespective of the security category. However, these documents may have different lifecycles and workflows associated with them, depending on the security category in each case. 160 Security Role-Based Access Control The system automatically imposes role-based access controls on all documents created in the repository and grants the relevant level of access to the appropriate users and groups automatically, according to the role member settings and the document’s status in its lifecycle in each case. This is achieved through security configurations in D2. Internally, D2 uses the security configuration applied to a document to construct an Access Control List (ACL) in Documentum and applies it to the document, granting the role members the appropriate level of access in each case. Where a user has two or more roles on the same document, the effect is additive, so that the highest applicable permit level is granted to that user. For example, if a user is designated as both an Author with WRITE access and a Reader with READ access, the higher permit (WRITE) takes precedence. If the roles or lifecycle state is updated for a particular document, D2 updates the underlying ACL automatically, as and where applicable. For example, if the document is in a “Draft” state, only the Document Authors (generally) can access it, but when it becomes “Effective”, the Authors’ permit is reduced to VERSION, and Readers should be given at least READ access (in practice, they may be given RELATE access, which enables them to cross-reference the document in change requests, as well as being able to access the document on a read-only basis). D2 also has a built-in ACL re-use mechanism to reduce the number of distinct ACLs generated by the system, This provides certain performance advantages in normal operations but can adversely affect mass update operations in which the role members are updated for multiple documents. To avoid these updates, the use of groups instead to individual users as role members is recommended. The group members can be updated independently of the documents and ACLs that refer to them, without incurring performance penalties. This also makes the system easier to maintain as changes to role group members immediately affect all documents that use them. If a very large number of role groups are defined, this can also lead to performance issues, particularly for users belonging to many groups because of the way in which the Documentum Content Server filters out objects that the user should not see while navigating and searching the repository. (As a general rule, if a user belongs to no more than 20-30 groups this does not cause any significant performance problems, but if they belong to 200 groups or more the performance degradation can be significant.) Ownership of Category 1-3 Documents In standard Documentum, documents are owned by the user who creates them, and this user has special privileges, as they are able to change the ACL permissions assigned to the document in the repository. This is known to cause problems in role-based access control systems, where the permissions should be enforced in accordance with business rules, and where the “ownership” of objects changes as the document progresses through its lifecycle, and as users join or leave the organization or change roles within it. To circumvent this problem, the system automatically transfers ownership of all Category 1-3 documents to the admingroup (the Documentum Administrators group), and adds the Creator as an initial Author/Document Coordinator by default, so that they are given the appropriate level of access according to the document state. When the document becomes “Final”, the Authors are given VERSION access but as they are not the owners of the document they created, they cannot override the permits assigned to them by the role-based access control policy. The Document Creator has no special privileges; the documents are effectively “owned” by the system, as opposed to individual users. 161 Security To accomplish this, the Category 1-3 lifecycle models contain a dummy initial state, “(init)”, which transfers ownership to the admingroup, assigns the creating user to the Authors role, sets the initial lifecycle state to “Draft”, and applies the role-based security accordingly. Thus, although the initial lifecycle state is set to “(init)”, the actual initial lifecycle state is “Draft”. (The “Draft” state cannot be used to transfer ownership, because documents are sometimes reverted back to “Draft” from other states, e.g. as a result of creating a new version of an “Effective” document, and this would fail if the user does not belong to the admingroup. Therefore, a dummy initial state must be used in the D2 lifecycle configuration.) In the Cat 1-3 security model, users who can bring about state changes (that is, Authors and Document Coordinators) are given the “change state” and “change permit” extended permits, so they can effect state transitions even though they are not the document owners. The owners (that is, admingroup) are given full permissions, so they can fix up documents as and where necessary. It is not necessary to reassign Category 1-3 documents to new owners as users leave the organization or change roles, or for the admingroup to change permissions in order to make adhoc changes, making the repository easier to maintain. Folder Security Cabinets and folders may be created automatically by D2 as a result of auto-filing/auto-linking rules. Access to these folders is governed by separate security configurations that are referenced in the auto-filing/auto-linking path configuration at each level in the file plan. This enables access to be restricted to users in the appropriate functional area master groups, and for cabinets/folders to be hidden to users in other groups. For example, the auto-linking path for Clinical documents use the Clinical Folder Security Model configuration, which grants DELETE access to members of the cd_clinical group and sets the default (dm_world) permit to NONE for all other users, so that only users in the cd_clinical group can see these folders (apart from the admingroup that is, who, being privileged users, can always access all folders in the repository). Note that this does not mean that cd_clinical users can delete any folder in the “Clinical” cabinet – they can only delete empty folders. Similarly, the auto-filing path for Change Requests (CRQs) uses the Change Request Folder Security Model configuration at each level, which grants public DELETE access to all users. This enables any user to create a change request and access it through the Change Requests cabinet/folder structure. It does not necessarily mean they can delete any change request folder; they can only delete empty folders. For example, by deleting CRQs that they themselves have raised but not yet submitted, then deleting the now-empty folder(s) that were created for them. TMF Dynamic Role-Based Access Control (eTMF Only) In the Documentum eTMF solution, external trial participants involved in a clinical trial can be registered for access to specific parts of the Trial Master File (TMF) related to that trial. This enable them to access the relevant documents and folders in the repository depending on their role, and the scope of access required. In Documentun eTMF, registration forms represent the TMF. There is a Product Registration Form for each product and a Clinical Trail Registration Form for the trial. There is also a separate registration 162 Security form for each country in which the trial is conducted (Country Registration Forms) and each site in each country (Site Registration Forms), which can be added to the repository as the trial is rolled-out. These registration forms are used to build out the TMF in accordance with a prescribed file plan. However, managing access to external users centrally in an adhoc manner is not a workable solution. A trial may involve many sites spread over many countries, involving thousands of external users, such as Clinical Investigators, Inspectors, and external Authors/Reviewers, who are not part of the sponsoring organization. Given the large-scale, global nature of clinical trials and the relatively short-term engagement of external users in each site, coupled with the need to maintain strict controls over access to the trial documentation, an automated system is required using devolved administration, to safeguard against IP theft, protect patient confidentiality and to ensure Corporate governance and regulatory compliance. To this end, extensions are provided in Documentum eTMF to enable external users to be registered for access to a TMF at the appropriate level, that is against a trial, country or site-registration form, and in an appropriate role, such as Clinical Investigator. Registrations are valid for a designated period only. They can be set up in advance by local Administrators, and are activated and deactivated automatically by the system accordingly. The external user roles to be supported are centrally-configurable, and the access levels to be granted to each role on specific artifacts (document types) in the TMF are also centrally-configurable, according to the security requirements of the business. In this way, the registration of external users is simplified and devolved to local Administrators, and the predefined security model is enforced automatically by the system. External User Registration External users must be named Documentum users that is, they must have Documentum user accounts created for them in the repository. The user accounts for external users can be managed by conventional means, for example, through Active Directory, and synchronized with Documentum through the standard LDAP synchronization job. They are then registered in the system by associating them with a suitable role, such as Inspector or Contributor, against the appropriate registration form: • For site-level access, users are registered against the relevant Site Registration Form. • For country-wide access to all sites in a particular country, users are registered against the relevant Country Registration Form. • For study-wide access to all sites in all countries, they are registered against the relevant Trial Registration Form. The access level that a registered external user is granted on a particular document – whether they have read-write access, read-only access, or no access at all – is then governed automatically by the system, and depends on the following factors: 1. The level at which the user is registered in the system such as for a specific site, country, or an entire trial (study). 2. The role assigned to the user in their registration such as Inspector, Investigator or Contributor (the roles are configurable, although these are the standard roles that are provided out-of-the-box). 3. The time period during which the user registration is to be active. This enables access to be planned in advance, and revoked automatically when the time period expires. 163 Security 4. The position of the document in the TMF folder structure such as site-specific, country-specific, trial-level, or product-level. 5. The artifact name of the document such as Investigator Brochure. External users can be given different levels of access to different artifacts, according to their role. For example, as a Contributor, they may be able to edit certain TMF artifacts, but not others. 6. The current status of the document in its lifecycle – whether it is a Draft or Final/Effective version. The system also grants access to the relevant folders in the TMF structure automatically, enabling external users to navigate the cabinet/folder structure and locate documents in the relevant areas of the TMF while their registration is active. However, they cannot see the folders for products, trials, countries and sites that they are not registered to access. They are also provided browse-level access to the relevant registration forms, so that they can search for documents based on product codes, trial IDs, countries and sites for which they are registered. However, they cannot search on product codes, trial IDs, countries and sites that they are not registered to access – access is strictly on a need to know basis. If an external user is registered for access at a higher level than for an individual site, that is at the country or trial level, the registration is assumed to apply to all of the relevant sites for that country or trial. In other words, their registration fans down to the site level. Likewise, if a TMF document is created at the country, trial or product level, then it is assumed to apply to all of the relevant sites. So, if a user has been granted access to a particular artifact at the site-level, they also have the same level of access to the same artifact at the country, trial and product level. In other words, their access also fans up to the relevant artifacts at the peer levels. Note that for logistical reasons it is not possible to register external users for compound or product-level access to all sites across all studies or trials associated with a particular product using this mechanism. Doing so would impact the system extensively whenever a product-level registration is updated. However, it may be possible to accomplish this through other means, for example, by managing access to individual documents manually on an adhoc basis. 164 Chapter 11 Configuration Tasks This chapter contains the following topics: • Auditing Events, page 165 • Configuring Search Criteria, page 167 • Hard Delete (Documentum eTMF), page 167 • Bulk Import-Export (Documentum eTMF), page 169 • Configuring Roles and Permissions for External Participants (Documentum eTMF), page 173 • Distributed Server Method Processing, page 181 • Media Files, page 185 • D2 Mailing Configurations, page 185 Auditing Events D2 auditing is used to capture and record key events as documents progress through their lifecycle. It is possible to reconfigure the audited events for each category of documents independently, if necessary. In the default configuration, the following events are audited. For Cat 1-3 controlled documents and Change Requests, the following events are audited: • Document creation • Document deletion (including D2 recycle bin delete/restore events) • Document versioning (check-in events) • Document property updates, including changes to role members and/or Effective, Review, and Expiry dates, as and where applicable (audited explicitly) • Document lifecycle state changes • Creation of relations • Removal of relations • Workflow initiation • Workflow termination (abort events) • Workflow task acquisition 165 Configuration Tasks • Workflow task forwarding (completion) • Workflow task rejection • Workflow task delegation For Cat 4 documents, the same events as Cat 3 are audited except for workflow events, since there are no defined workflows for these documents in the default configuration. (Auditing of Cat 4 events can be disabled if preferred.) In the case of Registration Forms, the following events are audited: • Form creation • Form deletion • Form property updates, including changes to the primary key values such as product codes (audited explicitly) • Form lifecycle state changes The EMC Documentum for Life Sciences Installation Guide provides the steps for configuring audit events. Configuring Audit Events Administrators can specify the events that the system audits in D2-Config. Administrators can also restrict the audited events shown to users. Auditing an event creates an audit trail entry, which captures the process of creating, reviewing, approving, and releasing information in an electronic record. Audit trails facilitate the reconstruction of events relating to an electronic record. The Life Sciences solutions are preconfigured to audit events according to best practices, but you can modify the events based on your own requirements or preferences. 1. Log in to D2-Config as an administrator. 2. Select EMC Controlled Document Foundation from the configuration filter. 3. Select Audit from the Configuration elements list. 4. Select the document group to audit. 5. Specify the events to audit: • Select events from the Auditable events list and add them to the Audited events list. The system audits the events in the Audited events list. • To no longer audit events, select the events from the Audited events list and move them to the Auditable events list. 6. Specify the audited events shown to users: • Select events from the Audited events list and add them to the Displayed events list. Users can only see events in the Displayed events list. • To hide audited events from users, select events from the Displayed events list and move them to the Audited events list. 166 Configuration Tasks 7. Save the configuration. 8. To view the audit events in D2 Client, administrators grant users the View Audit extended privilege in Documentum Administrator. Configuring Search Criteria Administrators can change the Advanced Search Configuration in D2-Config. This feature allows administrators to define types and properties from the repository that appear in the D2 Client Advanced Search interface. 1. Log in to D2-Config as an administrator. 2. Select EMC Controlled Document Foundation from the configuration filter. 3. Select the Search element from the Configuration elements list and then select the Advanced Search Configuration element. 4. In the Search configuration & properties mapping area, select a type from the Type list. Use the arrows to add or remove items from the selection list. 5. In the Properties of selected type area, add or remove properties to refine the search. 6. Save the configuration. If additional attributes are added as facets, configure the attributes for indexing by Documentum xPlore as described in and the EMC Documentum xPlore Administration Guide. Hard Delete (Documentum eTMF) Documentum eTMF enables users to permanently remove documents using the Hard Delete functionality. When users perform a Hard Delete of a document, Documentum eTMF audits the event. You can search for these events in the audit trail. For example, if a user improperly scans or imports a document into the TMF, users with permissions can perform a Hard Delete the document to remove it. By default, the system is configured to only allow clinical document coordinators (members of the cd_clinical_doc_coordinators group) to perform a Hard Delete of documents in the Withdrawn state. Prerequisties for performing a Hard Delete of document(s): • The selected document(s) should not be in the checked-out state. • The document should match the criteria specified through the cd_delete_config object. Hard Delete of placeholders is not supported. The Delete menu item can be disabled/hidden. The Hard Delete feature can be configured through the docbase object cd_delete_config. A default instance of this object is provided with Documentum eTMF DAR file that is configured as shown in the following table. 167 Configuration Tasks Table 23. Configuring the Hard Delete feature Attribute Name Single/Repeating Purpose Default Value doc_type Single Document type on which users can perform a Hard Delete. cd_clinical_tmf_doc doc_statuses Repeating Documents status (refers to valid values for a_status attribute like DRAFT, Withdrawn, Expired and so on). Withdrawn roles Repeating User roles who can perform a Hard Delete operation. cd_clinical_doc _coordinators auditted_attributes Repeating Attributes of documents selected for Hard Delete that must be added in the dm_audit_trail table for the event cdf_hard_delete (maximum limit 6). NIL Note: This attribute is not used to validate if the document qualifies for hard delete or not. You can adjust the default configuration of the Hard Delete feature to meet your business requirements by following these steps. 1. Log in to D2-Client as a member of cd_admingroup. 2. From the Repository browser, navigate to System/CDF/Delete Config. 3. Right-click the TMF Doc Delete Config object and click Properties. Caution: Only one instance of this object can exist at any point in time. If you create multiple instances of this object, Hard Delete may not work correctly. 4. 168 Configure the TMF Doc Delete Config properties as defined in the following table: Field Description Name Shows TMF Doc Delete Config. Title Shows TMF Doc Delete Config. Document Type Select the document type that selected user roles can hard delete. For example, cd_clinical_tmf_doc. Configuration Tasks 5. Field Description Document Statuses Select the statuses that the document must be in before users can hard delete it. User Roles Select the user roles that can perform the hard delete. Attributes to Audit Select the document attributes to capture in the audit trail for the cdf_hard_delete event. The system audits a maximum of six attributes. Click OK. You can view hard deleted documents in D2-Client using the Find Delete Audit Events search query. Note: In the repository, you can delete related documents by setting the integrity_kind attribute in the dm_relation_type table for that relationship type to 2. The system deletes both the original document (referred to by parent_id in the dm_relation table) and the related document (child). However, deleting the child does not delete the parent in the repository. The system records only the dm_destroy event (not the cdf_hard_delete event) for the related document. If the integrity attribute is set to 0 or 1, the hard delete fails with an error message. The standard Documentum functionality is that after an object is deleted, the content file relating to it is not deleted until the dm_DMClean job is run. Therefore, prior to execution of dm_DMClean, it is possible to recover the content. Configuring the dm_DMClean job as part of Hard Delete is not supported. Bulk Import-Export (Documentum eTMF) A document package is an arbitrary collection of documents, folders and/or virtual documents in Documentum that can be packed into a ZIP file (including content files, renditions and metadata) and unpacked from a ZIP file back into the repository. Using document packages, users can easily package up and export a set of documents and send these to an external agency for offline editing and completion. Any changes can then be imported back into the repository as a ZIP file and unpacked. The Documentum eTMF solution uses document packages to import and export TMF placeholders, documents, and associated document information (metadata). A document pack is represented as an object of type cd_document_pack in the repository (a sub-type of cd_controlled_doc) with a series of dm_relations linking it to the various objects included in the package. The following figure illustrates this representation. 169 Configuration Tasks The document package is the parent object in a Package Item relation, and the various items are child objects. The child objects can be individual documents, folders, or virtual document nodes. In the case of folders and virtual documents, the subordinate objects are included automatically in the document pack, in recursive fashion. The document pack has a main content file that is, either a Microsoft Excel spreadsheet (when new or unpacked) or a ZIP file (when packed). The Excel spreadsheet is derived from a template and is used to record the Documentum metadata for each item when the document pack is packed. The Excel spreadsheet template is part of the default installation and is defined as a cd_content_template object in the repository, with the domain set to Document Pack. Lifecycle Model for Document Packages A document pack has a D2 lifecycle configuration associated with it, comprising the following states. Table 24. Lifecycle model for document packages State Description New Newly-created document pack. Refreshing A transient state representing a document pack that is being refreshed (that is, the spreadsheet is being regenerated with the appropriate metadata). When the refresh process is complete, it reverts to New. Packing A transient state representing a document pack that is in the process of being packed (through an asynchronous server method). 170 Configuration Tasks State Description Packed A document pack that has been packaged up into a ZIP file and is ready for export or unpacking, as appropriate. Unpacking A transient state representing a previously packed document pack (or one that has been imported as a ZIP file) that is in the process of being unpacked (through an asynchronous server method). Unpacked A document pack that has been successfully unpacked into the repository, that is, any changes such as new or modified documents have been applied. Invalid A document pack that could not be processed for some reason; for example, it refers to document files that do not exist. The “Importing and Exporting Multiple Documents” section in the EMC Documentum Electronic Trial Master File User Guide provides more information about the bulk import-export process. The EMC Documentum for Life Sciences Installation Guide provides the steps to configure bulk import-export. Note: In the Bulk Import-Export Excel spreadsheet, the LIFECYCLE_STATE is set to Read-only (‘Y’) by default. This setting does not allow lifecycle transition to be considered when importing documents. All documents will be imported in the “Draft” state even if the user specifies a different state in the Status column, such as Final, To be Reviewed, and so on. To import documents to the repository in the specified document status and perform lifecycle transitions, you must set the Read-only column to ‘N’. Configuring the Bulk Import-Export Spreadsheet EMC Documentum eTMF provides the ability to import and export Trial Master File (TMF) placeholders, documents, and associated document information (metadata). The package contains a Microsoft Excel spreadsheet that contains metadata, known as the bulk import-export spreadsheet. You can configure the spreadsheet to use any properties that exist on the cd_clinical_tmf_doc type or your own custom type. The system synchronizes any dictionaries associated to properties on the Schema worksheet of the spreadsheet. This procedure shows you how to add a Documentum attribute to the bulk import-export spreadsheet. You can find detailed information within the spreadsheet template to make additional configurations. 1. Log in to D2 Client as a member of cd_admingroup. 2. From the Repository browser, navigate to Templates/D2. 3. Right-click TMF BulkUpload.xls and select Edit. 4. Add a column to the File List worksheet. For example, add a Subject column. 171 Configuration Tasks 5. On the Schema worksheet, add a row for the data field definition as described in the following table: Column Description Worksheet Type File List to indicate that the data resides in the File List worksheet. Column Heading Type the column name for your attribute. For example, Subject. Data Field Type the Documentum attribute name or your custom attribute name. For example, subject. Default Value (Optional) Type a default value for blank cells. Read-only Type Y if it is a read-only attribute. During an export, the system reads the attributes from the repository and writes them to the spreadsheet. The system ignores this column on import. Consider highlighting the column in light blue so that the end users know that it is a read-only column. Type N to enable the system to read the metadata in this column and write it to the repository on import. Do not change the information for the pre-populated system data fields. The following example shows information added to the Schema worksheet for the Documentum attribute column: The following example shows the Documentum attribute column highlighted in light blue to indicate that it is a read-only column: 172 Configuration Tasks 6. Save the Microsoft Excel Spreadsheet in Microsoft Excel 97-2003 format (.xls format). The zip library in Java 1.6 does not support the ZIP64 standard and therefore, cannot be used to zip large files. To resolve this, you must modify the value of the -zip_library parameter in the TMFImportExportPackageMethod. By default, the -zip_library parameter value is set to 0, which enables the use of the Java zip library. Setting the parameter value to 1 enables the system to use the Apache Commons zip library, which supports the ZIP64 standard. If the parameter is left out, 0 is assumed by default. An Alias column has been added to the Schema worksheet to enable dictionary aliases to be specified. For example, you can add a "Synonym" alias to the "TMF Unique Artifact Names" dictionary and override the default artifact display names in this column. If a dictionary alias is not specified or blank, the locale setting is used for dictionary lookups. The default locale is "en" (English) although this can also be specified in the schema settings. Configuring Roles and Permissions for External Participants (Documentum eTMF) EMC Documentum Electronic Trial Master file allows you to provide direct, tailored access to TMF documents and placeholders for external trial participants such as Inspectors or Contract Research Organizations (CROs). Documentum eTMF contains four preconfigured roles, but you can add additional roles or disable the default roles as needed. You can configure each role defined in the system to have different permissions at the artifact level. For example, an External Contributor can have Reader access to some artifacts, Author access to other artifacts, and None access to others. Configuring the roles and their permissions in the Documentum eTMF system is a two-step process. First, you define the role and then you assign the role permissions at the artifact level. An IT administrator performs this configuration based on business requirements. Changes to the role definitions do not affect existing trials and related registration objects unless the security is refreshed explicitly, so it is important to define your business rules as part of your implementation project. In this way, the roles and their permissions are consistent across your system, regardless of the country or site assigned to an external participant. This section describes how to create the external roles in your system and assign the roles security at the artifact level. Once defined, the roles are available to Trial Managers so they can assign a user as 173 Configuration Tasks an external role to a country or site. For example, if a regulatory authority is inspecting two sites, the Trial Manager can add the user as an External Inspector to those sites. By doing so, the user receives the configured access to only the documents in those sites (including all country, trial, and product documents related to those sites), and nothing more in the system. The preconfigured roles are: • External Contributor • External Reviewer • Inspector • Investigator To define the roles and permissions, complete the following procedures: • Defining External Trial Participant Roles, page 174 • Defining Permissions for External Participant Roles, page 177 The following procedure provides an example of how to add a new role in your system: • Adding an External Participant Role Example, page 178 Defining External Trial Participant Roles Documentum eTMF includes predefined roles that enable you to provide direct access to your Documentum eTMF system for external trial participants. You can configure the roles based on your business requirements. 1. Log in to D2-Config as an administrator. 2. Select EMC Life Sciences eTMF Solution from the configuration filter. 3. Select Data > Dictionary from the menu bar. 4. In the Dictionaries list, select TMF External Contributor Roles. 5. On the Alias tab, configure the external participant roles as defined in the following table: Column Description (Checkbox) Select the checkbox for each role to include as an external participant. To add a role, type information in a blank row with the checkbox selected. To remove a role, clear the checkbox for that role. Key 174 Type a user-friendly role name. These participant role names appear as selections for users in drop-down lists. For example, you can type Contractor in the Key column for a new role. Configuration Tasks Column Description Group Name Suffix Type a unique suffix for your participant roles. For example, you can type _contract for a new document Contractor role. The system uses this suffix to configure the dynamic role group naming conventions. The EMC Documentum Electronic Trial Master File User Guide provides additional information on external trial participant groups. It is not necessary to change the Group Name Suffix for the default roles. Note: By convention, Documentum group names use lower-case letters and underscore symbols. Do not specify excessively long group name suffixes, as the group names are limited to 48 characters in total. Taxonomy Dictionary Level Type the participant names to use for the dictionary referenced by the taxonomy. This name must be identical to the name of the dictionary created for a particular participant role. For example, if you type TMF Contractor Access for a new role in this column, the system requires a dictionary for this role with the same name. It is not necessary to change the Taxonomy Dictionary Level name for the default roles. If you decide to change it, the system requires a dictionary for the role with the same name. File Plan Column Alias Context Group Type a column alias in upper case letters with no spaces. This alias is for system use. For example, you can type CONTRACTOR for a new role. Note: This setting is not currently used. It is reserved for future use. Type the name of the top-level group associated with this role. For example, for the preconfigured External Contributor role, the top-level group is tmf_external_contributors. This is used to associate a Documentum D2 workspace with the members of this group so that users working in a particular role can access the appropriate workspace. You can modify the predefined workspaces and configure additional workspaces if necessary, 175 Configuration Tasks Column Description and associate them with the relevant groups. If a user has only one workspace available, it is preselected automatically when they log in to D2 Client. Otherwise, they can choose the appropriate workspace when they log in. For example, you can type tmf_contractor. The EMC Documentum Electronic Trial Master File User Guide provides additional information on external trial participant groups. 6. Save the configuration. 7. For each context group that you add: a. In Documentum Administrator (DA), create a role with the same name as the context group. For example, if you create the context group tmf_contractor, create a role in DA named tmf_contractor. b. In D2-Config, select Go to > Context from the menu bar, click New, to create a context with a similar name. c. In the Group area, move the context group to the Selection area of the context and save the configuration. d. Click Matrix and map the context to a workspace. Click to place a checkmark at the intersection of the context and the workspace. 8. For each participant role that you add, copy the TMF Document Roles dictionary to create a new dictionary: a. Select Data > Dictionary from the menu bar. b. In the Dictionaries list, select TMF Document Roles and click Create from on the toolbar. c. Type a name for this copy of the dictionary. This name should be the same as the name defined for the participant role in the Taxonomy Dictionary Level column of the TMF External Contributor Roles dictionary. For example, TMF Contractor Access. d. Do not make any other changes and save the configuration. 9. Update the TMF Classification by Artifact taxonomy with your participant roles: a. Select Data > Taxonomy from the menu bar. b. In the Taxonomies list, select TMF Classification by Artifact. In the dialog box, select Excel as the file format and click Modify. Save the file to your local machine. c. 176 Adjust the default TMF External Contributors, TMF External Reviewers, TMF Inspector Access, and TMF Investigator Access columns of the spreadsheet based on your role definitions. These columns must match the name of the dictionaries created for each role. For example, TMF Contractor Access. Add a column for each additional role. If you remove a role, remove the column for that role. Configuration Tasks d. Save the file, import it, and save the configuration. Related topic: • Adding an External Participant Role Example, page 178 Defining Permissions for External Participant Roles Documentum eTMF provides predefined document permissions for each external trial participant role. If necessary, you can define individual document access permissions (for example: None, Reader, Author, Reviewer) for each external trial participant role. 1. Log in to D2-Config as an administrator. 2. Select EMC Life Sciences eTMF Solution from the configuration filter. 3. Select Data > Taxonomy from the menu bar. 4. In the Taxonomies list, select TMF Classification by Artifact and edit the taxonomy. In the dialog box, select Excel as the file format and click Modify. Save the file to your local machine. 5. In the TMF External Contributors, TMF External Reviewers, TMF Inspector Access, and TMF Investigator Access columns of the spreadsheet, type the document-level roles for each artifact in the cells of the columns. If you adjusted or added additional role columns, type the document-level roles for each artifact for your defined roles. The following figure shows an example of document-level access changes in the TMF External Reviewers column and an additional TMF Contractor Access column added for a new role: In practice, these role setting are most likely to be Author to provide read and write access and either Reader or Auditor for read-only access. The available roles are defined in the following table: Role Description Document Coordinator Has full access and can reassign document-level roles and define the effective period of a Category 1 document Author Has read and write access to work-in-progress versions and can self-approve Category 3 documents 177 Configuration Tasks 6. Role Description Reviewer Can participate in a review and approval workflow Approver Electronically-signs a Category 1-2 document through a review and approval workflow Reader Has read-only access to Effective versions Auditor Has read-only access to release-ready versions, including historic release-ready versions. For example, Release Pending, Effective, Superseded, but not work-in-progress and Withdrawn versions. None Has no access to this artifact (the artifact is hidden) Save the file, import it, and save the configuration. The EMC Documentum D2 Administration Guide provides more information on configuring D2-Config. Adding an External Participant Role Example This procedure provides an example of how to add an external trial participant role, Contractor, to your system. 1. Log in to D2-Config as an administrator. 2. Select EMC Life Sciences eTMF Solution from the configuration filter. 3. Select Data > Dictionary from the menu bar. 4. In the Dictionaries list, select TMF External Contributor Roles. 5. On the Alias tab, configure the blank row for the new role as defined in the following table: 178 Column Configuration example (Checkbox) Select the checkbox. Key Type Contractor. Group Name Suffix Type _contract. Taxonomy Dictionary Level Type TMF Contractor Access. File Plan Column Alias Type CONTRACTOR. Context Group Type tmf_contractor. Configuration Tasks 6. Save the configuration. 7. In Documentum Administrator (DA), create a role with the same name as the context group. In this example, create a role in DA named tmf_contractor since the context group is named tmf_contractor. 8. Create a context for the role: a. In D2-Config, select Go to > Context on the menu bar, click New, and create a context with a similar name, such as TMF Contractors. b. In the Parents area, select TMF Roles. c. 9. In the Group area, select and move the context group to the Selection area of the context and save the configuration. Click Matrix and map the context to a workspace:. a. Expand the TMF Roles context. b. Click to place a check mark at the intersection of the context and a workspace. 179 Configuration Tasks c. Save the configuration. 10. Copy the TMF Document Roles dictionary to create a new dictionary: a. Select Data > Dictionary from the menu bar. b. In the Dictionaries list, select TMF Document Roles and click Create from on the toolbar. c. Type TMF Contractor Access as the name for this copy of the dictionary. This name should be the same as the name defined for the participant role in the Taxonomy Dictionary Level column of the TMF External Contributor Roles dictionary. d. Do not make any other changes and save the configuration. 11. Update the TMF Classification by Artifact taxonomy with the participant role: a. Select Data > Taxonomy from the menu bar. b. In the Taxonomies list, select TMF Classification by Artifact. In the dialog box, select Excel as the file format and click Modify. Save the file to your local machine. c. 180 Add a column with the label TMF Contractors next to the other external participant role columns. The column name must match the name of the dictionary that you created for the role. Configuration Tasks d. In the cells of the TMF Contractors column, type the document-level roles for each artifact for your defined roles. For this example, type Auditor in the cells to provide read-only access for each artifact to the role. e. Save the file, import it, and save the configuration. Distributed Server Method Processing In the Life Sciences solution, a concurrent server method processing framework is provided to improve the efficiency and scalability of server methods. Life Sciences supports both multi-threading and distributed processing for the following operations: • Applying attribute inheritance rules to multiple documents and registration forms in Documentum Q&M, Documentum eTMF, and Documentum R&D. For example, to reapply Documentum D2 auto-naming to affected documents and registration forms when a Manager changes a product code. • Generating missing TMF placeholders on trial activation and refresh in Documentum eTMF. • Updating the dynamic access control groups for external participants in a TMF in Documentum eTMF. For these operations, the standard settings allocate up to five threads for local multi-threaded processing, but disable distributed processing. To use distributed processing, set up a multi-node Content Server architecture with at least two Content Servers. Using D2-Config, enable the distributed processing options in the System Parameters dictionary. Because of the caching of the dictionary settings, ensure that you restart the relevant Java Method Server services to make the configuration changes effective. If there is sufficient CPU capacity, you can also increase the number of processing threads per server. Do not over-optimize the system solely for TMF processing, because it can result in diminished performance of the repository overall. It is important to remember that Documentum has to serve interactive users, Documentum D2 lifecycle operations, workflows, and other batch processes at the same time. To balance the loads effectively in multi-node architectures, it is possible to allocate some of the servers for interactive use and others for batch processing. Contact EMC Documentum Professional Services for assistance with analyzing your TMF system architecture and performance tuning. 181 Configuration Tasks Enabling Distributed and Multi-threaded Processing Distributed processing enables large batch jobs to execute across multiple Content Servers. The system balances the workload over the available content servers and uses distributed processing only for large datasets. 1. Verify that multiple Content Servers are available. The repository should have more than one dm_server_config object registered. 2. Log in to D2-Config as an administrator. 3. Select EMC Controlled Document Foundation from the configuration filter. 4. Select Data > Dictionary from the menu bar. 5. In the Dictionaries list, select System Parameters. 6. On the Alias tab, configure the system parameters as defined in the following table: Parameter Description content_servers Type the Content Servers available for distributed processing. Use a comma-separated list of dm_server_config names, or * to use all available servers. To enable distributed processing, specify two or more Content Servers. To disable distributed processing, set this value to a blank string. distributed_processing_threshold Type the minimum data size for invoking distributed server methods in multi-node Content Server architectures. To enable distributed processing, set this parameter to at least 2. For example, if you set it to 1000, batches of 1000 objects or more distribute across the available servers, but batches with less than 1000 process locally. To disable distributed processing, set this parameter to 0 (zero). Distributed processing is disabled by default. Note: Set this value to a reasonably high level to avoid the overheads of distributing processing tasks when there are relatively few objects for processing. In this case, it would be more efficient to process them locally. 182 Configuration Tasks Parameter Description max_threads Type the maximum number of server method threads per Content Server for local processing. The minimum value is 1, in which case the tasks are processed sequentially in single-threaded mode. The default setting is 5. There is no defined maximum value, but increasing it up to or beyond the point at which the Content Server CPU becomes saturated is not recommended, as this can be detrimental to the performance of the repository overall. shared_folder (Optional) Type a dm_location name or explicit path of a network-shared folder to use to interchanges data efficiently between content servers for distributed processes. If you do not define this value, data exchanges through temporary binary objects stored in the repository. 7. Save the configuration. 8. Restart the Java Method Server. Disabling Parallel Processing for CFD Methods Distributed parallel processing has been implemented for the following CDF methods and utilities, which helps create multiple threads across available content server instances to share the load while processing logic: • CDFVirtualDocumentMethod • CDFApplyAttributeInheritanceMethod This existing distributed parallel processing logic reads the System Parameters dictionary and processes the content_servers configured in the dictionary, assuming that all the server names configured in the dictionary are up and running. In addition, it just picks the threshold as 100, which is the default value. It is up to users to enable or disable the distributed processing by configuring the following parameters in the dictionary: • content_servers • distributed_processing_threshold To disable the parallel processing, the parameters must be set to null. 183 Configuration Tasks Change Request Configurations (LSQM) The following sections provides steps to disable the Change Request functionality in Documentum Q&M and steps to prevent a Change Request document from being sent to a workflow when a non-current version of a document is attached to it. Disabling Change Request for Category 1 Documents The following procedure enables you to send a Category 1 document to a workflow without associating it to a Change Request: 1. Log in to D2-Config as Administrator. 2. Select All elements from the configuration filter on the main toolbar. 3. Click Go to > Workflow. 4. Under Workflow List, select Cat 1 Approve Site Performers [1-GMP-APPROVE]. 5. Under Workflow entry conditions, remove the Validate document is associated with a CIP Change Request uniqueness condition and click Save. 6. Perform steps 4 and 5 for the Cat 1 Review Approve Site Performers [1-GMP-REVIEW -APPROVE] workflow. To disable the Change Request functionality: 1. Log in to D2-Config as Administrator. 2. Select All elements from the configuration filter on the main toolbar. 3. On the Creation menu, click Creation profile. 4. Under Profiles, select Change Request. 5. Under Properties, in the Users group field, replace cd_gmp_authors with admingroup. 6. Click Save. Disabling Workflows for Change Requests with Non-Current Document Versions Attached In the system, Change Request documents can be sent to a workflow even if a non-current version of a document is attached to the Change Request. To disable such Change Requests from being sent to a workflow if the current version of the document is not attached to them, follow these steps: 1. Log in to D2-Config as Administrator. 2. Select All elements from the configuration filter on the main toolbar. 3. Click Go to > Lifecycle. 4. Under Lifecycles, select Change Request Lifecycle Model. 184 Configuration Tasks 5. Under Properties, select (Checkin) in the table and in the Extra arguments field, type "-bind current". 6. Click Save. 7. Click Go to > Workflow. 8. Under Workflow List, select Change Request For Approval Workflow [CR-APPROVE]. 9. Under Workflow entry conditions, click the + icon to add a new row. 10. In the new row, under Entry condition ?, select Condition on uniqueness, and in the Check field, select Validate selected Change Request document has only CURRENT version child documents available. 11. Click Save. 12. Perform steps 8 through 11 for the Change Request For Review/Approval Workflow [CR-REVIEW-APPROVE] workflow. Media Files Media files, such as video, can be previewed in Documentum through the Life Sciences Document Preview widget. Any media file format supported by Windows Media Player can be previewed: the formats that are supported can be specified in the optional "mediaFormats" URL parameter to the Life Sciences Document Preview widget as a comma-delimited list of dm_format names. Where unspecified, the default formats are: wmv, avi, mpg/mpeg/mpg-4v, quicktime, and wav files. D2 Mailing Configurations Email configuration in D2 can be used for the following purposes: • Create mailing lists that end users can use to send preconfigured batch email messages. • Send email messages directly from the D2 Client. • Create email distributions based on events. • Create subscriptions-based events such as workflows, lifecycle transitions, and so on. Types of Mailing Configurations The following table lists the object types used in the configuration of D2 mailing: 185 Configuration Tasks Table 25. Object Types for Configuring D2 Mailing Object Type Description Configurations Result d2_mail_config You can configure the mailing server, event-based mailing, and subject and message for triggering event mails. D2-Config > Tools > Email End users receive notifications when a workflow is initiated for a document. You can enable hyperlinks for enabling the user to directly navigate to the task and approve or reject it based on the business use case. You can configure the email subject, message, and attachment behavior to enable end users to send email messages concerning a selected object. D2-Config > Go to > Send Email You can configure content import such that when an end user imports an email message with an attachment, the attachment is processed and saved in the repository as a rendition. The supported content types are .eml or Outlook formats. D2-Config > Creation > Mail Attachments d2_sendmail_config d2_mail_attachment _config d2_mailing_config 186 You can configure the recipients, subject, message, and attachments that should be included in an email message. Ensure that the email server is configured and the relevant email events are configured based on the business requirement. Email templates can be configured and mapped with different role-based contexts enabling those users to use the template when they use the Send Email option. This is a global setting that allows users to import attachments in email messages and allow the system to create rendition of the imported email message and its attachments. D2-Config > Go to > Mailing list Ensure mailing lists are configured for the specific set of users in the system and can be used when configuring lifecycle transitions, context mapping based on End users want the ability to send messages to both internal and external users of D2 system for a selected object. Using the Send Mail configuration, you can predefine the message and subject of the email to streamline this task. End users need to import email messages with attachments and retain the same format of the email and create renditions of the email messages and its attachments. End users need to send the messages to users notifying or reminding them of a document that needs to be reviewed. The end user selects the document and chooses the mailing list that has been configured, which is Configuration Tasks Object Type d2_subscription _config Description You can define specific events and associated email messages that end users can subscribe to, so that they can be alerted when the event occurs. Configurations Result conditions and enable email trigger to the users based on the conditions. then automatically sent to the predefined recipients with applicable message and attachment. D2-Config > Go to > Subscription End users want to be notified any time someone checks in a new version of a particular document. By creating a subscription, they can subscribe to this event for the document and be notified by email when a new version has been checked in. Subscription templates can be created for events and mapped with different role-based contexts. This enables users to subscribe events to get email notifications using the Subscribe option and select templates based on the business requirement. Note: You cannot preset subscription for users. It is based on user preference. d2_distribution_config You can configure a simple workflow-like process where you can define attachments, property pages, recipients, email messages, and any electronic signature requirements when accepting or rejecting the requested distribution actions. D2-Config > Go to > Distribution Enable users to send bulk email. The distribution templates or user email messages can be preconfigured and mapped to context based on which users can use the same in the system through the Distribution option. End users want a quick way of sending a document for review to reviewers but want to make sure that they accept or reject the new changes in the document. Further, any approval must be electronically signed and the approver must indicate the reason for approval. Configuring Mailing Configurations The EMC Documentum D2 Administration Guide provides the information for configuring the Mail Server, Mailing list configurations, Send mail configurations, subscriptions, and distributions configurations in D2. 187 Configuration Tasks List of Task Variables The following table lists the task variables that you can use to configure D2 email configuration, for example, event dm_startedworkitem Table 26. List of Task Variables Variable Syntax docbase_name: $value(docbase_name) due_date: $value(due_date) event_name: $value(event_name) message_text: $value(message_text) object_name: $value(object_name) package_id: $value(package_id) planned_start_date: $value(planned_start_date) task_priority: $value(task_priority) router_id: $value(router_id) router_name: $value(router_name) sender_name: $value(sender_name) supervisor_name: $value(supervisor_name) task_name: $value(task_name) task_number: $value(task_number) recipient_login_name: $value(recipient_login_name) recipient_os_name: $value(recipient_os_name) recipient_name: $value(recipient_name) platform: $value(platform) mail_user_name: $value(mail_user_name) stamp: $value(stamp) date_sent: $value(date_sent) link_cnt: $value(link_cnt) package_type: $value(package_type) content_type: $value(content_type) content_size: $value(content_size) dos_extension: $value(dos_extension) web_server: $value(web_server) web_server_type: $value(web_server_type) temp_file_name: $value(temp_file_name) mailScript: $value(mailScript) 188 Configuration Tasks Variable Syntax bulk_mail_file: $value(bulk_mail_file) smtp_server: $value(smtp_server) Subject $value(Subject) Message $value(Message) task.subject $value(task.subject) task.message $value(task.message) user_name $value(user_name) password $value(password) domain_name $value(domain_name) launch_async $value(launch_async) document.object_name $value(document.object_name) Message Configuration When mapping the appropriate events in the Email Configuration, you can specify the subject and message for events. You can embed HTML messages with hyperlinks and images in the email messages. The following sample code shows HTML messages with hyperlinks and images in the email messages: <html> <head> <meta http-equiv=Content-Type content="text/html; charset=windows-1252"> <meta name=Generator content="Microsoft Word 14 (filtered)"> <style></style> </head> <body lang=EN-US link=blue vlink=purple> <div class=WordSection1> <p class=MsoNormal> <span style='font-family: "Arial", "sans-serif"'>The following workflow task has been assigned to you ($value(recipient_os_name))by $value(sender_name):</span></p> <p class=MsoNormal> <span style='position: absolute; z-index: 251659264; margin-left: -7px; margin-top: 18px; width: 778px; height: 3px'><img width=778 height=3 src="notification%20message%204_files/image001.png"> </span> <span style='font-family: "Arial", "sans-serif"'><br> <br></span></p> <table class=MsoTableGrid border=0 cellspacing=0 cellpadding=0 style='border-collapse: collapse; border: none'> <tr style='height: 31.9pt'> <td width=101 valign=top style='width: 76.1pt; padding: .05in 5.75pt .05in 5.75pt; height: 31.9pt'> <p class=MsoNormal align=right style='text-align: right'> <b><span style='font-size: 10.0pt; font-family: "Arial", "sans-serif"'>Task:</span></b></p></td> <td width=537 valign=top style='width: 402.7pt; padding: .05in 5.75pt .05in 5.75pt; height: 31.9pt'> <p class=MsoNormal> <span style='font-size: 10.0pt; font-family: "Arial", "sans-serif"'>$value(task_name) for value(document.object_name)</span></p></td></tr> <tr style='height: 30.1pt'> <td width=101 valign=top style='width: 76.1pt; padding: .05in 5.75pt .05in 5.75pt; height: 30.1pt'> 189 Configuration Tasks <p class=MsoNormal align=right style='text-align: right'><b> <span style='font-size: 10.0pt; font-family: "Arial", "sans-serif"'>Subject:</span></b></p></td> <td width=537 valign=top style='width: 402.7pt; padding: .05in 5.75pt .05in 5.75pt; height: 30.1pt'> <p class=MsoNormal> <span style='font-size: 10.0pt; font-family: "Arial", "sans-serif"'>$value(task.subject) </span></p></td></tr> <tr style='height: 31.0pt'> <td width=101 valign=top style='width: 76.1pt; padding: .05in 5.75pt .05in 5.75pt; height: 31.0pt'> <p class=MsoNormal align=right style='text-align: right'><b> <span style='font-size: 10.0pt; font-family: "Arial", "sans-serif"'>Description: </span></b></p></td> <td width=537 valign=top style='width: 402.7pt; padding: .05in 5.75pt .05in 5.75pt; height: 31.0pt'> <p class=MsoNormal> <span style='font-size: 10.0pt; font-family: "Arial", "sans-serif"'>$value(task.message) </span></p></td></tr> </table> <p class=MsoNormal> <span style='font-size: 10.0pt; font-family: "Arial", "sans-serif"'> </span> </p> <p class=MsoNormal> <span style='font-family: "Arial", "sans-serif"'> </span> </p> <p class=MsoNormal> <span style='font-family: "Arial", "sans-serif"'>Please click </span><a href="http://rbauv148.bas.roche.com:8180/D2/?docbase=$value(docbase_name) &amp;locateId=$value(stamp) &amp;locateTarget=TaskFoldersWidget"> <span style='font-family: "Arial", "sans-serif"'>here</span></a> <span style='font-family: "Arial", "sans-serif"'> to open task. </span> </p> <p class=MsoNormal> </p> </div> </body> </html> Font definitions for the above sameple: @font-face { font-family: Calibri; panose-1: 2 15 5 2 2 2 4 3 2 4; } /* Style Definitions */ p.MsoNormal,li.MsoNormal,div.MsoNormal { margin: 0in; margin-bottom: .0001pt; font-size: 12.0pt; font-family: "Times New Roman", "serif"; } a:link,span.MsoHyperlink { color: blue; text-decoration: underline; } a:visited,span.MsoHyperlinkFollowed { color: purple; text-decoration: underline; } .MsoChpDefault { font-family: "Calibri", "sans-serif"; } .MsoPapDefault { margin-bottom: 10.0pt; line-height: 115%; } 190 Configuration Tasks @page WordSection1 { size: 8.5in 11.0in; margin: 1.0in 1.0in 1.0in 1.0in; } div.WordSection1 { page: WordSection1; } All aliases are resolved when using through actual D2 environment. Images can be included in the HTML. This can be done by deploying the D2 War file or any custom War files and then using an Alias-set to point to the correct URL and file in each environment. Configuring Session Timeout For the session timeout to work with the Life Sciences solutions, the following parameters should be sequenced with the correct values: 1. DM Ticket timeout value should be greater than auto-refresh interval. 2. Auto-refresh interval should be greater than the D2 session timeout. 3. D2 web application session timeout should be equal to the session timeout on the Application Server. To configure the session timeout: 1. On the application server, configure the D2 session timeout setting in the <App_Server>\conf \web.xml file. Modify the following value in the <session-timeout> tag, which is by default 30 minutes. <session-config> <session-timeout>30</session-timeout> </session-config> 2. Configure the D2 web application session timeout setting in the <App_Server>\webapps\D2 \WEB-INF\web.xml file with the same value set in step 1. Modify the following value in the <session-timeout> tag, which is by default 30 minutes. <session-config> <session-timeout>30</session-timeout> </session-config> 3. On the Content Server, configure the DM Ticket timeout, which is the timeout value for the D2 Ticket that is used for Documentum downloads (by default, configured to 5 minutes). To modify the value from default value, add a new value in server.ini file called "client_session_timeout" and assign a value to it. 4. On the application server, configure the Auto-refresh interval in the <App_Server>\webapps \XMLViewer\DocViewer.html file. This is the configured time interval passed as the URL parameter for the widgets that is used for requesting a new D2 ticket for Documentum downloads 191 Configuration Tasks (by default, configured to 4 minutes). Modify the value in the refreshLoginTicketInterval = 240 variable. 192 Chapter 12 Workspaces and Welcome Pages This chapter contains the following topics: • Workspaces, page 193 • Display Labels, page 202 • Welcome Pages, page 202 Workspaces A workspace is a container of widgets that allows you to personalize functionality for availability and convenience. D2 includes preconfigured workspace templates. These templates contain the layout and positioning of widget areas. The templates also come with a predetermined set of widgets. Administrators can configure workspaces to contain workspace views. Views function the same way as workspaces but provide a method for organizing widgets without losing widget-to-widget interaction. In the Life Sciences solution, the organization of the D2 workspace is based on user roles. This means that all role-based view contexts, widgets, menus, and query forms are assigned to a single workspace that includes the embedded views necessary for users in that role to perform their tasks and activities. Workspace Views and Tasks The following table lists the different workspaces available in the Life Sciences solution and the tasks that can be performed in each of them. Table 27. Workspace views and tasks 193 Workspaces and Welcome Pages Workspace Views Tasks Business Administrator • Browse The following tasks can be performed in this workspace: • Tasks • Administration • Dashboard • Navigate the cabinets and folders • Search for documents using either quick search or saved searches • View details about documents such as Preview, Properties, Locations, Versions, Renditions, Relations, Audit trails, Workflow overview, and Permissions • Add or remove group memberships • Manage dictionaries • Manage taxonomies • Manage lifecycle transitions • Manage the workflow • Create new content, folder, cabinet, and group (user needs to have Create Group privileges) • Import content such as file, rendition, or a new version of a document • Check in, check out, or cancel the checkout of a document • Edit a document • View a document • View native content • Insert annotations • C2 views (Audit Report, TBR Audit Report) • Locate a document • Manage Favorites • Export a document or a folder • Print a document • Request a rendition • Delete a document 194 Workspaces and Welcome Pages Workspace Views Tasks • Create a relation • Copy link to clipboard • Process workflow tasks Coordinator • Browse • Tasks The tasks that can be performed in this workspace are similar to the Business Administrator tasks, except for managing dictionaries and taxonomies. • Dashboard Author • Browse The tasks that can be performed in this workspace are similar to the Coordinator tasks. • Tasks • Dashboard Reviewer/Approver • Browse • Tasks (this is the initial view that appears) The tasks that can be performed in this workspace are similar to the Author tasks, except that Reviewers/Approvers cannot create or import documents. • Dashboard Consumer (read-only) • Browse • Tasks • Dashboard The following tasks can be performed in this workspace: • Navigate the cabinets and folders • Search for documents using either quick search or saved searches • View details about documents such as Preview, Properties, Locations, and Relations • Manage lifecycle transitions • View a document • C2 views (Audit Report, TBR Audit Report) • Locate a document • Manage Favorites • Export a document • Print a document • Copy link to clipboard 195 Workspaces and Welcome Pages Workspace Views Tasks • Process workflow tasks (needed by recipients to process TBR task) Regulatory Manager • View Submission • Browse • Compare • Tasks • Administration The following tasks can be performed in this workspace: • Navigate the cabinets and folders • Search for documents using either quick search or saved searches • View details about documents such as Preview, Properties, Locations, and Relations • Manage lifecycle transitions • View the submissions and also the documents imported in the submission in the PDF Viewer. • Locate a document • Compare two documents. • Manage Favorites • View the locations, rendition, versions, relations, audit, and workflow overview of the content. • View the virtual document created as part of regulatory correspondence email import. • Access the tasks assigned to the user and also view its attachment and properties. • Preview the thumbnail of the object and also provide notes to tasks and view tasks details. • Control group, dictionary, and taxonomy administration Submission Contributors • View Submission • Browse • Tasks • Compare 196 The tasks that can be performed in this workspace are similar to the Regulatory Manager tasks, excluding the administration tasks. Workspaces and Welcome Pages Workspace Mapping by User Role For the Life Sciences solutions, each out-of-the-box Life Sciences user role is mapped to a D2 context as shown in the following tables. 197 Workspaces and Welcome Pages Table 28. Workspace Mapping for eTMF User Roles 198 TMF User Role Welcome Screen Browse Task QC & Index My Sites Dashboard Administration Concurrent View Author Author Welcome Screen Browse – Author /Coordinator /Contributor Y Y N N N N Contributor Author Welcome Screen Browse – Author /Coordinator /Contributor Y Y N N N N Reviewer/Approver Reviewer/Approver Welcome Screen Browse – Reviewer /Approver /Reader Y N N N N N Consumer Reader Welcome Screen Browse – Reviewer /Approver /Reader Y N N N N N Coordinator No Welcome Screen Browse – Author /Coordinator /Contributor Y Y N Y Y N Inspector TMF Inspector Welcome Screen Browse – Inspector N N N N N Y Investigator TMF Investigator Welcome Screen N Y N Y N N N Workspaces and Welcome Pages Table 29. Workspace Mapping for Q&M User Roles User Role Welcome Screen Browse Task Taxonomies Dictionaries Dashboard User Group Administration Author Author Welcome Screen Browse – Author /Coordinator Y N N Y N Reviewer, Approver, and QO Approver Reviewer/Approver Welcome Screen Browse – Reviewer /Approver /Reader Y N N Y N Reader Reader Welcome Screen Browse – Reviewer /Approver /Reader Y N N N N Coordinator N Browse – Author /Coordinator Y Y Y Y N Business Administrator N Browse – Author /Coordinator N Y Y Y Y 199 Workspaces and Welcome Pages Table 30. Workspace Mapping for R&D User Roles 200 User Role Welcome Screen Browse Task View Submission Dashboard Author Author Welcome Screen Browse – Author/Business Administrator Y N Y Reviewer/Approver Reviewer/Approver Welcome Screen Browse – Reviewer/Approver /Reader Y N Y Reader Reader Welcome Screen Browse – Reviewer/Approver /Reader N N Y Business Administrator N Browse – Author/Business Administrator Y N Y Workspaces and Welcome Pages Table 31. Workspace Mapping for SSV User Roles User Role Welcome Screen Browse Task View Submission Dashboard Author N Browse – Author/Business Administrator Y Y Y Reviewer/Approver N Browse – Reviewer/Approver /Reader Y Y Y Reader N Browse – Reviewer/Approver /Reader N Y Y Business Administrator N Browse – Author/Business Administrator Y Y Y 201 Workspaces and Welcome Pages Display Labels Labels can be set to show different values for attributes than those that are stored in Content Server. The Life Sciences solution utilizes this functionality to change the way the status label for Effective documents displays for non-Good Manufacturing Practices (GMP) documents. The display label is set to show Final instead of Effective for these documents despite the attribute being saved in Content Server with an a_status of Effective. Welcome Pages Welcomes pages in the Life Science solution are .jsp files that are called through an external widget within D2. When the user first logs in to the D2-Client, the Welcome view is displayed with a single external widget that points to these .jsp files. In addition, there is a utility .jsp file for each Welcome page that contains the DQL queries and a CSS file that contains the style information. There also exists an imgs folder that contains the images displayed on the pages. There are three basic identical Welcome pages for the Documentum Q&M and Documentum R&D for the following roles: • Authors • Reviewers/Approvers • Readers Documentum eTMF includes Welcome pages for the following roles: • Author • Contributor • Inspector • Reviewers/Approvers • Readers Each Welcome page include a menu bar and a quick action bar. The menu bar changes based on each workspace. The menu bar provides an actionable button for one view available in the workspace, which is displayed on the top left of the Welcome page. Clicking this button switches the user to the specified view. The menu bar also includes the following buttons with numbers next to them indicating the number of documents the user needs to address: • Tasks: Number of workflow tasks assigned to the user. • QC & Import: Number of documents the user has uploaded but not yet indexed. These values do not update dynamically. You must refresh the D2-Client page to update the values. 202 Workspaces and Welcome Pages The quick action bar includes the following two buttons: • Create: Invokes the D2 create_object method and displays the Creation Profile interface to the user. • Import: Invokes the D2 import_object method and displays the Import Creation Profile interface to the user. 203 Workspaces and Welcome Pages 204 Chapter 13 Regulatory Submissions This chapter contains the following topics: • Submission Overview, page 205 • Electronic Common Technical Document Submission, page 207 • Submission History XML File, page 208 • Supporting New eCTD XML Formats, page 208 • Processing Standard XML Files, page 216 • Transforming Non-Standard XML Files, page 218 • Previewing and Processing eCTD Module 1 Regional XML Files, page 221 • XML Metadata Extraction, page 224 • Non-eCTD Electronic Submission, page 231 • Submission Filestore, page 231 • Configuring the SSV Viewer Widget URLs, page 233 • Processing of PDFs and Inter-Document Hyperlinks, page 241 • Study Tagging Files, page 242 • Previewing of Media Files, page 245 Submission Overview A regulatory submission is a collection of documents (submission elements) sent to a regulatory Authority with respect to an application. For example, an Investigative New Drug (IND) application to the US Food and Drugs Administration (FDA) for approval to commence clinical trials in humans or a New Drug Application (NDA) to the FDA for approval to market a drug in the US. The application type denotes the purpose of the application (IND or NDA, in the preceding examples). An application may require several submissions to be made before it is approved. Various amendments, queries, and requests for supplementary information may be requested by the Authority and post-approval, additional submissions may be necessary from time to time, such as Periodic Safety Update Reports (PSURs). The submission type indicates the purpose of each submission, for example, an Initial Filing, Amendment, or PSUR. Both application types and submission types are regional – different application and submission types are used in different 205 Regulatory Submissions geographic regions. For example, the IND and NDA application types pertain to the US, whereas the European equivalents are CTA (Clinical Trials Approval) and MAA (Marketing Authorization Application), respectively. The following figure illustrates the relationship between the various submission-related objects. An application is typically made to one health authority in one country, in accordance with a National Procedure (NP). The exception is for applications to European member states, which can follow either a National Procedure for specific member states (a separate application being made to each member state in that case), or a Centralized Procedure (CP), in which case the application is made directly to the European Medicines Agency (EMA), the central European regulatory authority. If the application is approved by the EMA, it is approved for use across all EU member states. For certain types of applications, such as Biological Licence Applications (BLAs), approval by the EMA through the CP is mandatory; for others, it is discretional. There is also an option to use the Mutual Recognition Procedure (MRP) in the EU, which enables the same application to be made to two or more member states simultaneously. Once one member state decides to evaluate the product, it becomes the Reference Member State. The others become Concerned Member States, acting in a reviewing or monitoring capacity. In this way, the MRP is designed to share the workload in evaluating medicinal products across national regulatory authorities within the EU, without 206 Regulatory Submissions compromising safety or regulatory scrutiny. To support MRP applications, it must be possible for an application to be associated with multiple health authorities within the EU region. Electronic Common Technical Document Submission An application can adopt the electronic Common Technical Document (eCTD) format, as defined by the International Committee on Harmonization (ICH). In an eCTD submission, each submission represents a sequence of the eCTD, enumerated from sequence number 0000 for the initial filing. An XML backbone file (index.xml) is included within the top-level sequence folder, referencing the documents included in that sequence. The documents in a sequence are organized into the prescribed ICH eCTD module structure: • Module 1 (Regional) • Module 2 (Summaries) • Module 3 (Quality) • Module 4 (Non-Clinical) • Module 5 (Clinical) The structure of the regional module m1 is not defined by the ICH, but is defined by the regulatory authorities in each region. It has its own regional XML file in the appropriate format (for example, us-regional.xml for US, eu-regional.xml for Europe) referring to the regional-specific documents included in module m1 of the sequence. Document-specific metadata may be included in the XML backbone and regional XML files, such as the drug substance and manufacturer to which a particular document pertains, as and where applicable; and submission-specific metadata may also be included in the regional XML file, such as the product trade names intended to be used in each country. The initial submission for an eCTD comprises only new documents. Each subsequent submission (numbered 0001, 0002, and so on) contains only incremental changes that is, additional (new) documents, replacements, and supplements to previously-submitted documents, and previously-submitted documents to be considered as withdrawn. Each sequence includes a new version of the XML backbone file, specifying the alterations to be made for each leaf document in terms of operations (new, replace, append or delete), as appropriate. Regional XML Files for Other Agencies Additional regional XML files may be included in the standard installation, or downloaded from the relevant agency websites and manually-imported into the repository post-installation, to support other regions. 207 Regulatory Submissions Additional XSL Style Sheets The XSL style sheets provided by the ICH and regional agencies are installed on the application server as part of the Documentum SSV installation. However, they are not required for XML processing and import purposes. Submission History XML File The submission history view (model) is compiled and maintained automatically by the system as each submission or sequence is imported into the repository. The Submission History XML file in Documentum SSV represents the submission history of a particular application, that is, the series of submissions that were imported in chronological order. The format of this XML file is based on the ICH eCTD XML backbone format. Documentum SSV compile and maintains the Submission History XML. The Submission History XML file is stored as an XML document and is the main content of the Regulatory Application Registration Forms (RARF). Users can view and navigate the XML file through an XML Preview widget, which renders the file into HTML. The HTML document provides cumulative, sequence, and current views of the eCTD submission with links to the m1 regional XML file and hyperlinks to the PDF documents in the submission folders. Supporting New eCTD XML Formats Documentum SSV supports the following eCTD XML formats by default: eCTD Modules Region/Health Authority DTD/Schema Versions Predefined XMl Schema Configuration Names M1 Europe (EMA and all EU Member State Health Authorities) 1.2.1, 1.3, 1.4 and 2.0 eCTD EU Regional XML file v x.y US (FDA) 2.01 eCTD US-FDA Regional XML file v 2.01 Canada (Canada Heath) 2.2 eCTD Canada Regional XML file v 2.2 Japan (Ministry of Health, Labour and Welfare (MHLW)) 1.0 eCTD Japan Regional XML file v 1.0 208 Regulatory Submissions eCTD Modules Region/Health Authority DTD/Schema Versions Predefined XMl Schema Configuration Names M2-M5 Global (ICH)* 3.2 eCTD ICH XML Backbone File v 3.2 M4-M5 Study tagging files (STFs) US (FDA) 2.2 ICH Study Tagging File v 2.2 *The (ICH is not a health authority, but an international industry body responsible for defining and maintaining standard models such as the format used for eCTD module M2-M5 XML backbone files. Documentum SSV uses the XML schema configuration objects in the repository to represent these eCTD module formats. The predefined XML schema configuration objects are created automatically in the repository as objects of type cd_ectd_xml_schema, which are stored in the /System/SSV/XML Schemas folder. These objects are used by Documentum SSV to identify and handle XML files that are encountered in eCTD sequences during the submission import process. To support additional eCTD XML formats, such as M1 regional XML formats for other regions or different eCTD versions for existing regions, it is possible to extend the standard configuration as follows: 1. Using Documentum Administrator, copy and rename an existing cd_ectd_xml_schema configuration object in the /System/SSV/XML Schemas folder that is similar to the format required. For example, for US FDA v 2.3 regional M1 XML files, use the existing eCTD US-FDA Regional XML file v 2.01 configuration as a starting point. It is also possible to create a new cd_ectd_xml_schema configuration object through DQL although it is generally easier to copy and adjust the existing objects. It is recommended that the existing naming conventions are followed, including the format version number suffix, so that the applicability of each configuration object can be easily identified. 2. Adjust the properties of the configuration object. See XML Schema Configuration Object Settings, page 210 for more information. 3. Create an XSL transformation script, if required, to convert the XML into a standard format and store it in the main content file of the XML schema configuration object as an xsl content file. Then, enable the XSLT processing option for this schema. This is only required for handling XML files that use a format or element naming convention that is dissimilar to the standard ICH format, such as Japanese regional M1 files. See Processing Standard XML Files, page 216 and Transforming Non-Standard XML Files, page 218 for more information. 4. On the application server, set up an XSL script to extract the regional M1 XML metadata for previewing in Documentum SSV. The easiest way to do this is to copy and edit one of the predefined XSL scripts (see Previewing and Processing eCTD Module 1 Regional XML Files, page 221). Link this script to the XML schema configuration object by adjusting the xml_envelope_stylesheet property accordingly. 5. Import a sample submission to test the new configuration and ensure that it can be navigated and previewed correctly. 209 Regulatory Submissions XML Schema Configuration Object Settings The attributes of the cd_ectd_xml_schema objects must be configured in Documentum as follows: Attribute Data type Description Example Values for eu-regional.xml Version 2.0 Schema object_name Char(255) An arbitrary unique identifier for this XML schema configuration object in the repository. eu-regional.xml v 2.0 title Char(400) An optional description of the XML format that this schema object represents. eCTD EU Regional XML file v 2.0 origin_url Char(255) An optional URL referring to the website of the organization or Health Authority that owns the specification of this XML format. http://esubmission .ema.europa.eu /eumodule1/index.htm xpath_qualifier Char(255) An XPath expression identifying the root element in an XML file that conforms to this format. This is used by SSV to identify and select the appropriate XML schema configuration object to use for each XML file discovered in the eCTD sequence. /eu-backbone[@dtd -version=’2.0’] schema_category Char(32) Indicates the type of this XML file, as follows: eCTD Regional XML File • eCTD Regional XML File • eCTD ICH XML Backbone File • eCTD ICH Study Tagging File 210 Regulatory Submissions Attribute Data type Description Example Values for eu-regional.xml Version 2.0 Schema xml_format_code Char(32) An abbreviated display label denoting this XML format, used in the SSV Viewer to show the eCTD module formats or versions used in a particular submission. EU-2.0 enable_xslt_processing Boolean Indicates whether this XML file needs to be pre-processed through an XSLT transformation script when loaded, in order to convert it into a form that can be processed more easily. The XSLT script itself should be stored as a main content file or rendition of the XML schema configuration object, using the Documentum format code “xsl”. See Transforming Non-Standard XML Files, page 218. F contains_leaf_docs Boolean Indicates whether or not this XML file contains references to “leaf elements,” that is, documents to be imported into the repository. T 211 Regulatory Submissions Attribute Data type Description Example Values for eu-regional.xml Version 2.0 Schema xml_extract_leaf_docs Boolean Indicates whether or not leaf elements should be extracted from this XML file and incorporated into the main Submission History View. This setting should be enabled for Regional M1 files and study tagging files, and disabled for ICH backbone files. T xml_extract_leaf_docs _from Char(128) Specifies the XPath of the top-level XML nodes that contain leaf documents. Required if contains_leaf_docs is enabled. The wildcard value “*” indicates that all elements should be included. /eu-backbone/m1-eu xml_leaf_doc_element Char(32) Specifies the name of the XML elements representing leaf documents (after XSLT pre-processing, where necessary). Required if contains_leaf_docs is enabled and xml_extract_leaf_docs _from is not “*”. leaf xml_leaf_doc_attrs Char(128) Repeating Specifies the document-level XML attributes to be extracted from leaf document elements into the submission history view or Documentum attributes, using the notation <target-Documentum -attribute-name> =<XPath-expression (none) 212 Regulatory Submissions Attribute Data type Description Example Values for eu-regional.xml Version 2.0 Schema -for-XML-leaf -element>. Applies to eCTD ICH XML Backbone Files only (not regional M1 XML files). See XML Metadata Extraction, page 224. is_required_leaf_doc _attr Boolean Repeating For each value in the above, indicates whether a defined, non-blank attribute value is required for each leaf element (T), or whether it is optional (F). This is not currently used. (none) override_leaf_attrs_on _rarf Boolean Repeating For each of the above, specifies whether the value extracted from the XML file can be used as a default attribute value for the Regulatory Application Registration Form. This is not currently used. (none) contains_envelope Boolean Indicates whether or not this XML file contains submission-level metadata. T xml_envelope _element Char(32) Specifies the name of the top-level XML elements that contain metadata to be extracted from regional XML files. Required if the contains_envelope flag is enabled. envelope 213 Regulatory Submissions Attribute Data type Description Example Values for eu-regional.xml Version 2.0 Schema xml_envelope _stylesheet Char(32) The file name of the XSL stylesheet to use to render the regional XML metadata as HTML in the SSV document preview screen. The specified XSL stylesheet must be installed in the %WEBAPPS% /XMLViewer/style folder on the D2 application server. See Previewing and Processing eCTD Module 1 Regional XML Files, page 221. eu-regional.xsl xml_envelope_attrs Char(128) Repeating Specifies the XML attributes to be extracted from the envelope elements into the submission history view or Documentum attributes, as and where appropriate, using the notation <target-attribute> =<XPath-expression>, where <XPath -expression> is evaluated in relation to the envelope element in each case. health_authority = agency-name; country_code = @country; application_number = application/number;… is_required_envelope _attr Boolean Repeating For each value in the above, indicates whether a defined, non-blank attribute value is required for each leaf element (T), or whether it is optional (F). This is not currently used. T;T;T;… override_env_attrs_on _rarf Boolean Repeating For each of the above, specifies whether the value extracted T;T;T;… 214 Regulatory Submissions Attribute Data type Description Example Values for eu-regional.xml Version 2.0 Schema from the XML file can be used as a default attribute value for the Regulatory Application Registration Form. This is not currently used. The system can support multiple versions of the same XML format. A separate XML schema configuration object must be defined for each format or version. The xpath_qualifier setting is used to identify and select the appropriate XML schema configuration object for each XML file encountered during the eCTD import process, depending on whether the specified XPath expression matches an element in that XML file. The xpath_qualifier should include a qualifier in each case so that it only matches XML files of the appropriate format and version, for example, the XPath expression /eu-backbone[@dtd-version=’1.2.1’] only matches XML files containing a root element named “eu-backbone” (ignoring the ”eu:” XML namespace prefix) where the “dtd-version” attribute value of the root element is set to “1.2.1”. In other words, this schema only applies to XML files that use version 1.2.1 of the EU regional M1 XML format, such as the following: <?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE eu:eu-backbone SYSTEM "../../util/dtd/eu-regional.dtd"> <?xml-stylesheet type="text/xsl" href="../../util/style/eu-regional.xsl"?> <eu:eu-backbone xmlns:eu="http://europa.eu.int" xmlns:xlink="http://www.w3c.org/1999/xlink" dtd-version="1.2.1"> <eu-envelope> <envelope country="uk"> <application> <number>N123456</number> </application> <applicant>Acme Pharma Inc.</applicant> <agency-name>MHRA</agency-name> <atc>C10AB05</atc> <submission type="initial-maa" /> <procedure type="national" /> <invented-name>My Wonder Drug</invented-name> <inn>wonderdrug</inn> <sequence>0000</sequence> <submission-description>Submission of registration dossier</submission-description> </envelope> </eu-envelope> <m1-eu> <m1-0-cover> <specific country="uk"> <leaf operation="new" xlink:href="10-cover/uk/en-cover-wonder-drug-50mg.pdf" xlink:type="simple" checksum-type="md5" application-version="PDF 1.4" checksum="b132fc1e9e0c5c9f5401a4288f20f60f"> <title>Cover Page (English)</title> </leaf> </specific> </m1-0-cover> …etc. </m1-eu> <eu:eu-backbone> 215 Regulatory Submissions In this way, different XML formats or versions can be matched to different XML schema configuration objects with different settings. The file system filename of the XML file itself is not significant (an EU M1 regional XML file does not need to be named eu-regonal.xml, for instance); neither is the location of the XML file within the folder structure – the XML file recognition depends only on the contents of the XML file. If none of the XML schema configuration objects defined in the repository return a match for a particular XML file, the system logs a warning indicating that the XML file is not recognized, and treats it as standard leaf document. It is not possible to extract metadata from unrecognized XML files. It is also not possible to preview them in the Documentum SSV Document Viewer. Processing Standard XML Files If the eCTD XML file conforms to a standard format, it is possible for Documentum SSV to process it directly by setting up XML schema configuration objects in the repository, as described in the Supporting New eCTD XML Formats, page 208 section. To conform to the standard format: 1. The XML file should encapsulate all regional metadata (if any) directly or indirectly in one XML node, known as the envelope node, and all leaf documents in a separate document node. For example, in US regional M1 files, the regional metadata is defined in the envelope node /fda-regional/admin, and the leaf documents in the document node /fda-regional/m1-regional. Similarly, in EU regional M1 files, the envelope node is /eu-backbone/eu-envelope, and the documents node is /eu-backbone/m1-eu. ICH eCTD M2-M5 XML files do not have an envelope node because the regional metadata is stored in a separate M1 XML file. The document node for these is the root element, /ectd. 2. Each leaf document in the document node must be represented as a <leaf> element with the following attributes defined for it, as appropriate: • operation: Denotes incremental modifications to previously-submitted documents, as and where necessary. Expected values are “new” for new documents; “replace” for new versions of previously-submitted documents; “append” for extensions (supplements) to previously-submitted documents; or “delete” for previously-submitted documents to be regarded as withdrawn. In the initial sequence 0000, only “new” documents are permitted. (Required) • xlink:href: Specifies the document content file in terms of a relative file system path from the sequence-level folder. (Required except where operation = “delete”) • xlink:type: Specifies the type of the xlink:href value, which is expected to be “simple”, where defined. (Optional) • checksum: Specifies a checksum for the content file, which can be used to verify that the content file has not been modified since the XML file was generated. (Optional) • checksum-type: Specifies the algorithm used to generate the checksum; usually “md5” (where defined). This is not currently used by DocumentumSSV. (Optional) • application-version: Denotes the application name and version number associated with the content file, that is, the content file format. For example, “PDF-1.4”. (Optional) • modified-file: Denotes the previously-submitted file affected by the operation (if any) as a relative file path from the top-level folder containing the sequence folders; the first path 216 Regulatory Submissions element being the previous sequence number. (Required where operation code is “replace”, “append” or “delete”; not applicable where it is “new”) Each <leaf> element should also have a <title> sub-element, in which the document title is specified. In practice, it is possible to use a different XML element name for leaf documents, provided the element has attributes and a <title> sub-element defined as above – the actual leaf document element name is configured in the XML schema configuration object. 3. Non-leaf nodes in the document section are used to represent standard eCTD modules, sections, and subsections, nested to an arbitrary depth. These usually represent the file system folder structure of the eCTD sequence. Non-leaf nodes can have the following additional attribute values defined for them, indicating sections pertaining to specific contexts: • substance—Name of drug substance • product-name—Name of drug product • manufacturer—Manufacturer of drug substance or product • indication—Specific therapeutic indication • dosageform—Specific dosage form • excipient—Name of excipient (inactive ingredient) These attributes are defined in the relevant ICH DTD. In practice, Documentum SSV enables arbitrary metadata to be specified for non-leaf nodes. 4. <node-extension> elements may also be used to represent custom extensions to the standard eCTD folder structure. Each <node-extension> element has a <title> sub-element defining the section title (display label), and one or more <leaf> document elements or <node-extension> sub-elements recursively. 5. In M1 regional modules, <specific> elements can be used to denote country-specific sections, where the country attribute value denotes the ISO country code in each case. For example, <specific country="de"> represents a section that is applicable to Germany only. In practice, these elements only appear in EU regional M1 XML files. The country code value eu or the aliases ema, emea, or common can be used to denote elements pertaining to the central European Medical Authority (EMA) or to the EU region in general. 6. In M1 regional modules, <pi-doc> elements can be used to denote package information documents, such as labeling documents. This may be country-specific (with a country code defined as above). These elements may also specify a type attribute value indicating the type of labeling document in each case, although Documentum SSV does not use this. These elements only appear in EU regional M1 XML files. All the XML files supported in the out-of-the-box configuration conform to this standard format except for the Japanese regional M1 XML files. Note: Whenever a large amount of processing is involved during the import of an eCTD submission that has multiple submission folders, it is better to allocate more resources to the Java Method Server. For example, memory should be preferably 1024 MB or greater. 217 Regulatory Submissions Transforming Non-Standard XML Files For Documentum SSV to process non-standard-format XML files, it is necessary to provide a transformation script written in extensible stylesheet language (XSL) to enable Documentum SSV to convert them into the standard format so that they can be processed. For example, Japanese regional M1 XML files use a non-standard format as shown below: <?xml version="1.0" encoding="UTF-8"?> <?xml-stylesheet type="text/xsl" href="../../util/style/jp-regional-1-0.xsl"?> <universal xmlns="universal" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="universal ../../util/dtd/jp-regional-1-0.xsd" lang="ja" schema-version="1.0"> <document-identifier> <title>Japanese title</title> <doc-id>Document identifier</doc-id> </document-identifier> <document> <content-block param="admin"> …Japanese envelope metadata </content-block> <content-block param="m1"> <block-title>Japanese section label </block-title> <content-block param="m1-03"> <block-title> Japanese sub-section label </block-title> <doc-content xlink:href="relative content file path"> <title>1.3.5. Japanese document title</title> <property name="operation" info-type="jp-regional-m1-toc">new</property> <property name="checksum" info-type="jp-regional-m1-toc"> content file checksum </property> <property name="checksum-type" info-type="jp-regional-m1-toc">md5</property> </doc-content> …etc. </content-block> </content-block> </document> </universal> To convert Japanese regional M1 XML files into the standard format, the following XSL transformation script is used: <?xml version=”1.0" encoding="UTF-8" standalone="no"?> <xsl:transform version="1.0" xmlns:xsl = "http://www.w3.org/1999/XSL/Transform"xmlns:ectd = "http://www.ich.org/ectd" xmlns:xlink = "http://www.w3.org/1999/xlink"xmlns:gen = "universal"> <xsl:output method="xml" version="1.0" encoding="UTF-8" indent="yes"/> <xsl:template match="/"> <xsl:element name="jp-backbone"> <xsl:attribute name="dtd-version"><xsl:value-of select="/gen:universal/@schema-version"/> </xsl:attribute> <xsl:apply-templates select="*"/> </xsl:element> </xsl:template> <!--Japanese M1 root XML element--> <xsl:template match="gen:universal"> <!--Generate "admin" section containing document title, ID and Japanese MHLW envelope information--> <xsl:element name="admin"> <xsl:element name="title"> <xsl:value-of select="gen:document-identifier/gen:title"/> </xsl:element> <xsl:element name="document-id"> <xsl:value-of select="gen:document-identifier/gen:doc-id"/> 218 Regulatory Submissions </xsl:element> <xsl:element name="properties"> <xsl:attribute name="label"><xsl:value-of select="/gen:universal/gen:document/gen: content-block[@param = 'admin']/gen:block-title"/></xsl:attribute> <xsl:for-each select="/gen:universal/gen:document/gen:content-block[@param = 'admin']/*"> <xsl:choose> <xsl:when test="name() = 'doc-content'"> <xsl:element name="property"> <xsl:attribute name="item-number"><xsl:value-of select="@param"/></xsl:attribute> <xsl:attribute name="name"><xsl:value-of select="./gen:property/@name"/></xsl:attribute> <xsl:attribute name="label"><xsl:value-of select="./gen:title"/></xsl:attribute> <xsl:attribute name="value"><xsl:value-of select="./gen:property"/></xsl:attribute> </xsl:element> </xsl:when> <xsl:when test="name() = 'content-block'"> <xsl:element name="property"> <xsl:attribute name="item-number"><xsl:value-of select="@param"/></xsl:attribute> <xsl:attribute name="name"><xsl:value-of select="./gen:doc-content/gen:property/@name"/> </xsl:attribute> <xsl:attribute name="label"><xsl:value-of select="./gen:block-title"/></xsl:attribute> <xsl:attribute name="value"><xsl:value-of select="./gen:doc-content/gen:property"/> </xsl:attribute> </xsl:element> </xsl:when> </xsl:choose> </xsl:for-each> </xsl:element> </xsl:element> <!--Generate "m1-jp" section containing M1 modules and leaf documents--> <xsl:element name="m1-jp"> <xsl:attribute name="label"><xsl:value-of select="/gen:universal/gen:document/gen: content-block[@param = 'm1']/gen:block-title"/></xsl:attribute> <xsl:apply-templates select="/gen:universal/gen:document/gen: content-block[@param = 'm1']/gen:content-block"/> </xsl:element> </xsl:template> <!--M1 module / sub-module--> <xsl:template match="gen:content-block"> <xsl:element name="{@param}"> <xsl:attribute name="label"><xsl:value-of select="./gen:block-title"/></xsl:attribute> <xsl:apply-templates/> </xsl:element> </xsl:template> <!--M1 leaf document--> <xsl:template match="gen:doc-content"> <xsl:element name="leaf"> <xsl:attribute name="operation"><xsl:value-of select="./gen:property[@name = 'operation']"/> </xsl:attribute> <xsl:attribute name="checksum-type"><xsl:value-of select="./gen:property[@name = 'checksum-type'] "/></xsl:attribute> <xsl:attribute name="checksum"><xsl:value-of select="./gen:property[@name = 'checksum']"/> </xsl:attribute> <xsl:attribute name="xlink:href"><xsl:value-of select="@xlink:href"/></xsl:attribute> <xsl:if test="string-length(./gen:property[@name = 'modified']) > 0"> <xsl:attribute name="modified-file"><xsl:value-of select="./gen:property[@name = 'modified'] "/> </xsl:attribute> </xsl:if> <xsl:element name="title"> <xsl:value-of select="./gen:title"/> </xsl:element> 219 Regulatory Submissions </xsl:element> </xsl:template> <xsl:template match="*"/> </xsl:transform> This script is included in the standard installation, and is stored in the repository as the main content file of the XML eCTD schema configuration object for Japanese regional M1 files. The XSL file is then downloaded and applied automatically to Japanese M1 XML files at import time as they are loaded, prior to processing them. A copy of this XSL transformation script can also be found on the Application Server in the file %WEBAPPS%/XMLViewer/style/jp-regional-1-0-normalize.xslt for reference, although it is not used by the Viewer. The output from the XSL transformation script is another XML file, of the following form: <jp-backbone dtd-version=”Japanese schema version”> <admin> <title>Japanese title</title> <document-id>document identifier</document-id> <properties label="Japanese section label"> <property item-number="nn" name="property-code" label="Japanese property label" value="Property value"/> ... </properties> </admin> <m1-jp label="Japanese section label "> <m1-01 label="Japanese sub- section label "> <m1-01-03> <leaf operation="new " checksum-type="md5" checksum="content file checksum" xlink:href="relative content file path" <title>Japanese document title</title> </leaf> ... </m1-01-01> </m1-01> ... </m1-jp> </jp-backbone> This now conforms to the standard XML format required by Documentum SSV. The XML schema configuration settings are configured accordingly for this XML file to enable it to be processed as normal. For example, the xml_envelope_element XPath setting is set to /jp-backbone/admin in the eCTD schema configuration object for Japanese M1 files; similarly, xml_extract_leaf_docs_from is set to /jp-backbone/m1-jp, and so on. It is possible to use a similar technique to support new eCTD formats that do not conform to the standard XML format, as follows: 1. Create an XSL transformation script to convert the eCTD format into a standard format, just as in the example above. 2. Test the XSL transformation script by linking a sample eCTD XML file to it, for example, add an XML preprocessing instruction of the form <?xml-stylesheet type="text/xsl" href="filename.xsl"?> to the XML header in the sample file, and opening it in the browser. 3. After verifying that the XSL transformation script is generating XML output appropriately in the standard format, create a new XML configuration object in the repository representing the new eCTD format, and configure the settings as described previously. Ensure that the enable_xslt_processing option is enabled and import the XSL transformation script as the 220 Regulatory Submissions main content file of the XML configuration object in the repository, using the Documentum format code xsl. 4. Test the installation by importing a sample eCTD that contains the XML files that use the new format. You can also add XSL scripts to the existing XML schema configuration objects to transform the metadata in XML files as and where necessary, for example, to convert values to lower-case, translate country names into corresponding country code values, truncate values that are too long, and so . However, in the default installation, XSL transformation is only used for converting Japanese regional M1 XML files and study tagging files. XSL scripts can also be used on the application server to generate XML preview renditions. Previewing and Processing eCTD Module 1 Regional XML Files XML preview renditions (of format xml_preview) are generated and stored for each module M1 XML file at import time, alongside the original XML file. This enables the metadata contained in these XML files to be previewed in the Submission Document Preview panel in the same way as for PDF documents. At the same time, any leaf documents referenced in the regional XML file are extracted and incorporated into the main submission history view, so that these files can be navigated and previewed alongside the main eCTD module 2-5 files. To enable this, the following settings must be configured in the relevant eCTD schema configuration object: contains_envelope Set to T (enabled). xml_envelope_element Specifies the elements to be included in the XML preview rendition, after having transformed the XML file into the standard format, where necessary. This is also used for XML metadata extraction purposes. xml_envelope_stylesheet Specifies the name of the stylesheet used to render the XML file into HTML in the Submission Document Viewer. Predefined stylesheets are provided for each of the supported regions (USA, Europe, Canada and Japan.) Custom stylesheets can be created to support other regions. 221 Regulatory Submissions contains_leaf_docs Set to T (enabled) if the XML file contains <leaf> elements as well as metadata, or F (disabled) otherwise. xml_extract_leaf_docs_from Specifies the top-level document element containing <leaf> elements (indirectly), after having transformed the XML file into the standard format, where necessary. The specified element, together with all of its subordinates, is removed from the XML preview rendition, so that the XML preview rendition contains only envelope metadata. This is because the leaf document nodes themselves cannot be navigated from the Submission Document Viewer pane used for previewing. Instead, these elements are incorporated directly into the Submission History XML, so they can be navigated through the Submission Navigator view. In this way, the Submission Navigator provides a consolidated view across all of the M1-M5 eCTD modules, even though the M1 module is actually defined as a separate XML file. For example, the following settings are preconfigured in the schema configuration object named “us-regional_2-01”, which can be found in the /SSV/XML Schemas folder, and is used to generate previews of “us-regional.xml” files: XML Schema Configuration Settings: us-regional_2-01 Configuration Setting Value contains_envelope T xml_envelope_element admin xml_envelope_stylesheet us-regional.xsl contains_leaf_docs T xml_extract_leaf_docs_from /fda-regional/m1-regional This tells the system to extract the XML metadata from the admin element of us-regional.xml files below the root element, fda-regional, to generate the xml_preview rendition, and extract the leaf document elements from the m1-regional element below the root element into the main submission view. If the user clicks the us-regional.xml element in module 1 in the Submission Viewer, the xml_preview rendition is rendered into HTML by the relevant stylesheet (in this case, the “us-regional.xsl” stylesheet is used) and displayed in the document preview panel. Note: The xml_preview rendition is generated and stored in the repository automatically at import time. It is attached to the regional XML file as a rendition. This is used only for previewing the XML metadata in SSV. The primary content of the regional XML file is not affected, and preserves a record of the XML file that was included in the submission. If the imported submission folder is exported 222 Regulatory Submissions back out to the local filesystem, only the original primary content files are exported, and not the SSV renditions, so that an exact copy of the submitted files is exported. If a new region or eCTD version for an existing region is to be supported, a new XSL stylesheet for it must be provided to enable the XML preview to be generated. These stylesheets must be installed in the %WEBAPPS%/XMLViewer/style folder on the application server, with the predefined stylesheets. In some cases, the XSL stylesheets provided by the relevant Authority itself can be used directly, or adapted as necessary. For example, standard eu-regional.xsl stylesheet provided with Documentum SSV is based on the stylesheet provided by the EMA. However, in other cases, a custom stylesheet will need to be developed, where the Agency does not provide one (such as Canada), or where it is unsuitable for direct use, for example, it contains JavaScript or XSL functions that refer to M1 leaf elements, which are not included in the XML preview (such as the US FDA stylesheet). In these cases, you can use one of the standard stylesheets that are pre-installed with Documentum SSV as a guideline for developing new stylesheets. The following is a transcript of the us-regional.xsl script that is provided for this purpose: ?xml version="1.0" encoding="UTF-8"?> <!--U.S. Regional Stylesheet (us-regional.xsl) for previewing XML metadata in SSV--> <xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns:fda-regional="http://www.ich.org/fda"> <xsl:template match="/"> <html> <head> <meta http-equiv="content-type" content="text/html; charset=UTF-8"/> </head> <body> <h3> <img src="icons/countryflags/us.gif" style="padding-right: 10px;"/> US Food and Drugs Administration - Regulatory Information </h3> <table border="0" cellspacing="20px"> <tr><td>Applicant:</td><td><xsl:value-of select="/fda-regional:fda-regional/admin/ applicant-info/company-name"/></td></tr> <tr><td>Product Name:</td><td><xsl:value-of select="/fda-regional:fda-regional/admin/ product-description/prod-name"/></td></tr> <tr><td>Application Number:</td><td><xsl:value-of select="/fda-regional:fda-regional/admin/ product-description/application-number"/></td></tr> <tr><td>Application Type:</td><td><xsl:value-of select="/fda-regional:fda-regional/admin/ application-information/@application-type"/></td></tr> <tr><td>Submission Type:</td><td><xsl:value-of select="/fda-regional:fda-regional/admin/ application-information/submission/@submission-type"/></td></tr> <tr><td>Date of Submission (<xsl:value-of select="/fda-regional:fda-regional/admin/ applicant-info/date-of-submission/date/@format"/>):</td><td> <xsl:value-of select="/fda-regional:fda-regional/admin/ applicant-info/date-of-submission/date"/></td></tr> <tr><td>Sequence Number:</td><td><xsl:value-of select="/fda-regional:fda-regional/admin/ application-information/submission/sequence-number"/></td></tr> </table> </body> </html> </xsl:template> </xsl:stylesheet> Note that this stylesheet is only used for previewing the XML metadata in SSV: the standard agency-supplied regional stylesheets can still be included in the eCTD submission itself (in the utils folder) and used for navigating the submission when it has been exported to the local file system. 223 Regulatory Submissions XML Metadata Extraction Submission-level metadata can be extracted from eCTD regional M1 XML files into Documentum, in order to facilitate browsing and searching for submissions and regulatory applications. This metadata is extracted from the envelope section of the XML file and stored in the corresponding Documentum attributes of the top-level cd_submission_folder object representing the sequence folder in the repository, the cd_reg_submission_info object representing the Submission Registration form, and the cd_reg_admin_info object representing the Regulatory Application Registration Form for the application. The following attributes are defined in the default installation for each of these object types, for XML metadata extraction purposes: Documentum Attribute Data Type Description country_code Char(2) The ISO country code for the country to which the application is being submitted, for example, “ca” for Canada. For European submissions, the country code “eu” should be used for Centralized Procedure (CP) submissions to the EMA, or otherwise the country code for the relevant target EU Member State or Reference Member State for National Procedure (NP) or Mutual Recognition Procedure (MRP) should be used, for example, “sv” for Sweden. By convention, this is assumed to be the country code of the first “envelope” element in the EU Regional XML file concerned_member_states Char(2) REPEATING ISO country codes for other EU Member States acting as reviewers of European submissions using the MRP. By convention, this is assumed to be the country codes for all except the first “envelope” element in the EU Regional XML file. Applies only to MRP submissions to the EU. dosage_form Char(128) REPEATING The forms in which a drug product is provided for a defined administration route. 224 Regulatory Submissions Documentum Attribute Data Type Description dosage_strength Char(32) REPEATING For each dosage form, specifies the amount of active ingredient in terms of a defined unit of measure. For example, the amount of active ingredient contained in one dose as specified in the label. drug_product_manufacturer Char(128) REPEATING The business entity/entities engaged in making, assembling, processing or modifying a finished drug product; or packaging, repackaging or otherwise changing the container or wrapper for a drug product. drug_product_name Char(64) REPEATING For each drug product manufacturer, the name of the manufactured drug product in each case. drug_substance_manufacturer Char(128) REPEATING The business entity/entities engaged in making, assembling, processing or modifying the pharmaceutical ingredients used in a drug product. drug_substance_name Char(64) REPEATING For each drug substance manufacturer, the name of the manufactured drug substance in each case. excipients Char(128) REPEATING A list of excipients (inactive ingredients) used in the manufacture of a drug product. indication Char(128) REPEATING The indications (diseases) that a particular drug product is designed to treat. product_generic_name Char(128) REPEATING The unique non-proprietary or common name for a drug defined by establishing logical nomenclature classifications based on pharmacological or chemical relationships and approved by USAN or INN. 225 Regulatory Submissions Documentum Attribute Data Type Description product_trade_name Char(128) REPEATING The proprietary name (brand name) of a drug product designated for regulatory approval/marketing. submission_type Char(48) The type of individual submission within the application, as defined by the relevant Agency. Some of these attributes, such as region, health_authority, submission_number, submission_type, and submission_date, may be specified in the Import Submission dialog box at import time, or they may be overridden with metadata extracted from the XML file, where defined. To enable XML extraction for these attributes: 1. Ensure that the relevant attributes are defined for the cd_submission_folder and cd_reg_admin_info object types in Documentum; add them to both object types if necessary. 2. In the relevant XML schema configuration object for the regional M1 XML file: a. Enable the contains_envelope setting. b. Set xml_envelope_element to the name of the “envelope” elements containing the regional metadata in the XML file. In most cases there will be only one such element; however, EU regional XML files for submissions using the MRP contain multiple “envelope” elements – one for each EU Member State to which the submission is sent. (In that case, the first “envelope” element is assumed to pertain to the Reference Member State, and the remainder to Concerned Member States.) c. Specify the attributes to be extracted in the xml_envelope_attrs repeating attributes of the XML schema configuration object, using values of the form “<Documentum-attribute-name>=<XML-XPath-expression>”. d. For each of the above, set the corresponding flags in the is_required_ envelope_attr and override_env_attrs_on_rarf repeating attributes to T (true) or F (false), accordingly. If an attribute is marked as “required” in the XML envelope but is missing from the XML file or has a blank value specified for it in the XML file, this is logged as a warning. If the “override on RARF” setting is enabled, the extracted attribute is copied to the relevant Regulatory Application Registration Form as well as the submission folder, even if it is already defined at that level. If this flag is disabled, the extracted attribute is only copied to the Regulatory Application Registration Form if the form itself does not already have a defined value, that is, it is used as a default value for the Regulatory Application Registration Form in that case. Example 1: US Submission to the FDA The following code shows part of a sample us-regional.xml file included in module M1 of an eCTD submission to the US FDA: <?xml version="1.0" encoding="utf-8"?> <!DOCTYPE fda-regional:fda-regional SYSTEM "..\..\util\dtd\us-regional-v2-01.dtd"> <?xml-stylesheet type="text/xsl" href="..\..\util\style\us-regional.xsl"?> <fda-regional:fda-regional xmlns:fda-regional="http://www.ich.org/fda" xmlns: 226 Regulatory Submissions xlink="http://www.w3c.org/1999/xlink" dtd-version="2.01" xml:lang="en"> <admin> <applicant-info> <company-name>Acme Pharmaceuticals Inc.</company-name> <date-of-submission> <date format="yyyymmdd">20141205</date> </date-of-submission> </applicant-info> <product-description> <application-number>123456</application-number> <prod-name type="proprietary">Wonder Drug</prod-name> </product-description> <application-information application-type="ind"> <submission submission-type="original-application"> <sequence-number>0000</sequence-number> </submission> </application-information> </admin> <m1-regional> …etc. </m1-regional> </fda-regional:fda-regional> The standard XML schema configuration object for the above is called “us-regional_2-01”, and it has the following predefined settings: XML Schema Configuration Setting Name XML Schema Configuration Setting Values Documentum Attribute Value Extracted from Example XML File (if any) xml_envelope_element admin — xml_envelope_attrs country_code=’us’ us health_authority=’FDA’ FDA submission_date=./applicant -info/date-of-submission/date 20141205 submission_date_format =./applicant-info/date-of -submission/date/@format yyyymmdd application_num=./product -description/application -number 123456 application_type=./application -information/@application-type ind submission_number=. /application-information /submission/sequence-number 0000 submission_type=./application -information/submission/ @submission-type original-application product_trade_name=./product -description/prod-name[@type =’proprietary’] Wonder Drug 227 Regulatory Submissions XML Schema Configuration Setting Name XML Schema Configuration Setting Values Documentum Attribute Value Extracted from Example XML File (if any) product_generic_name=. /product-description/prod -name[@type=’established’] — In the above, XPath expressions are used to extract the relevant metadata from the admin node of the XML file. For more information on using XPath expressions, refer to: http://www.w3schools.com/XPath/. Example 2: EU Submission to Multiple EU Countries This next example is for an eu-regional.xml file included in a submission to three EU Member States (Sweden, Germany, and France) using the MRP. It has three envelope sections, one for each country: <?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE eu:eu-backbone SYSTEM "../../util/dtd/eu-regional.dtd"> <?xml-stylesheet type="text/xsl" href="../../util/style/eu-regional.xsl"?> <eu:eu-backbone xmlns:eu="http://europa.eu.int" xmlns:xlink="http://www.w3c.org/1999/xlink" dtd-version="1.2.1"> <eu-envelope> <envelope country="sv"> <application> <number>pending</number> </application> <applicant>ACME Pharmaceuticals Inc.</applicant> <agency-name>SV-MPA</agency-name> <atc>C10AB05</atc> <submission type="initial-maa" /> <procedure type="mrp" /> <invented-name>Wonder Drug</invented-name> <inn>cureimol monosulphate</inn> <sequence>0000</sequence> <submission-description>Submission of registration dossier</submission-description> </envelope> <envelope country="de"> <application> <number>pending</number> </application> <applicant>ACME Pharmaceuticals Inc.</applicant> <agency-name>DE-BfArM</agency-name> <atc>C10AB05</atc> <submission type="initial-maa" /> <procedure type="mrp" /> <invented-name>Wunderdroge</invented-name> <inn>cureimol monosulphate</inn> <sequence>0000</sequence> <submission-description>Einreichung des Registrierungsdossiers </submission-description> </envelope> </eu-envelope> <envelope country="fr"> <application> <number>pending</number> </application> <applicant>ACME Pharmaceuticals Inc.</applicant> <agency-name>FR-AFSSAPS</agency-name> 228 Regulatory Submissions <atc>C10AB05</atc> <submission type="initial-maa" /> <procedure type="mrp" /> <invented-name>Médicament miracle</invented-name> <inn>cureimol monosulphate</inn> <sequence>0000</sequence> <submission-description>Présentation d'un dossier d'inscription</submission-description> </envelope> </eu-envelope> <m1-eu> …etc. </m1-eu> </eu:eu-backbone> In this case, since the XML file contains multiple envelope elements, multiple values can be extracted for repeating attributes, such as concerned_member_states, product_trade_name, and product_generic_ name. Duplicate values are ignored. The first envelope element pertains to the Reference Member State, and the others pertain to Concerned Member States (this only applies to EU submissions using the MRP; otherwise there would be only one envelope element). The standard XML schema configuration object for the above is “eu-regional_1-2-1.xml” in this case, and has the following predefined settings: XML Schema Configuration Setting Name XML Schema Configuration Setting Value(s) Documentum Attribute Value Extracted from Example XML File (if any) xml_envelope_element envelope — xml_envelope_attrs country_code=@country sv concerned_member_states= .[position()>1]@country de; fr application_number =application/number pending health_authority=agency-name SV-MPA atc_code=atc C10AB05 submission_type=submission /@type initial-maa submission_procedure_type =procedure/@type mrp product_trade_name=invented -name Wonder Drug; Wunderdroge; Médicament miracle product_generic_name=inn cureimol monosulphate sequence_number=sequence 0000 title=submission-description Submission of registration dossier Note the use of the [position()>1] condition in the XPath expression for concerned_member_states, which means that all country codes except that of the first envelope element are extracted and combined together into the concerned_member_states repeating attribute. In the case of single-valued attributes such as country_code, application_number, and title, where there are 229 Regulatory Submissions multiple envelope elements, the first element that has a defined, non-null value takes precedence; usually those that are specified in the first envelope element. Therefore, in this example, country_code is set to sv (the code for Sweden, as specified in the country attribute of the first envelope element) and title is set to “Submission of registration dossier” (the first title value; the German and French title values are ignored in this case, because title is a single-valued attribute in Documentum). Submission-level metadata is also recorded in the Submission History XML file for each submission, enabling this metadata to be displayed by the SSV Viewer. By default, the following attributes are recorded for each submission or eCTD sequence: • submission_number—Recorded in the id XML attribute. • submission_date—Recorded in separate day, month, and year XML attributes, in order to facilitate localization. • submission_type–Recorded in the type XML attribute. • submission_procedure_type—Recorded in the procedure-type XML attribute (applies to EU submissions only). • health_authority—Recorded in the health-authority XML attribute. • concerned_member_states—Recorded in the concerned-member-states XML attribute (applies to EU MRP submissions only). In the standard XSL stylesheet, which is provided as part of the SSV web application (submission-navigator-4.0.xsl), these attributes are listed in the Table of Contents (TOC) view when an application is selected. You can extend the standard XSL stylesheet to include additional custom submission-level metadata in this view. However, only metadata that is recorded in the Submission History XML file can be displayed in this view. To arrange for custom metadata to be recorded in the Submission History XML file at import time, you can change the D2 lifecycle configuration settings for the Regulatory Application Registration Form lifecycle to include a –record_submission_attrs argument, overriding the default settings. Note: Including submission-level metadata in the Submission History XML file that can change after the submission has been imported is not recommended. This would mean that the values recorded in the XML file may be different to the corresponding values in Documentum, leading to inconsistencies between the TOC view in the Submission Navigator and the Submission Registration Form properties page in Documentum. For this reason, properties such as submission_status are omitted from the Submission History XML file in the default installation. However, it is safe to include properties that are read-only after importing. Document-level metadata can also be extracted for each <leaf> element, from both regional M1 XML files and ICH M2-M5 eCTD backbone files, and populated on the corresponding cd_submission_element objects representing the archived submission documents in Documentum. These attributes are defined in the xml_leaf_doc_attrs setting of the ICH eCTD XML Backbone schema configuration object. The default settings for this are as follows: • country_code=@country • dosage_form=ancestor::*[@dosageform != ’’]/@dosageform • drug_product_manufacturer=ancestor::*[@manufacturer != ’’ and @product-name != ’’]/@manufacturer • drug_product_name=ancestor::*[@manufacturer != ’’ and @product-name != ’’]/@product-name 230 Regulatory Submissions • drug_substance_manufacturer=ancestor::*[@manufacturer != ’’ and @substance != ’’]/@manufacturer • drug_substance_name=ancestor::*[@manufacturer != ’’ and @substance != ’’]/@substance • ectd_application_version=@application-version • ectd_checksum_type=@checksum-type • ectd_checksum=@checksum • ectd_element_name=../name() • ectd_operation=@operation • ectd_prev_submitted_file=@modified-file • excipients= ancestor::*[@excipients != ’’]/@excipient • indication=ancestor::*[@indication != ’’]/@indication • title=title Note that some of these attributes, such as dosage_form, drug_product_manufacturer, and so on, are defined in the parent XML elements containing the <leaf> element, which is why the ancestor XPath expression function (or axis) is used for those items. Non-eCTD Electronic Submission Applications that do not adopt the eCTD format use a non-eCTD electronic submission (NeeS) format. For these, each submission has a manually-specified, distinct submission number, and is assumed to be a complete copy of the files sent to the authority in that submission. Incremental changes are not supported by this model. After the first submission has been imported into Documentum SSV, it is not possible to change the application from NeeS to eCTD format. If the Sponsor decides to adopt the eCTD format midway through an application, a new application must be made. Submission Filestore Submissions are generated by some kind of publishing tool and stored in a network filestore that is accessible to both the users and the Documentum Content Server. This enables submission folders to be selected in the D2 browser, and the contents of the those folders to be retrieved asynchronously through the submission import process, which runs as a back-end server method on the Content Server (Java Method Server). 231 Regulatory Submissions The folder path from the Content Server to the submission filestore can be different to the folder path from the desktop of the user to the same submission filestore. For example, if the Content Server is running on Unix, the submission filestore path could be /mnt/ext/eSubmissions, depending on where it is mounted, whereas on the desktop of the user, it could be a UNC path to the relevant server, for example, \\FSVRM1\eSubmissions. Windows-mapped drives can also be used for the client path, but the same drive letter must be mapped on each users desktop for the path to be valid in all cases, for example, S:/eSubmissions. However, Windows-mapped drives cannot be used for the Content Server path, because Windows does not allow them to be used by processes running as a service, such as Documentum. A UNC path from the server is required. If the Content Server is behind a firewall, it may be necessary to replicate the filestore at the storage level, or through a sync-and-share utility, such as Syncplicity, so that the same content is accessible from both sides. WRITE access is required to select the submission filestore because of a D2 limitation. Documentum SSV does not write to the submission filestore (write access is only required for submission publishing). If necessary, enable sharing on the submission filestore itself, so that the appropriate users (including the Documentum installation owner account used by the Content Server, such as dmadmin) have at least Read access to the appropriate folder. You may need to set up a local user account for dmadmin on the machine hosting the filestore, so that the Content Server can connect to it as that user. The EMC Documentum for Life Sciences Installation Guide provides the steps for registering submission filestores. For eCTDs, the user must select either an individual sequence folder, or a parent folder containing a series of sequence folders (that is, an application-level folder), in which case those sequences that have not already been imported are imported into the repository in increments. For NeeS, the selected folder must be a submission-level folder to be imported in its entirety. Existing submission folders in the repository are not updated. To replace existing submission folders in the repository, you must delete the existing submission folder from the repository and reimport it from the external filestore. 232 Regulatory Submissions Configuring the SSV Viewer Widget URLs The Documentum SSV Viewer uses the following external widgets that connect into the D2 client: • The Submission Navigator widget provides a navigation panel in the “View Submission” workspace view, enabling the user to select the required view for the application or submission, drill down into the submission folder structure and select documents for previewing. • The Submission Document Preview widget displays the currently-selected document in a separate panel in the “View Submission” workspace view, enabling the user to browse individual documents and switch between documents easily. This widget can also be used to display regional metadata in XML files selected in the Submission Navigator. • The WG EXT SSV Compare Viewer 1 and WG EXT SSV Compare Viewer 2 widgets provide a side-by-side view of two selected documents in the “Compare” workspace view to enable them to be compared easily. These are separate instances of the same widget used by the Submission Document Preview widget, but with their own configurations in D2, enabling each widget to respond to different document selection events and display the relevant content in its own panel. These widgets may need to be configured to use the widget parameters in the URL. Follow these steps: 1. Log in to D2-Config as Administrator. 2. In the filter on the main toolbar, select EMC Life Sciences Submission Storage and Viewing. 3. On the Widget view menu, click Widget. 4. Under Widgets, select WG EXT Submission History View. 5. In the Widget url field, ensure the Widget URL setting is configured appropriately for your environment. The following parameters can be specified in the URL: Submission Navigator Widget URL Parameters (“WG EXT Submission History View”); Default URL Path: /XMLViewer/XMLViewer.html URL Parameter Description Default Configuration Setting type List of object type(s) to be rendered by this widget. cd_reg_admin_info, cd_reg_submission_info cd_submission_element style XSL stylesheet to use to render the XML file for the relevant application into HTML in the widget panel. (The specified stylesheet must be installed in the %WEB-APPS% /XMLViewer/style folder on the Application Server.) submission-navigator.xsl docViewerWidget Widget ID of the Submission Document Preview widget. SSVLeafDocViewer 233 Regulatory Submissions Submission Navigator Widget URL Parameters (“WG EXT Submission History View”); Default URL Path: /XMLViewer/XMLViewer.html URL Parameter Description Default Configuration Setting docViewerEvent D2 event code to send to the Submission Document Preview widget when a document is selected in the navigation panel. D2_CUSTOM_EVENT initView Initial display mode to use for application-level views, as follows: toc • toc–Table of Contents view • current–eCTD “current” view or first NeeS submission (as appropriate) • cumulative–eCTD “cumulative” view or first NeeS submission (as appropriate) • first–first eCTD sequence or NeeS submission, as appropriate This setting only applies if a Regulatory Application Registration Form is selected. If a Submission Registration Form or Submission Element, that is, an imported submission document, is selected, the appropriate submission or sequence view is opened automatically. initMessage 234 Message to display when the widget is initially loaded and nothing is selected. Underscore characters can be used here to represent spaces, to make it easier to specify the message in the URL. Select_a_Regulatory _Application_Registration _Form, Submission _Registration_Form_or _archived_submission _document Regulatory Submissions Submission Navigator Widget URL Parameters (“WG EXT Submission History View”); Default URL Path: /XMLViewer/XMLViewer.html URL Parameter Description Default Configuration Setting refreshLoginTicketInterval Periodic interval, in seconds, to refresh the D2 login ticket, to prevent tickets from expiring. The specified value should be less than the Documentum login ticket timeout value, as configured in the dm_server_config object for the repository (default = 5 minutes). It should allow a margin of at least 10 seconds for D2 to respond to new ticket requests. 240 workspaceView D2 view labels in the workspace in which this widget is installed. A comma-delimited list of view labels can be specified if necessary; use “%20” to denote a space character in the URL. To avoid unnecessary processing, the currently-selected Regulatory Application Registration Form or Submission Registration Form XML file is not downloaded and rendered until the relevant view is selected. Submission%20View active Indicates whether or not the widget is active in the default workspace view. In single-view workspaces, the value should be set to true; for multi-view workspaces, specify active=true if the widget is in the initial (default) view, and active=false otherwise. false docbase Repository name. The D2 token $DOCBASE can be used here. $DOCBASE 235 Regulatory Submissions Submission Navigator Widget URL Parameters (“WG EXT Submission History View”); Default URL Path: /XMLViewer/XMLViewer.html URL Parameter Description Default Configuration Setting username Username to use for the current session. The D2 token $LOGIN can be used here. $LOGIN password Password to use for the current session. The D2 token $TICKET can be used here. $TICKET A following URL is an example widget URL for the Submission Navigator widget: /XMLViewer/XMLViewer.html?workspaceView=View%20Submission&active =false&format=xml&type=cd_reg_admin_info,cd_reg_submission_info,cd _submission_element&style=submission-navigator&docViewerWidget =SSVLeafDocViewer&docViewerEvent=D2_EVENT_CUSTOM&initMessage=Select_a _Regulatory_Application_Registration_Form,_Submission_Registration_Form _or_archived_submission_document&docbase=$DOCBASE&locale=en&username =$LOGIN&password=$TICKET 6. Click Save. 7. Under Widgets, select WG EXT SSV Leaf Element View and configure the widget URL using the following URL parameters: Submission Document Preview Widget URL Parameters (“WG EXT SSV Leaf Element View”); Default URL Path: /XMLViewer/DocViewer.html 236 URL Parameter Description Default Setting widget_id The ID of this widget, as specified in the docViewerWidget widget in the Submission Navigator URL. SSVLeafDocViewer workspaceView D2 view labels in the workspace in which this widget is installed. A comma-delimited list of view labels can be specified if necessary; use “%20” to denote a space character in the URL. To avoid unnecessary processing, the currently-selected Regulatory Application Registration Form or Submission Registration Form XML file is not downloaded and rendered until the relevant view is selected. Submission%20View Regulatory Submissions Submission Document Preview Widget URL Parameters (“WG EXT SSV Leaf Element View”); Default URL Path: /XMLViewer/DocViewer.html URL Parameter Description Default Setting active Indicates whether or not the widget is active in the default workspace view. In single-view workspaces, the value should be set to true; for multi-view workspaces, specify active=true if the widget is in the initial (default) view, and active=false otherwise. false autoSelect Indicates whether or not the widget should track and preview the currently-selected document in the D2 Doc List widget. If false, the widget responds to custom menu events or events fired by some other widget (for example, the Submission Viewer widget) targeted at this widget ID. false type Comma-delimited list of expected object types. Where specified, only selected documents of the specified type are rendered. Optional; if unspecified, all object types are rendered, if they have suitable content. null useC2Overlays Set as true to display PDF renditions with watermarks or signature pages, according to the C2 view configuration; false to display PDFs without C2 watermarks or signature pages. false imageFormats Comma-delimited list of in-line image formats supported by the browser. jpeg,gif,png docCompareLeftWidgetId Widget ID of the left document preview panel used in the “Compare” view. Optional. If undefined or left blank, the comparison view is disabled. lsDocViewer1 237 Regulatory Submissions Submission Document Preview Widget URL Parameters (“WG EXT SSV Leaf Element View”); Default URL Path: /XMLViewer/DocViewer.html 8. URL Parameter Description Default Setting docCompareRightWidgetId Widget ID of the right document preview panel used in the “Compare” view. Optional. If undefined or left blank, the comparison view is disabled. lsDocViewer2 docCompareEvent D2 event code to send to the comparison widgets to initiate a side-by-side comparison operation. D2_EVENT_CUSTOM initMessage Message to display when the widget is initially loaded and nothing is selected for previewing. Underscore characters can be used to represent spaces here, to make it easier to specify the message in the URL. Select_a_document_in_the _submission_viewer. docbase Repository name. The D2 token $DOCBASE can be used here. $DOCBASE username User name to use for the current session. The D2 token $LOGIN can be used here. $LOGIN password Password to use for the current session. The D2 token $TICKET can be used here. $TICKET Click Save. The use of the standard D2 PDF Preview widget is not recommended in multi-view workspaces because it responds to all document selection events in the Doc List widget irrespective of whether or not the widget is visible. This can lead to performance issues when navigating the repository. Instead, it is recommended that the custom Life Sciences document preview widget is used for previewing. In the standard workspaces, the Life Sciences document preview widget is used by default in several places, with different URL parameters passed to it in each case, so that the widget only downloads and renders content when it is in the currently-active view. The following table summarizes the default widget configurations used for document previews: 238 Regulatory Submissions D2 Widget Configuration Applies To Default URL WG EXT LSS Doc Preview (Browse) Browse and My Sites views in workspaces with a Welcome page /XMLViewer/DocViewer .html?widget_id=lsDocViewer1 &workspaceView =Browse,My%20Sites &autoSelect=true &useC2Overlays=true &initMessage=Select_a _document &docbase=$DOCBASE &locale=en &username =$LOGIN&password=$TICKET WG EXT LSS Doc Preview (Initial Browse) Browse view in workspaces without a Welcome page /XMLViewer/DocViewer .html?widget_id=lsDocViewer1 &workspaceView =Browse &active=true &autoSelect=true &useC2Overlays=true &initMessage=Select_a _document &docbase=$DOCBASE &locale=en &username =$LOGIN&password=$TICKET WG EXT LSS Doc Preview (Tasks) Tasks view /XMLViewer/DocViewer .html?widget_id=lsDocViewer1 &workspaceView=Tasks &autoSelect=true &useC2Overlays=true &initMessage=Select _a_document &docbase =$DOCBASE&locale =en&username=$LOGIN &password=$TICKET WG EXT SSV Doc Compare Viewer1 Compare view on the left pane /XMLViewer/DocViewer .html?widget_id=lsDocViewer1 &initMessage=Select_a _document_for_comparison_in _Viewer_1 &docbase=$DOCBASE &locale=en &username =$LOGIN &password=$TICKET 239 Regulatory Submissions D2 Widget Configuration Applies To Default URL WG EXT SSV Doc Compare Viewer2 Compare view on the right pane /XMLViewer/DocViewer .html?widget_id=lsDocViewer2 &initMessage=Select_a _document_for_comparison_in _Viewer_2 &docbase=$DOCBASE &locale=en &username =$LOGIN &password=$TICKET WG EXT SSV Leaf Element Viewer Right document preview panel in the View Submission view /XMLViewer/DocViewer .html?widget_id =SSVLeafDocViewer &workspaceView =View%20Submission &active=false &autoSelect=false &useC2Overlays=false &docCompareLeftWidgetId =lsDocViewer1 &docCompareRightWidgetId =lsDocViewer2 &initMessage =Select_a_document_in _the_Submission_Viewer &docbase=$DOCBASE &locale=en &username=$LOGIN &password=$TICKET If you decide to remove the Welcome pages, change the standard view labels or allow users to add the Life Sciences Document Preview widget to other workspace views, it may be necessary to adjust the widget URL parameters so that the widget is enabled correctly for the new view labels. Do not activate the same widget in more than one view within a multi-view workspace, as this will cause performance issues. If necessary, create a new D2 widget configuration in D2-Config for the new view, with the appropriate URL parameters, alongside the standard widget configurations described above. This must then be enabled in the D2 configuration matrix for the appropriate roles and added to the default workspace view configuration XML files as necessary. In addition, make sure that the widget description is set appropriately in D2-Config in each case. When users want to add preview widgets to the standard workspaces, they can identify the correct widget in the gallery. 240 Regulatory Submissions Processing of PDFs and Inter-Document Hyperlinks Documentum SSV generates a PDF preview rendition (represented by the pdf_preview object in the Documentum SSV object model) for each document in an eCTD or NeeS submission that has the eCTD PDF Document or NeeS PDF Document element type, respectively, in the file info map. The generated renditions include hyperlinks to other submission documents. The document is opened for reading through the itext PDF library, which is included with D2 and is used by the C2 plug-in to process PDF files. If the document contains a PDF Document Information (DocInfo) field, which represents the source document object ID with a non-null value referring to a valid dm_document object in the current repository, a relation of type Source Document is created in the repository between the parent document and the imported child document in the repository. A Used in Submission relation is also created between the source parent document and the child submission folder. The source_object_pdf_docinfo_field parameter specifies an optional PDF DocInfo field used by the submission publishing tool to record the Documentum r_object_ids of the original source documents in the published PDF documents. When publishing documents from Documentum, it is useful to embed the source object IDs in the corresponding published PDFs in a designated DocInfo field. Any of the standard DocInfo fields can be used for this purpose such as Subject. Alternatively, a custom DocInfo field can be used, such as SourceObjectId, which will not be shown on the document properties page of Adobe Acrobat. Configuring the Document Information parameter enables the system to track the original source documents and relate them to the corresponding published submission documents when they are imported into the repository through the Import Submission function. The EMC Documentum for LifeSciences Installation Guide provides the steps for configuring the PDF DocInfo parameter in the D2 dictionary. If the document contains inter-document hyperlinks (that is, relative filepath links, also known as “/GoToR” links in PDF terminology), they are converted into D2 hyperlinks (“/URI” links) to the relevant object in the repository. The resulting document, if modified, is saved as a new PDF file and is checked-in as a pdf_preview rendition of the relevant document in the repository. The original PDF content file/rendition is preserved. The format attribute of the corresponding XML DOM object is updated to the pdf_preview object accordingly. If the file does not contain any inter-document hyperlinks, the system does not generate a pdf_preview rendition; the primary content file (pdf format) is previewed. Note that this processing does not apply to other types of PDF links, such as intra-document links (“/GoTo” links) or web links (“/URI” links). Such links are preserved as is in the PDF rendition. A limitation is that hyperlinks to specific pages or named destinations within the target document are not supported in the preview renditions. Instead, these links navigate to the first page of the target document. This is a D2 product limitation. 241 Regulatory Submissions Study Tagging Files Study Tagging Files (STFs) are XML files that may be included in the m4 (Non-Clinical) and m5 (Clinical) sections, primarily for submissions to the US FDA. These are optional for European submissions, and are not allowed for Japanese submissions. Each STF relates to a specific study, and may refer to several study documents (for example, Clinical Study Reports) in a particular section of the eCTD. By convention, the STF XML file is named “stf-<study-id>.xml”, where <study-id> is a unique study identifier, and is located in the appropriate folder in the eCTD, alongside the documents it references. There may be several STFs in one folder, one for each study. The purpose of an STF is to: • Provide additional metadata about each study, for example, the study ID, title, duration, species and type of control used in each case • Enable the individual study documents to be grouped by study • Provide additional information about the contents of each study document, known as its file tags. Usually, there is one file tag per study document indicating the purpose of that document, if defined; for example, “synopsis” or “study-report-body”. However, it is possible for a study document to have multiple file tags in an STF. If an STF is not provided for a particular study, the SSV Viewer displays the study documents in the relevant eCTD section as a flat list, exactly as they appear in the eCTD XML backbone file. For example, suppose section M5.3 of an eCTD XML backbone file contains the following entries: <m5-3-clinical-study-reports> <m5-3-1-reports-of-biopharmaceutic-studies> <m5-3-1-2-comparative-ba-and-bioequivalence-study-reports> <leaf id="id106245" operation="new" xlink:href="m5/53-clin-stud-rep/531-rep-biopharm-stud/ 5312-compar-ba-be-stud-rep/csr-5312.001.pdf"> <title>csr-5312.001</title> </leaf> <leaf id="id106246" operation="new" xlink:href="m5/53-clin-stud-rep/531-rep-biopharm-stud/ 5312-compar-ba-be-stud-rep/csr-5312.002.pdf"> <title>csr-5312.002</title> </leaf> <leaf id="id106247" operation="new" xlink:href="m5/53-clin-stud-rep/531-rep-biopharm-stud/ 5312-compar-ba-be-stud-rep/csr-5312.003.pdf"> <title>csr-5312.003</title> </leaf> </m5-3-1-2-comparative-ba-and-bioequivalence-study-reports> </m5-3-1-reports-of-biopharmaceutic-studies> </m5-3-clinical-study-reports> Each section in modules M4 and M5 can contain multiple study report documents pertaining to multiple studies. However, where there are many study documents, it may be difficult for users to navigate the submission structure and find documents related to a particular study. STFs facilitate this process by providing additional metadata for each study, over and above that which is provided in the standard ICH XML backbone file. An example code is as follows: <?xml version=”1.0” encoding=”UTF-8”?> <!DOCTYPE ectd:study SYSTEM "../../util/dtd/ich-stf-v2-2.dtd"> <?xml-stylesheet type="text/xsl" href="../../util/style/ich-stf-stylesheet-2-2a.xsl"?> <ectd:study xmlns:ectd="http://www.ich.org/ectd" xml:lang="en" dtd-version="2.2" xmlns:xlink="http://www.w3.org/1999/xlink"> <study-identifier> <title>Wonderdrug Phase III Clinical Study Report: SN-3.001</title> <study-id>3.001</study-id> 242 Regulatory Submissions <category name="species" info-type="ich">human</category> <category name="route-of-admin" info-type="ich">oral</category> <category name="type-of-control" info-type="ich">dose-response-without-placebo</category> </study-identifier> <study-document> <doc-content xlink:href="../../../../index.xml#id106245"> <title>SN-3.001.01 – Overview of study objectives</title> <file-tag name="synopsis" info-type="ich"/> </doc-content> <doc-content xlink:href="../../../../index.xml#id106246"> <title>SN-3.001.02 – Long-term dose response results in human trials for Wonderdrug 50mg capsules</title> <file-tag name="study-report-body" info-type="ich"/> </doc-content> <doc-content xlink:href="../../../../index.xml#id106247"> <title>SN-3.001.03 – Amendments to Clinical Study Protocol</title> <file-tag name="protocol-or-amendment" info-type="ich"/> </doc-content> </study-document> </ectd:study> The STF XML file resides in the same folder as the study report documents; in this case, the 5312-compar-ba-be-stud-rep folder (used for comparative bioavailabilty/bioequivalence studies). Documentum SSV uses a built-in XSL script, stf-2-2-normalize.xslt, to convert the STF XML files into a standard format that is easy to process (just as for other non-standard XML files, such as Japanese regional M1 XML files). This script is installed as the primary content file of the XML schema configuration object named stf_2-2, which applies to v 2.2 Study Tagging Files; XSL transformation is enabled for this schema, so that all STF XML files are transformed automatically by this script: <?xml version="1.0" encoding="UTF-8"?> <!--Stylesheet used to convert ICH Study Tagging Files (STFs) into a form that can be embedded into Submission History XML files. The output is an XML document of the form: <stf label="study-id" study-attr-1="value-1" study-attr-2="value-2"...> <leaf ID="..." operation="..." xlink:href="...path..." checksum="..." checksm-type="..." application-type="..." modified-file="...path..." file-tag="..."> <title>...</title> </leaf> ... </stf> Author: Pete Higgins EMC Information Intelligence Group --> <xsl:transform version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns:ectd="http://www.ich.org/ectd" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xlink-ectd="http://www.w3c.org/1999/xlink"> <xsl:output method="xml" version="1.0" encoding="UTF-8" indent="yes"/> <xsl:template match="/"> <xsl:element name="stf"> <xsl:attribute name="label"> <xsl:value-of select="/ectd:study/study-identifier/study-id"/> </xsl:attribute> <xsl:for-each select="/ectd:study/study-identifier/category"> <xsl:attribute name="{@name}"> <xsl:value-of select="."/> </xsl:attribute> </xsl:for-each> 243 Regulatory Submissions <xsl:apply-templates select="/ectd:study/study-document/*"/> </xsl:element> </xsl:template> <xsl:template match="doc-content"> <xsl:variable name="backbone-file" select="'/index.xml'"/> <xsl:variable name="backbone" select="document($backbone-file, *)"/> <xsl:variable name="leaf-id" select="substring-after(@xlink:href, '#')"/> <xsl:variable name="leaf-node" select="$backbone//leaf[@ID=$leaf-id]"/> <xsl:variable name="leaf-file-tag" select="file-tag/@name"/> <xsl:variable name="leaf-title" select="title"/> <xsl:element name="leaf"> <xsl:attribute name="ID"><xsl:value-of select="$leaf-id"/></xsl:attribute> <xsl:attribute name="operation"><xsl:value-of select="$leaf-node/@operation"/> </xsl:attribute> <xsl:attribute name="xlink:href"><xsl:value-of select="$leaf-node/@xlink-ectd:href"/> </xsl:attribute> <xsl:attribute name="checksum"><xsl:value-of select="$leaf-node/@checksum"/></xsl:attribute> <xsl:attribute name="checksum-type"><xsl:value-of select="$leaf-node/@checksum-type"/> </xsl:attribute> <xsl:attribute name="application-type"><xsl:value-of select="$leaf-node/@application-type"/> </xsl:attribute> <xsl:attribute name="modified-file"><xsl:value-of select="$leaf-node/@modified-file"/> </xsl:attribute> <xsl:attribute name="file-tag"><xsl:value-of select="$leaf-file-tag"/></xsl:attribute> <xsl:element name="title"> <xsl:value-of select="$leaf-title"/> </xsl:element> </xsl:element> </xsl:template> <xsl:template match="*"/> </xsl:transform> This information can then be manifested in the main Submission Viewer panel, with links to the three study reports arranged underneath the study tagging file node itself. If the version 2.2 study tagging file format is revised in the future, a new XSL transformation script may need to be developed to transform it into the same format as above, so that it can be processed by SSV. To accomplish this: 1. Copy the /XMLViewer/style/stf-2-2-nornalize.xslt script provided, rename it accordingly, and edit it to convert the new format into the same “normalized” XML format described above. 2. In Documentum Administrator, copy the stf_2-2 XML schema configuration object and rename it accordingly. Adjust the xpath_qualifier setting to refer to the new version of the STF. 3. Use the check-out/check-in from file functionality in Documentum Administrator to replace the main content file of the new XML schema configuration object with the new XSL transformation script developed in step 1. 4. Import a sample eCTD submission using the new STF format and verify that it can be navigated correctly. 244 Regulatory Submissions Previewing of Media Files Media files, such as video, can be included in submissions and previewed in Documentum SSV. Any media file format supported by Windows Media Player can be previewed. The formats that are supported can be specified in the (optional) "mediaFormats" URL parameter to the SSV Submission Document Preview widget as a comma-delimited list of dm_format names. Where unspecified, the default formats are wmv, avi, mpg/mpeg/mpg-4v, quicktime, and wav files. Adding Custom Format Icons If new content formats are to be supported, it may be necessary to provide icons for them in the %WEBAPPS%/icons/format folder, so that the correct icons are displayed in the Submission Viewer. Icons for the standard formats are pre-installed. Additional icon files must be provided as GIF (Graphics Interchange Format) files of size 16x16 pixels, and the file name must be the same as the corresponding dm_format name in each case (for example, mpeg.gif). In many cases, GIF files for new formats can be obtained from the Documentum Administrator web application folder, %WEBAPPS%/da/wdk/theme/documentum/icons/format. Copy the relevant f_<format>_16.gif file to the %WEBAPPS%/XMLViewer/icons/format folder, and rename the file as <format>.gif. Do not use the larger 32-bit icon files as this can disrupt the tree view in Documentum SSV. 245 Regulatory Submissions 246 Chapter 14 Migration and Integrity Check Utilities This chapter contains the following topics: • D2 Configuration Migration Tool, page 247 • TMF Admin Integrity Checking and Repair Tool, page 249 D2 Configuration Migration Tool The D2 Configuration Migration tool is a command-line tool that can be used by System Administrators to apply D2 auto-linking, auto-naming and/or security configurations selectively to specific objects in the repository. You may need to run this tool in the following cases: • After migrating a set of new or legacy documents into the repository into a staging area folder, D2 auto-linking to be applied to them. • After making changes to the D2 auto-linking, auto-naming, or security configurations that are to be applied to the existing documents. • After a bulk DQL update operation that changes the users and groups assigned to various roles, in order to update the security on those documents. The tool supports multithreaded parallel processing, and also distributed processing across multiple Content Servers. The tool can be scaled-out both horizontally, by providing more servers, and vertically, by increasing the number of parallel processing threads on each server. Installing the D2 Configuration Migration Tool The D2 Configuration Migration tool is shipped as part of the Life Sciences solution suite. Batch scripts for both UNIX and Windows installations are provided within the utils/migration folder of the Life Science solution installation package. These files can only be executed on a Documentum Content Server host that has the Life Sciences solution server components installed on it. To install the scripts, copy the relevant files to an arbitrary folder on the Content Server. On UNIX, ensure that the shell scripts are set to be executable through the chmod o+x command. 247 Migration and Integrity Check Utilities To install the tool on a system that has D2 but does not have any of the Life Sciences Solution modules installed: 1. Copy the CDF-Methods.jar file (the Controlled Document Foundation server method library) to the Java Method Server lib folder on each Content Server, along with the D2 jars, found in the location, %Documentum%\jboss5.1.0\server\DctmServer_MethodServer\deploy \ServerApps.ear\lib 2. Restart the Java Method Server on each node after installing the JAR file, so that it loads the new JAR. 3. To support distributed processing in multi-node Content Server architectures, you must create a dm_method object in Documentum to enable remote processing: a. Log in to Documentum Administrator (or equivalent tool) as the Documentum installation owner. b. Run the following DQL statement: create dm_method object set object_name = 'CDFApplyD2ConfigurationsMethod', set title = 'CDF', set method_verb = 'com.emc.d2.api.methods.D2Method -class_name com.documentum.cdf.methods.ApplyD2Con figurations,set method_type = 'java', set use_method_server = true, set launch_async = false, set run_as_server = true, set timeout_min = 3600, set timeout_max = 86400, set timeout_default = 7200 This creates the required dm_method object with timeout set to 7200s (2 hours) by default (adjust the timeout parameters if necessary). Configuring the D2 Configuration Migration Tool To view the usage notes for the tool: • On Windows, double-click the ApplyD2Configurations.bat script in Windows Explorer. • On UNIX, run the ApplyD2Configurations.sh script without any parameters, or with the help parameter. You can configure the default settings for the tool parameters in the D2 “System Parameters” dictionary in D2-Config, rather than specifying them explicitly on the command line. The following is an example of a Windows command that applies D2 configurations (auto-naming, auto-linking, and security) to all controlled documents below the /Clinical/Cardiology-Vascular/Vasonin folder, including sub-folders of this folder: C:\Users\dmadmin> ApplyD2Configurations -docbase_name documentum -user_name dmadmin -password "" -qualifier "cd_controlled_doc where folder('/Clinical/Cardiology-Vascular/Vasonin', descend)" -verbose true In this example, C:\Users\dmadmin> is the Windows command prompt, indicating the folder where the scripts are installed. The parameters are the same for UNIX: $ sh ApplyD2Configurations -docbase_name documentum -user_name dmadmin -password "" 248 Migration and Integrity Check Utilities -qualifier "cd_controlled_doc where folder('/Clinical/Cardiology-Vascular/Vasonin', descend)" -verbose true D2 auto-naming, auto-linking and security are applied by default. To apply them selectively, specify the appropriate flags on the command line explicitly; for example, C:\Users\dmadmin> ApplyD2Configurations -docbase_name documentum -user_name dmadmin -password "" -qualifier "cd_controlled_doc where folder('/Clinical/Cardiology-Vascular/Vasonin', descend)" -verbose true –auto_naming false –auto_linking false –security true To process new documents, include the –new true argument, so that D2 applies auto-naming and auto-numbering correctly. Otherwise, it retains the existing auto-numbering values. You can also specify a D2 lifecycle state transition to apply to each document, through the –state_transition argument. For example, –state_transition "(init)" applies the initial lifecycle state actions to each document, as specified in the D2 lifecycle configuration for the “(init)” state. The –delete_empty_folders option is also useful for cleaning up any empty folders below the specified top-level folder. For example, C:\Users\dmadmin> ApplyD2Configurations -docbase_name documentum -user_name dmadmin -password "" -qualifier "cd_controlled_doc where folder('/Clinical/Cardiology-Vascular/Vasonin', descend)" -verbose true –auto_naming true –auto_linking true –security true –delete_empty_folders "/Clinical/Cardiology-Vascular/Vasonin" When using the –auto_linking option, empty folders are sometimes generated as a result of conflicts between parallel processing threads. These are prefixed by dm_fix_me labels in the folder names. Such folders can be cleaned out by enabling the –delete_empty_folders option. Note that the use of the –auto_linking and –state_transition options, in particular, can increase the processing time required by the tool substantially. If the documents can be migrated into the relevant folders directly and initialized with the appropriate metadata in advance, it is better to do so, in order to avoid lengthy processing. If this cannot be avoided, and there are many documents to be processed, consider increasing the number of processing threads available through the –max_threads parameter. If multiple Content Servers are available, you can enable distributed processing as follows: C:\Users\dmadmin> ApplyD2Configurations -docbase_name documentum -user_name dmadmin -password "" -qualifier "cd_controlled_doc where folder('/Clinical', descend)" -verbose true –content_servers "^*" –max_threads 8 –distributed_processing_threshold 1000 In this example, assuming there are more than 1000 documents to be processed (the -distributed_ processing_threshold value), the tool splits the processing tasks across all available servers. Note the use of the caret symbol before the “*” symbol, which prevents the Windows command-line shell from expanding this symbol into a list of files in the current directory. On UNIX, use –content_servers “\*” to achieve the same results. TMF Admin Integrity Checking and Repair Tool The TMF Integrity Checking and Repair tool (also known as the TMF Admin tool) is a command-line system administration utility. This tool enables System Administrators to validate the external role group security settings for TMF documents and folders and optionally repair them. This tool can: • Examine the TMF documents and subfolders in a specified top-level folder, and highlight those that have incorrect role groups assigned to them. Optionally, it can automatically fix those 249 Migration and Integrity Check Utilities documents and folders and reapply D2 security to them, create any missing groups as required, and delete groups that are no longer used. • Force a refresh of the external group members for specific trials, countries, and sites. This ensures that appropriate levels of access are granted to the external users on the relevant TMF artifacts. It also ensures that read-only access is granted to the TMF folders and registration forms to enable navigation and searching on specific products, trials, countries and sites. • Dump selected group hierarchies to enable group members to be examined more closely, and optionally purge or delete them completely. You may need to run this tool in the following scenarios: • After migrating a set of new TMF documents into the repository for a currently-active trial. • After upgrading from a previous version of the Life Sciences eTMF solution to migrate the correct TMF role-based security settings to the existing documents. • After updating the external user registrations in a registration form outside of the D2-Client, for example, through the TMF SDK or bulk DQL update. • After changing the TMF role group naming conventions in D2-Config. • After changing product codes, combining products, moving a trial to a different product, or moving a site to a new trial, requiring the role groups to be reconstructed. Installing the TMF Admin Tool The TMF Admin tool is provided in the form of batch scripts in the utils/tmf subfolder within the Life Sciences solution package. Batch scripts for both UNIX and Windows installations are provided. These scripts must be installed on a Documentum Content Server host that has the Life Sciences solution server components installed on it. Copy the relevant files to an arbitrary folder on the Content Server. On UNIX, ensure that the shell scripts are set to be executable through the chmod o+x command. To view the usage notes: • On Windows, double-click the TMFAdmin.bat script in Windows Explorer to view the usage notes. • On UNIX, run the TMFAdmin.sh script without any parameters, or with the help parameter. Examining Access Control Groups The –show command can be used to dump the contents of a group, including the group members and its sub-groups. For example, the following Windows command dumps the entire dynamic role group hierarchy: C:\Users\dmadmin> TMFAdmin -docbase_name documentum -user_name dmadmin -password "" –show tmf_contributors | more In the above example, C:\Users\dmadmin> is the Windows command prompt, indicating the folder where the scripts are installed. The parameters are the same for UNIX: 250 Migration and Integrity Check Utilities $ sh TMFAdmin.sh -docbase_name documentum -user_name dmadmin -password "" -show tmf_contributors | more In both cases, the output is piped to the more command to enable it to be scrolled through. The tool can generate a lot of output if you dump the entire group structure in this way. It is more useful to focus on a particular subgroup. For example, the groups for clinical trial AMX001 only can be obtained using the command: C:\Users\dmadmin> TMFAdmin -docbase_name documentum -user_name dmadmin -password "" –show tg_amx001 | more Checking and Repairing the TMF Security Settings for External Users The –show command can be used to perform an integrity check on the external access control groups currently assigned to documents and folders at and below a specified TMF folder. In this case, you should specify the cabinet or folder path of the top-level folder to check. For example, C:\Users\dmadmin> TMFAdmin -docbase_name documentum -user_name dmadmin -password "" –show "/Clinical/Cardiology-Vascular/Vasonin" –verbose true The output shows that the access control groups on all of the TMF documents and folders for the product named “Vasculin” are configured correctly. However, the groups themselves may still need to be refreshed. In the next example, another product named “AIR” is selected, and this time, the tool reports a number of issues. To focus on the errors, the –verbose option is turned off: C:\Users\dmadmin> TMFAdmin -docbase_name documentum -user_name dmadmin -password "" –show "/Clinical/Cardiology-Vascular/AIR" –verbose false The output shows that there are 95 documents and one folder that must be repaired, and one redundant group “tg_A001” that should be deleted. These issues were brought about by bulk DQL updates to the repository, which caused the trial “A001” to be deleted, and changes to the TMF configuration in D2 affecting the way the external roles and folder levels are interpreted. To fix this, run the tool again in repair mode, as follows: C:\Users\dmadmin> TMFAdmin -docbase_name documentum -user_name dmadmin -password "" –repair "/Clinical/Cardiology-Vascular/AIR" –verbose false The parameters are the same except that –show has been changed to –repair. The tool then fixes all documents and folders that need repairing, reapplying D2 security in each case to ensure the access controls are corrected. You can combine both the –show and –repair arguments in one operation. For example, C:\Users\dmadmin> TMFAdmin -docbase_name documentum -user_name dmadmin -password "" –repair "/Clinical/Cardiology-Vascular/AIR" –show "/Clinical/Cardiology-Vascular/AIR" –verbose false In this case, the repair phase is always carried out first followed by the revalidation phase. The repair phase uses the same distributed/parallel processing mechanism as the D2-Configuration Migration tool and supports the same -max_threads, -content_servers, and –distributed_processing_threshold parameters, enabling potentially very large-scale repairs to be carried out in extreme scenarios. 251 Migration and Integrity Check Utilities Refreshing TMF Access Control Groups for Registered External Users External user registrations are stored: • at the trial (study) level, in the Clinical Trial Registration Forms • at the country (regional) level, in the Country Registration Forms for a particular trial • at the site level, in the Site Registration Forms for a particular trial/country The registrations are stored in repeating attributes associated with these forms. Whenever these attributes are updated through the Manage External Users lifecycle action in D2, the corresponding role groups are updated automatically to include only those users with active registrations. This immediately grants or revokes access to the relevant TMF documents and folders to the external users, as and where appropriate. It is not necessary to update the documents and folders themselves; only the group members must be updated. The group refresh operation is also carried out automatically on a daily basis for those registrations that are active through the D2 batch lifecycle job. This operation takes account of registrations that are active for a specified time interval. However, it is also possible to trigger the refresh operation on-demand through the TMF Admin tool. To do this, specify the –refresh parameter on the command line, followed by a DQL qualifier identifying the registration forms to be processed. For example, to refresh the external user groups for a specific site, with site ID “CH000001”, use: C:\Users\dmadmin> TMFAdmin -docbase_name documentum -user_name dmadmin -password "" -refresh "cd_clinical_site_info where tmf_site_id = 'CH000001'" To refresh the external user groups for all sites in a specific country, it is only necessary to identify the relevant Country Registration Form. For example, the following refreshes the groups for trial “AMX001” and country code “CH” (Switzerland), both at the country level and at the site level: C:\Users\dmadmin> TMFAdmin -docbase_name documentum -user_name dmadmin -password "" -refresh "cd_clinical_country_info where clinical_trial_id = 'AMX001' and country_code = 'CH'" Likewise, to refresh all site/country groups across all countries for a particular trial, it is only necessary to identify the relevant Clinical Trial Registration Form. For example, C:\Users\dmadmin> TMFAdmin -docbase_name documentum -user_name dmadmin -password "" -refresh "cd_clinical_trial_info where clinical_trial_id = 'AMX001'" To refresh all groups for all currently-active trials for a particular product, for example, “Vasonin”, use: C:\Users\dmadmin> TMFAdmin -docbase_name documentum -user_name dmadmin -password "" -refresh "cd_clinical_trial_info where product_code = 'Vasonin' and a_status = 'Active' and use_dynamic_access_ctrls = true" The use_dynamic_access_ctrls = true qualifier avoids unnecessary processing of TMFs that do not have dynamic access controls enabled. Finally, to refresh all external role groups throughout the repository, use: C:\Users\dmadmin> TMFAdmin -docbase_name documentum -user_name dmadmin -password "" -refresh "cd_clinical_trial_info where a_status = 'Active' and use_dynamic_access_ctrls = true" Note: This can potentially involve a lot of processing if there are many active trials in the system, and it should be used with caution. The mechanism utilizes the distributed/parallel processing mechanism to process the groups when a large number of groups must be updated, and you can 252 Migration and Integrity Check Utilities use the -max_threads, -content_servers, and –distributed_processing_threshold parameters as and where appropriate. In each case, the –reset true option can be specified in order to purge the relevant groups. For example, the following command can be used to revoke all external access to a particular trial: C:\Users\dmadmin> TMFAdmin -docbase_name documentum -user_name dmadmin -password "" -refresh "cd_clinical_trial_info where clinical_trial_id = 'AMX001' –reset true" Purging and Deleting Specific Groups The –purge and –delete commands can be used to forcibly revoke external user access as a last resort: • -purge <group-name> clears out all of the user members from the specified group, including its sub-groups in recursive fashion, leaving the group hierarchy empty but intact. • -delete <group-name> detaches the specified group from any ACLs that refer to it, then deletes the group from the repository, including its subgroups recursively. These commands can be used to purge and drop any Documentum group and not just TMF access control groups. However, they should be used with caution, as the effects may be irreversible. A backup of the repository database is taken before making such changes. The following example purges the external access control groups at and below the trial level for the Clinical Trial “AMX001”: C:\Users\dmadmin> TMFAdmin -docbase_name documentum -user_name dmadmin -password "" –purge tg_amx001" The same effect can be brought about by refreshing the relevant Clinical Trial Registration Form with the –reset option enabled as described previously, which is preferred technique, as this ensures the correct groups are purged. However, it may occasionally be necessary to revoke external user access to all trials for a particular product. The most efficient way to do this is to purge the relevant product group. For example, for the product “Vasonin”: C:\Users\dmadmin> TMFAdmin -docbase_name documentum -user_name dmadmin -password "" –purge pg_vasonin" The relevant trial, country, and site registration forms may also need to be deactivated to prevent them from being refreshed and reinstating external user access. The following DQL query can be used to achieve this: IDQL> update cd_common_ref_model objects set a_status = 'Inactive' where r_object_type in ('cd_clinical_trial_info', 'cd_clinical_country_info', 'cd_clinical_site_info') and product_code = 'Vasonin' The –delete option can be used where the group hierarchy needs to be rebuilt, for example, if the group structure has been reorganized. This is usually only necessary for migration/upgrade purposes. It is possible to rebuild the entire TMF group hierarchy using the following technique: • Delete the top-level tmf_contributors group. • Run the tool in repair mode against the entire /Clinical cabinet. This rebuilds all of the required groups, although they will not be populated at this stage. • Refresh all active trials to repopulate the groups. • Verify that the groups have been created successfully. 253 Migration and Integrity Check Utilities The following command accomplishes this in one operation: C:\Users\dmadmin> TMFAdmin -docbase_name documentum -user_name dmadmin -password "" –delete tmf_contributors –repair "/Clinical" -refresh "cd_clinical_trial_info where a_status = 'Active' and use_dynamic_access_ctrls = true" –show "/Clinical" This command should only be used as a last resort to rebuild the access control groups, as it is likely to involve very substantial processing, especially in mature repositories. 254 Chapter 15 Life Sciences Source Development Kit This chapter contains the following topics: • Overview, page 255 • Web Services Integration, page 255 • Supported Functionality in the SDK, page 256 Overview The Life Sciences solution Source Development Kit (SDK) enables System Integrators and Developers to integrate an individual solution such Documentum eTMF, R&D, or SSV with an existing external application or management system. Developers can develop plugins for the management system in Java and use the SDK to synchronize the Documentum repository in response to the management system events. The SDK exposes basic functions of the solution, such as creating registration forms, through a Java API and uses standard EMC Documentum Foundation Services (DFS) Web Service calls for integration purposes. Detailed JavaDocs on the SDK are provided in the javadocs folder of the SDK package. Web Services Integration DFS provides a set of Web Services for integrating applications with Documentum in a standard way. This enables external applications to store, retrieve, and manipulate objects in the repository, execute queries, and download or upload content files from and to the repository. DFS is included as part of the EMC Documentum Content Server installation. By default, DFS is hosted by the Documentum Java Method Server (JMS) running under JBoss. However, it is possible to host DFS Web Services on a separate host if necessary. The DFS documentation available on EMC Online Support (https://support.emc.com/) provide more information about installing and using DFS. DFS provides basic repository services and uses a generic data model for representing repository objects such as documents and folders. It does not use D2 configurations implicitly, although it is possible to query D2 configurations and appIy them through DFS service calls. It does not provide data models for Life Sciences solution-specific entities, for example, TMF-specific entities such as Clinical Trial Registration Forms, TMF documents, and so on. It does not support Life 255 Life Sciences Source Development Kit Sciences solution-specific functionality either. Therefore, to facilitate the development of external applications that integrate with a Life Sciences solution, a Java Client Library (JCL) is provided as part of the solution. Java Client Library The JCL acts as a productivity layer on top of the standard DFS SDK client library, simplifying access to the repository and providing a set of solution-specific Java classes. The following diagram shows the DFS Web Service architecture for the Life Sciences solution: The JCL productivity layer is packaged as a JAR file that can be included in Java applications. Although it is possible for client applications to directly call the DFS Web Services through the SDK, it is recommended that the operation be carried through the JCL to safeguard the application against future changes to the Life Sciences solution. Supported Functionality in the SDK The JCL in the Life Sciences solution SDK supports the following functionality: • General convenience functions for managing connections to the Documentum repository, retrieval of login credentials and other applications-specific parameters from properties files, running DQL queries, and so on. • Creation, retrieval, modification, and deletion of eTMF registration forms of various types, including Product Registration Forms, Country / Site Registration Forms, and Clinical Trial Registration Forms, including template registration forms for each of the above. • Retrieving, merging, and modifying file plans associated with registration forms of various types, that is, lists of expected artifacts (document types) to be created at the product, trial, country 256 Life Sciences Source Development Kit and/or site level in the TMF structure. This includes Product, Country, Trial, and Site-level file plans and associated templates. • Validation of file plans to ensure the relevant fields are defined and valid in the context of the trial, for example, to ensure country codes or site IDs refer to registered countries or sites for the trial. • Storage and retrieval of file plans in Microsoft Excel format, which is predefined with built-in value-assistance provided in the form of lookup tables. • Activation and deactivation of file plans to create or remove placeholders for the expected documents. File plans can be planned in stages if preferred, and activated in incremental fashion; an initial trial setup stage followed by an active trial stage, then a final close-out stage. A rollover function is provided to enable the next stage to be activated (this can also be configured to occur automatically if necessary). Alternatively, all defined stages can be activated at once if preferred, so that stages can be used to break up the overall file plan into manageable units. • Update and retrieval of progress statistics indicating the current level of completion of a trial (up to and including the currently-active stage). • D2 configuration lookup functions for dictionary entries, default value sets, creation matrices, and taxonomies, to enable country codes to be translated into locale-specific names, default values to be applied to new repository objects, and so on. Currently, this is restricted to read-only operations. D2 configuration changes are not supported through the JCL; this must be done through D2-Config. • TMF placeholder retrieval/update functions, enabling placeholders in the repository to be identified and replaced with document content programmatically for example, to transfer a Site Management Report (SMR) document from a Clinical Trial Management System (CTMS) into Documentum eTMF in response to a particular CTMS event such as SMR review/approval. • Ability to invoke D2 lifecycle transition actions on TMF documents and placeholders, enabling the relevant actions to be configured through D2-Config and invoked through the SDK just as in the D2 Client. • Registration of external users for access to the TMF documents at the trial, country and site levels in the appropriate roles, with automatic refresh of the corresponding role groups when the forms are saved. • Creation, retrieval, modification, and deletion of Non-Clinical Study Registration Forms including updating the Group, Subgroup, and other information specific to the registration form. • Creation, retrieval, modification, and deletion of Non-clinical documents including updating the metadata of the Non-clinical documents during creation or modification. • Creation, retrieval, modification, and deletion of Regulatory Application Registration Forms including updating the Group, Subgroup, and other information specific to the registration form. • Creation, retrieval, modification, and deletion of Regulatory documents including updating the metadata of the Regulatory documents during creation or modification. • Creation, retrieval, modification, and deletion of Quality Project Registration Forms including updating the metadata during creation or modification of the registration form. • Creation, retrieval, modification, and deletion of Regulatory Application Labeling documents including updating the metadata of the Labeling documents during creation or modification. 257 Life Sciences Source Development Kit • Creation, retrieval, modification, and deletion of Regulatory Core Labeling documents including updating the metadata of the Labeling documents during creation or modification. • Creation, retrieval, modification, and deletion of Regulatory Correspondence documents including updating the metadata of the Correspondence documents during creation or modification. 258 Chapter 16 Configuration Settings to Improve Performance This section provides various configuration settings that you can make to improve the performance of the Life Sciences solutions. Disabling the dm_bpm_XCPAutoTaskMgmt Job As Documentum Process Engine 2.2 is installed as a prerequisite for the Life Science solutions, the job, dm_bpm_XCPAutoTaskMgmt, is enabled to run by default. However, the dm_bpm_XCPAutoTaskMgmt job is only used for processing special workitems with ’to be processed by job’ in the name, which is xCP-related. This job is not required by the Life Science solutions and therefore, can be disabled to improve the overall performance of the Life Sciences solutions. 259 Configuration Settings to Improve Performance 260 Appendix A Configuration Planning Checklist Table 32. Configuration planning checklist Configuration Components Steps 1. Security 1. Determine mapping to existing roles in the solution. 2. Determine if additional roles must be added. 3. Identify the users or groups that should be added to each solution role. Determine the authors, reviewers, coordinators, managers, and so on in each department within your organization. 4. Determine if security configuration needs to be adjusted. 5. Determine if access to creation /administration configurations must be adjusted. 6. Determine if preconditions on menus must be adjusted. 2. Object model Review the Life Sciences standard object model to identify how your organization’s documents and metadata will map to the object model. 261 Configuration Planning Checklist Configuration Components Steps 3. D2 processing Review the following Life Sciences configurations and identify any changes needed for alternate processing (documents and registration forms). • Creation Profiles — Addition or removal of creation profiles — Addition or removal of individual document types within existing creation profiles — Changing the control category for artifacts.Registration forms • Default values • Lifecycles • Workflows • Check in/check out • Rendition requests 4. Artifacts 262 1. Review the Life Sciences set of artifacts and identify any additions or modifications needed. 2. Identify the attributes applicable to the artifact. 3. Identify the scopes applicable to the artifact (some organizations make each artifact scope specific (for example, artifact name (site), artifact name (country)). 4. Identify default templates for each artifact if the artifact is to be created within eTMF (not needed if all documents are created elsewhere and imported). 5. Identify naming conventions if using CDFSetAttribute mechanism for object names (if relying on D2 auto-naming, there Configuration Planning Checklist Configuration Components Steps will be one configuration for all documents. This, needs to be identified as well). 5. Review the procedures and best practices in Chapter 2, Customizing D2-Based Solutions. 263 Configuration Planning Checklist 264 Appendix B Troubleshooting This appendix contains the following topics: • Log Files, page 265 • Enabling Logging, Debugging, and Tracing, page 269 • Connection Issues, page 274 • Missing Icons in the Submission Viewer (Documentum SSV), page 275 Log Files The logs are the combination of D2–specific logs, Life Sciences-specific logs, and the supporting component logs. D2 Log Files D2 logs can be accessed during runtime when using the application. The files can also be accessed during design time when making configuration changes. The list of D2 logs in the Application Server machine are listed in the following table. Table 33. D2 logs on Application Server machine D2 Logs D2 3.1 D2 4.0 D2 4.1, 4.2, 4.5 C:\logs\D2-config .log Y Y Y C:\logs\D2-client .log Y N N C:\logs\D2fs.log N Y N C:\logs\D2.log N Y Y The list of D2 logs in Content Server are listed in the following table. 265 Troubleshooting Table 34. D2 logs on Content Server machine D2 Logs D2 3.1 D2 4.0 D2 4.1, 4.2, 4.5 C:\logs\D2-JMS .log Y Y Y C:\logs\D2-CS.log Y Y Y You can use both D2 Content Server and Application Server logs to troubleshoot many issues, including D2 Configuration-related issues and workflow and lifecycle-related problems. Life Sciences Log Files During the automated installation of the Life Sciences solution, installation log files are created. These logs are available on both Windows and Linux in the <Temp Extracted Installation Package>/<Installation package name>/working/logs folder. The log files for the individual solutions are as follows: • For Documentum eTMF: — LSTMF_dars<date>.log — LSTMF_updateversion<date>.log — LSTMF_populateroles<date>.log — LSTMF_copy_serverlibs.<date>.log — LSTMF_index<date>.log • For Documentum Q&M: — LSQM_dars<date>.log — LSQM_updateversion<date>.log — LSQM_populateroles<date>.log — LSQM_copy_serverlibs.<date>.log — LSQM_index<date>.log • For Documentum R&D: — LSRD_dars<date>.log — LSRD_updateversion<date>.log — LSRD_populateroles<date>.log — LSRD_copy_serverlibs.<date>.log — LSRD_index<date>.log • For Documentum SSV: — LSSSV_dars<date>.log — LSSSV_updateversion<date>.log 266 Troubleshooting — LSSSV_populateroles<date>.log — LSSSV_copy_serverlibs.<date>.log — LSSSV_index<date>.log Underlying Products Log Files You can use the log files for the underlying products, such as Content Transformation Servers, xPlore, Content Server, Thumbnail Server, and Java Method Server, to troubleshoot issues related to Life Sciences. Content Transformation Services The default location of the log file on the Content Transformation Services host is the %CTS_HOME%\logs folder. The Content Transformation Services log files include: • CTS_Log.txt: Contains the errors and exceptions that are specific to the server. • <Plug-In>_Log.txt: Contains individual plug-in-related errors and exceptions. • IMAGE3_log.txt: Contains the errors that are specific to the Image3 plug-in. The Image3 plug-in logs errors when generating storyboards because the PDFStoryBoard plug-in cannot produce images at a resolution higher than 96 dpi. Note: If separate logging is enabled, log files can be found in the %CTS_HOME%\docbases \<docbasename>\config\logs folder. The EMC Documentum Content Transformation Services Administration Guide provides more information about the log files. xPlore You can view indexing, search, content processing service (CPS), and xDB logs in xPlore Administrator. To view a log file: 1. In xPlore Administrator, select an instance and click Logging. 2. Click the tabs for dsearch, cps, cps_daemon, or xdb to view the last part of the log. Indexing and search messages are logged to dsearch. 3. Click Download All Log Files to obtain download links for each log file. The EMC Documentum xPlore Administration and Development Guide provides more information about the log files. 267 Troubleshooting Content Server Content Server logging and tracing provides information about Content Server operations. This logging information and tracing information is recorded in the following files: • Repository log file: Contains information about root server activities. This file is also sometimes referred as the Content Server log file. • Session log files: Contains all information, warning, error, and fatal error messages and, by default, all SQL commands generated from DQL commands. Session log files are stored in the %DOCUMENTUM%\dba\log\hex_repository_id\username ($DOCUMENTUM/dba/log/hex_repository_id/username) directory, where hex_repository_id is the repository ID expressed as a hexadecimal value and username is the user account under which the session is running. The session log name is the session ID. The server creates a separate session log for each new connection. Sessions that are connected to the primary Content Server create their session logs under the primary server. Sessions that are connected to one or more remote Content Servers create their session logs under the remote server(s). Because sessions are assigned using a round-robin method, you must look in both places for session logs. Some features, such as jobs, also record tracing and logging information specific to those features in log files. The EMC Documentum Content Server Administration and Configuration Guide provides more information about the log files. Thumbnail Server The logging feature in Thumbnail Server needs to be activated manually. You can configure Thumbnail Server to log thumbnail requests, which may help you troubleshoot any errors occurring with the Thumbnail Server, such as missing thumbnails. The log file also indicates errors related to invalid or expired tickets. The Thumbnail Server log file, servlet.log, is located in the %DM_HOME%\thumbsrv\container\logs folder. The Documentum Thumbnail Server Release Notes, Installation and Administration Guide provides more information about the log files. Java Method Server The CDF-Methods.jar and TMF-Methods.jar are two JARs that run on the Java Method Server. The server logs errors for these JMS method execution in the server.log file located in the %DM_HOME%\ jboss[version]\server\DctmServer_MethodServer\log\ folder. 268 Troubleshooting Third-Party Log Files You can use the log files for the supported third-party products, such as eDRG, to troubleshoot issues related to these products. eDRG When an eDRG report is generated manually or as a scheduled task, a log file is created and placed in the Temp cabinet in the Life Sciences solution. If the Delt Reporting Agent job is run, the log file is created in the /Temp/jobs/eDRG Agent folder. The eDRG User Guide provides more information about the messages that appears in the log file. Enabling Logging, Debugging, and Tracing You can enable logging for D2, the underlying products, and the third-party products. Configuring Logging for D2 For D2-Client issue: • Use the default Microsoft utility, Debugview to troubleshoot D2 3.1 client-related issues. • To troubleshoot D2-Client-related (4.x) issues, set the trace level to 5 for the Java Console log. • Charles/Fiddler Traces can help in troubleshooting Client-Server or AppServer-Server related issues. For D2-Config related issues: • Refer to the D2-Config.properties file located in the <webapp_root>\WEB-INF\classes folder. • To enable tracing, set logLevel=trace. Restarting the application server should not be required. If the new logLevel trace setting does not take effect, then log in to D2-Config and select Tools > Reload D2 Options. Note that this requires the client URL information to be correctly filled out in D2-Config>Tools>Client URL box, that is, http://<url>/D2-Config. Incorrect/unreachable URLs results in errors being reported in the D2 logs. • An alternative method of enabling debug tracing for D2-Config is through the <webapp_root>\WEB-INF\classes\logback.xml file. • Edit the <level>${logLevel:-warn}</level> and set to the desired logging level such as debug, that is <level>debug</level>. • Reproduce an issue and make sure it is captured in the trace output. 269 Troubleshooting For D2 (4.x client) related issues: • Debug logging should be enabled and captured for both D2 and D2FS (D2FS pertains to 4.0 only). • The Logback.xml file can be found in the <webapp_root>\WEB-INF\classes folder. • To enable tracing, find the <level>xxx</level> tags in the log file and set the value to <level>debug</level>. Changes to the logging level should be picked up automatically within 60 seconds. • Enable Java Console logging (level 5) on the client side through the Java Console window. • Reproduce an issue and make sure problem is captured in the trace output. Configuring Logging for Underlying Products You can configure logging for the underlying products, such as Content Transformation Servers, xPlore, Content Server, Thumbnail Server, and Java Method Server, to troubleshoot issues related to Life Sciences. Content Server For Content Server 6.6 and 6.7, the jboss-log4j.xml for D2 Java Method Server can be found in the <dctm_home>\jboss###\server\DctmServer_MethodServer\deploy\ServerApps .ear\APP-INF\classes folder. To enable tracing, find the <param name=”Threshold” value=”XXXX”/> tag and set the value to DEBUG. For Content Server 6.7 SP1 and above, because of JBOSS changes, certain configuration changes must be made to get proper D2 Java Method Server log information: 1. Delete the jboss-log4j.xml file from the <dctm_home>\jboss###\server\DctmServer _MethodServer\deploy\ServerApps.ear\APP-INF\classes folder. 2. Create a logback.xml file in the <dctm_home>\jboss###\server\DctmServer _MethodServer\deploy\ServerApps.ear folder. You can use the following sample log file to create your log file. 270 Troubleshooting 3. Stop the Documentum JMS Service. 4. Delete the contents of the following folders: • {jBoss Home}/server/DctmServer_MethodServer/log • {jBoss Home}/server/DctmServer_MethodServer/logs • {jBoss Home}/server/DctmServer_MethodServer/tmp • {jBoss Home}/server/DctmServer_MethodServer/work 5. Start the Documentum JMS Service. 6. To enable tracing, in the logback.xml file, find the <level>#####</level> tag and set the value to DEBUG. Changes to the log file are automatically picked up within 60 seconds. If not, restart Java Method Server. Content Transformation Services Separate logging appenders are added to the log4j.properties file for logging the polling and capability caching information. Refer to the following entries in the log4j.properties file: • log4j.category.POLLINGAppender=INFO, POLLINGAppender • log4j.appender.POLLINGAppender=org.apache.log4j.DailyRollingFileAppender • log4j.appender.POLLINGAppender.File=R $C(CTS, PARENT_DIR)\\logs\\Polling_log.txt • log4j.appender.POLLINGAppender.Append=true • log4j.appender.POLLINGAppender.layout=org.apache.log4j.PatternLayout • log4j.appender.POLLINGAppender.layout.ConversionPattern=%d{HH\:mm\:ss,SSS} %10r %5p [%10t] %-20c - %5x %m%n • log4j.appender.POLLINGAppender.DatePattern=’.’yyyy-ww-dd • log4j.category.CAPABILITYAppender=INFO, CAPABILITYAppender 271 Troubleshooting • log4j.appender.CAPABILITYAppender=org.apache.log4j.DailyRollingFileAppender • log4j.appender.CAPABILITYAppender.File= $C(CTS, PARENT_DIR)\\logs\\Capability_log.txt • log4j.appender.CAPABILITYAppender.Append=true • log4j.appender.CAPABILITYAppender.layout=org.apache.log4j.PatternLayout • log4j.appender.CAPABILITYAppender.layout.ConversionPattern=%d{HH\:mm\:ss,SSS} %10r %5p [%10t] %-20c - %5x %m%n • log4j.appender.CAPABILITYAppender.DatePattern=’.’yyyy-ww-dd The log files, Polling_log.txt and Capability_log.txt, corresponding to these appenders contain the logs related to polling and capability caching information respectively. This information is not logged to the main CTS_log.txt file. The log level can be set to DEBUG for more information to be captured in the log file. xPlore Basic logging can be configured for each service in xPlore administrator. Log levels can be set for indexing, search, CPS, xDB, and xPlore administrator. You can log individual packages within these services, for example, the merging activity of xDB. Log levels are saved to indexserverconfig.xml and are applied to all xPlore instances. xPlore uses slf4j (Simple Logging Façade for Java) to perform logging. To set logging for a service: 1. in xPlore Administrator, click System Overview. 2. Click Global Configuration. 3. On the Logging Configuration tab, configure logging for all instances. Open one of the services such as xDB and set levels on individual packages. To customize the instance-level log setting, edit the logback.xml file in each xPlore instance. The logback.xml file is located in the WEB-INF/classes folder for each deployed instance war file. Levels set in logback.xml take precedence over log levels in xPlore Administrator. Note: Logging can slow the system and consume disk space. In a production environment, run the system with minimal logging. Each logger logs a package in xPlore or in your custom code. The logger has an appender that specifies the log file name and location. DSEARCH is the default appender. Other defined appenders in the primary instance logback configuration are XDB, CPS_DAEMON, and CPS. You can add a logger and appender for a specific package in xPlore or your custom code. The following example adds a logger and appender for the package com.mycompany.customindexing: <logger name="com.mycompany.customindexing" additivity="false" level="INFO"> <appender name="CUSTOM" class=" ch.qos.logback.core.rolling.RollingFileAppender"> <file>C:/xPlore/jboss5.1.0/server/DctmServer_PrimaryDsearch/ logs/custom.log </file> <encoder> <pattern>%date %-5level %logger{20} [%thread] %msg%n</pattern> <charset>UTF-8</charset> </encoder> <rollingPolicy class="ch.qos.logback.core.rolling. FixedWindowRollingPolicy"> <maxIndex>100</maxIndex> <fileNamePattern>C:/xPlore/jboss5.1.0/server/DctmServer_ PrimaryDsearch /logs/custom.log.%i</fileNamePattern> 272 Troubleshooting </rollingPolicy> <triggeringPolicy class="ch.qos.logback.core.rolling. SizeBasedTriggeringPolicy"> <maxFileSize>10MB</maxFileSize> </triggeringPolicy> </appender> </logger> You can add custom logger and appender to logback.xml. To capture log entries in the logs in xPlore Administrator, add the custom logger to a logger family, which are defined in indexserverconfig.xml. This is an optional step – if you do not add your custom logger to a logger family, it still logs to the file that you specify in your appender. Logger families are used to group logs in xPlore Administrator. You can set the log level for the family, or expand the family to set levels on individual loggers. The log levels include TRACE, DEBUG, INFO, WARN, and ERROR. The levels are in increasing severity and decreasing amounts of information. Therefore, TRACE displays more than DEBUG, which displays more than INFO. Thumbnail Server To activate thumbnail logging: 1. Log in to the Thumbnail Server host as an administrator. 2. Stop the Thumbnail Server service. 3. Navigate to %DM_HOME%\thumbsrv\container\webapps\thumbsrv\web-inf. 4. Open the web.xml file in any text editor. 5. Change the <debug> flag to TRUE. 6. Save and close the web.xml file. 7. Restart the Thumbnail Server service. Java Method Server To enable logging for CDF and TMF server methods, set the logging level to DEBUG on the Java Method Server by adding the following settings to the log4j.properties file, located in \Documentum\jboss[version]\server\DctmServer_MethodServer\deploy \ServerApps.ear\APP-INF\classes, on Content Server 6.7 SP1 and above: • log4j.logger.com.documentum.d2=INFO • log4j.logger.com.documentum.cdf=DEBUG • log4j.logger.com.documentum.tmf=DEBUG • log4j.logger.com.documentum.ssv=DEBUG • log4j.logger.com.documentum.utils=DEBUG 273 Troubleshooting Life Sciences SDK The log4j logging framework is used in the Life Sciences SDK. The log4j properties can be set for the logs specific to the SDK by setting the log levels. For example: log4j.logger.com.documentum.ws=DEBUG. Configuring Logging for Third-Party Products To troubleshoot issues related to eDRG reports, eDRG logs can be collected by placing the logging.properties file the WEB-INF/classes folder in the eDRG web application and restarting the Application Server. The log levels can be FINE and FINEST. The following code can be added to the log file: handlers = org.apache.juli.FileHandler ############################################################ # Handler specific properties. # Describes specific configuration info for Handlers. ############################################################ org.apache.juli.FileHandler.level = FINE org.apache.juli.FileHandler.directory = ${catalina.base}/logs org.apache.juli.FileHandler.prefix = eDRG. java.util.logging.ConsoleHandler.level = FINE java.util.logging.ConsoleHandler.formatter = java.util.logging.SimpleFormatter Connection Issues The Life Sciences solution suite is a web-based application. If the repository does not appear or other connection issues occur, verify that the required services are running. To start the required services: 1. Log in to the Windows system using the login credentials. 2. Open the Services console. 3. Start the following services in the listed order: a. Documentum Docbroker Service Docbroker b. Documentum Docbase Service LifeSciences c. Documentum Java Method Server d. Apache Tomcat e. 274 EMC Documentum Thumbnail Server Troubleshooting Submission Viewer Timeout Issue (Documentum SSV) When viewing a submission in the Submission Viewer widget, if you try to view the submission after a few minutes, the Viewer does not display the submission. This issue occurs because the Submission Viewer gets timed out after five minutes. The login ticket time-out period can be configured in the Documentum dm_server_config parameters. You can also configure it in the server.ini configuration file on the server. By default, this is set to 5 minutes, but it can be changed. You can also specify the automatic ticket refresh interval used by the Submission Viewer widget by passing a refreshLoginTicketInterval=<n> parameter in the URL in the D2-Config configuration for the Ext SSV Submission Viewer widget, where <n> is the required interval in seconds. By default, n=240s (4 minutes). To prevent the Submission Viewer ticket from timing out, the specified refresh interval <n> should be less than the login ticket time-out value defined in the Documentum server configuration object. Missing Icons in the Submission Viewer (Documentum SSV) If icons are missing for certain file formats in the Submission Viewer, they can be added to the %WEBAPPS%/XMLViewer/icons/format folder as required. The icon files must be named "<format>.gif", where <format> is the Documentum format name identified for the file, as specified in the relevant <leaf> element of the Submission History XML file. Existing format icons can be copied and renamed, if necessary. 275 Troubleshooting 276 Appendix C DIA EDM and TMF Reference Model Dictionaries Table 35. Clinical domain dictionaries Dictionary Name Description Clinical Groups List of values in the Group column on the Clinical domain tab of the DIA EDM reference model spreadsheet. These values are the logical groupings or CTD modules in the Clinical domain. Clinical Subgroups List of values in the Sub-Group column on the Clinical domain tab of the DIA EDM reference model spreadsheet. Within the Clinical domain, categories of documents within a group, usually based on CTD module subsets. Clinical Artifact Names Complete list of Clinical artifacts defined in the Artifact Name column on the Clinical domain tab of the DIA EDM reference model spreadsheet. Clinical Literature References Artifact Names List of artifacts in the Literature References group on the Clinical tab of the DIA EDM reference model spreadsheet. Clinical Report Component Artifact Names List of artifacts defined on the Clinical Report Components tab of the DIA EDM reference model spreadsheet. Clinical Summaries Artifact Names List of artifacts in the Summaries group on the Clinical tab of the DIA EDM reference model spreadsheet. 277 DIA EDM and TMF Reference Model Dictionaries Table 36. Non-Clinical domain dictionaries Dictionary Name Description Non-Clinical Groups List of values in the Group column on the Non-Clinical domain tab of the DIA EDM reference model spreadsheet. These values are the list of logical groupings in the Non-Clinical domain. Non-Clinical Subgroups List of values in the Sub-Group column on the Non-Clinical domain tab of the DIA EDM reference model spreadsheet. Within the Non-Clinical domain, categories of documents within a group, usually based on CTD module subsets. Non-Clinical Artifact Names Complete list of Non-Clinical artifacts defined in the Artifact Name column on the Non-Clinical domain tab of the DIA EDM reference model spreadsheet. Non-Clinical Literature References Artifact Names List of artifacts in the Literature References group on the Non-Clinical tab of the DIA EDM reference model spreadsheet. Non-Clinical Reader Artifact Names Specifies the document types (artifacts) that can be created by end-users in the Non-Clinical area (for example, Change Requests). Note that the user must have client capability set to "Contributor" in their user profile in order to create documents. Non-Clinical Report Component Artifact Names List of artifacts defined on the Non-Clinical Report Components tab of the DIA EDM reference model spreadsheet. Non-Clinical Study Durations List of values that can be selected for the duration of a particular non-clinical study. Non-Clinical Study Management Artifacts List of document types defined on the Non-Clinical tab of the DIA EDM reference model spreadsheet that can be created my members of the Non-Clinical Study Management group. Non-Clinical Study Number Dictionary List of Non-Clinical Study Numbers defined on the Non-Clinical tab of the DIA EDM reference model spreadsheet Non-Clinical Study Types Lists categorizations of non-clinical studies defined on the Non-Clinical tab of the DIA EDM reference model spreadsheet identifying the kind of dosing or kind of assessment being made. 278 DIA EDM and TMF Reference Model Dictionaries Dictionary Name Description Non-Clinical Summaries Artifact Names List of artifacts in the Summaries group on the Non-Clinical tab of the DIA EDM reference model spreadsheet. Non-Clinical Test Facility Locations. List of artifacts in the Non-Clinical group on the Non-Clinical tab of the DIA EDM reference model spreadsheet. It is the list of locations that provide test facilities for non-clinical studies. Table 37. Quality domain dictionaries Dictionary Name Description Quality Groups List of values in the Group column on the Quality domain tab of the DIA EDM reference model spreadsheet. These values are the logical groupings in the Quality domain. Quality Subgroups List of values in the Subgroup column on the Quality domain tab of the DIA EDM reference model spreadsheet. Within the Quality domain, categories of documents within a group. Quality Artifact Names List of values in the Artifact column on the Quality domain tab of the DIA EDM reference model spreadsheet. List the various kinds of documents in the Quality domain. Quality Adventitious Agents Artifact Names List of values in the Artifact column on the Quality domain tab of the DIA EDM reference model spreadsheet. These are the artifact names for Domain: Quality and Group: Adventitious Agents. Quality Drug Product Artifact Names List of values in the Artifact column on the Quality domain tab of the DIA EDM reference model spreadsheet. These are artifact names for Domain: Quality and Group: Drug Product. Quality Drug Substance Artifacts Names List of values in the Artifact column on the Quality domain tab of the DIA EDM reference model spreadsheet. These are artifact names for Domain: Quality and Group: Drug Substance. Quality Facility Artifact Names List of values in the Artifact column on the Quality domain tab of the DIA EDM reference model spreadsheet. These are artifact names for Domain: Quality and Group: Facility. 279 DIA EDM and TMF Reference Model Dictionaries Dictionary Name Description Quality Information Artifact Names List of values in the Artifact column on the Quality domain tab of the DIA EDM reference model spreadsheet. These are artifact names for Domain: Quality and Group: Quality Information. Quality Literature Reference Artifact Names List of values in the Artifact column on the Quality domain tab of the DIA EDM reference model spreadsheet. These are artifact names for Domain: Quality and Group: Literature Reference. Quality Medical Device Artifact Names List of values in the Artifact column on the Quality domain tab of the DIA EDM reference model spreadsheet. These are artifact names for Domain: Quality and Group: Medical Device. Quality Overall Summary Drug Product Artifact Names List of values in the Artifact column on the Quality domain tab of the DIA EDM reference model spreadsheet. These are artifact names for Domain: Quality and Group: Quality Overall Summary Drug Product. Table 38. Regulatory-Admin domain dictionaries Dictionary Name Description Regulatory-Admin Groups List of values in the Group column on the Regulatory Administrative domain tab of the DIA EDM reference model spreadsheet. Regulatory-Admin Subgroups List of values in the Subgroup column on the Regulatory Administrative domain tab of the DIA EDM reference model spreadsheet. Regulatory-Admin Artifact Names List of values in the Artifact Names column on the Regulatory Administrative domain tab of the DIA EDM reference model spreadsheet. Table 39. TMF dictionaries Dictionary Name Description TMF Models Name and version of the TMF reference model that is supported as listed in the DIA TMF reference model spreadsheet. Defines the Trial Master File schemas supported. Each schema (model) can have its own access control rules for trial participants. 280 DIA EDM and TMF Reference Model Dictionaries Dictionary Name Description TMF Zones List of values in the TMF Zone column of the DIA TMF Reference model spreadsheet. TMF Sections List of values in the Section column of the DIA TMF Reference model spreadsheet. TMF Artifact Names List of values in the Artifact name column of the DIA TMF Reference model spreadsheet. TMF Unique Artifact Names List of values in the Alternate name columns of the DIA TMF Reference model spreadsheet. 281 DIA EDM and TMF Reference Model Dictionaries 282 Appendix D Visual Representation of Attribute Cascading in Life Sciences During document creation or import, a document inherits a set of attributes from a corresponding registration form. For example, if you create a non-clinical document, the system requires you to associate the document to a Non-clinical Study Registration Form. The individual document inherits a set of product and study information from the registration form. The following diagrams represent how information is cascaded from the registration forms to the individual documents in each of the solutions. Legend: • TXT — Free Form Text Entry • DQL — DQL-based set used for the drop-down list • DQL-prod — DQL-based set tempered by selected product to be used for the drop-down list • DICT — Dictionary-based set used for the drop-down list • DICT+FREE — Dictionary-based set used for the drop-down list; unlisted values accepted • DICT-DQL-prod — Dictionary-based value set through DQL tempered by the selected product • RO — Read only value; set earlier • DQL-RO — Read-only value set through a DQL query on another field • DQL-Dep — DQL-based set tempered by the first value in the set • DQL-Dep-RO — Read-only value set through DQL tempered by the first value in the set • DQL-Dep-Free — DQL-based set tempered by the first value in the set; unlisted values accepted 283 Visual Representation of Attribute Cascading in Life Sciences Figure 1. Product and Project Registration Form Attributes Figure 2. Cascading of Attributes in the Clinical Domain 284 Visual Representation of Attribute Cascading in Life Sciences Figure 3. Cascading of Attributes in the Non-clinical Domain 285 Visual Representation of Attribute Cascading in Life Sciences Figure 4. Cascading of Attributes in the Regulatory Domain 286 Visual Representation of Attribute Cascading in Life Sciences Figure 5. Cascading of Attributes in the Safety and Quality Domain 287 Visual Representation of Attribute Cascading in Life Sciences 288 Index A bulk import-export, 169 custom reference model creation profile, 83 dictionary, 79 file plan, 83 file plan template, 83 implement, 79 taxonomies, 82 custom roles create, 57 property page, 57 workflow, 57 C D cat 1–3 ownership, 161 CDF security model, 151 change request disable, 184 configure roles Q&M, 58 configuring audit events, 166 D2 mailing configuration, 187 modifying messages, 138 search criteria, 167 configuring roles and permissions external participants, 173 control categories, 48 assign, 159 ownership, 161 control category definition, 88 creation profile, 85 add artifacts, 91 change, 91 customize, 90 new, 90 remove, 92 remove artifacts, 92 D2 configuration migration, 247 configure, 248 install, 247 D2 mailing configuration message configuration, 189 task variables, 188 D2 mailing configurations, 185 D2–based solution, 51 base configuration, 52 base solution contexts, 53 best practices, 56 custom application, 52 extend, 51, 53 merging, 55 team development, 56 data model, 59 debugging enable, 269 default values template, 88 dictionary extend, 74 TMF artifact name, 75 TMF artifact number, 75 TMF section, 74 TMF unique artifact name, 76 TMF zone, 74 display label, 202 access control role-based, 161 adding role example external trial participants, 178 audit events, 166 audit trail, 166 B 289 Index distributed processing enabling, 181 to 182 dm_bpm_XCPAutoTaskMgmt job deactivate, 259 document creation profile, 86 document domains, 18 document permissions external trial participants, 177 document_id, 93 E eCTD, 207 M1 regional XML files, 221 new XML formats, 208 non-standard XML files, 218 regional XML file, 207 standard XML files, 216 xsl style sheet, 208 EDM reference model implementation, 66 eDRG, 32, 37, 41, 47 enabling distributed processing, 181 to 182 eTMF creation profile, 78 custom reference model, 79 file plan, 78 file plan template, 78 standard reference model, 74 events audit, 165 extended attribute expressions, 110 extended base configurations reconcile, 55 solution upgrades, 55 external participants configuring roles and permissions, 173 external trial participants adding role example, 178 define permissions, 177 define roles, 174 user groups, 34 user roles, 33 external user, 252 external users security, 251 F file names, 93 for collaborative editing, 125 H hard delete configure, 167 L Life Sciences fundamental concepts, 17 lifecycle, 141 document, 141 normal states, 149 pseudo states, 149 lifecycle actions custom business logic, 150 lifecycle configuration create, 149 modify, 149 lifecycle state transition uniqueness check, 148 lifecycle states control categories 1–3, 143 control category 4, 143 log files, 265 logging enable, 269 M mailing configurations, 185 management creation profile, 85 N native annotation, 93 NeeS, 231 O O2 configuration, 93 overview, 17 P parallel processing CFD methods, 183 disable, 183 290 Index PDF annotation, 93 performance configurations, 259 performance improvement, 259 permissions, 152 change requests, 155 country and site registration forms, 152 GMP documents, 155 product registration form, 152 R&D documents, 157 registration forms, 157 trial master file document, 152 trial registration form, 152 planning checklist, 261 previewing media files, 185 R reassign roles, 139 recall document, 129 reference model corporate document, 72 general, 72 manufacturing, 72 reference models, 65 registration form, 95 custom types, 97 types, 95 regulatory submissions, 205 roles, 20, 30 administrators, 22 approvers, 22 auditors, 23 authors, 23 contributors, 25 controlled printers, 28 coordinators, 25 custom, 57 extend, 57 external trial participants, 174 global external participants, 29 inspectors, 29 investigators, 29 managers, 27 QO approvers, 26 readers, 26 reviewers, 27 S SDK DFS, 255 Java Client Library, 256 overview, 255 web services integration, 255 search criteria, 167 security, 151 folder, 162 services required, 274 session timeout configuring, 191 solution types add, 62 create, 62 modify, 62 special naming conventions, 116 standard reference model extend, 74 submission filestore, 231 submission history XML file, 208 submit change request for approval, 131 T task performer update, 139 taxonomy extend, 77 TMF artifacts by model, 77 TMF classification by artifact, 77 tmf dynamic access control, 162 external user registration, 163 role-based, 162 TMF access control groups, 252 TMF admin tool, 249 delete, 253 examine, 250 external users, 251 install, 250 purge, 253 refresh, 252 repair, 251 TMF reference model implementation, 71 to be read recipients, 128 tracing 291 Index enable, 269 troubleshooting, 265, 274 U understanding user roles, 30 user groups Clinical, 32 cross functional, 37, 40, 47 cross-functional, 31 external trial participants, 34 quality, 42 Reporting, 32, 37, 41, 47 User groups Regulatory, 43 User Groups Clinical, 41 correspondence, 46 Labeling, 44 Non-clinical, 42 Safety, 43 user roles external trial participants, 33 utility integrity check, 247 migration, 247 V viewer widget URLs configuring, 233 W welcome page, 202 workflow, 123 attributes, 140 configure, 136 diagrams, 124 292 roles, 123 task performer, 138 workflows content template, 136 expiry review (control category 2), 134 for collaborative editing, 125 modifying messages, 138 periodic review (control category 1), 127 recall, 129 submit change request for approval, 131 submit change request for review and approval, 130 submit for approval (control category 1), 126 submit for approval (control category 2), 133 submit for delegated approval (control category 3), 135 submit for review (control category 3), 134 submit for review and approve (control category 1), 125 submit for review and approve (control category 2), 131 submit for review-format approval (control category 2), 132 submit to TBR recipients, 128 withdraw document (control category 1), 128 workspace, 193 mapping, 197 tasks, 193 views, 193 X XML metadata extraction, 224
