Application Deployment System Guide Version 8.0 October 14, 2013 For the most recent version of this document, visit our developer's website.
Table of Contents 1 Application Deployment System 4 1.1 System secured applications 4 2 Getting started with Relativity applications 4 2.1 Creating an application 5 2.2 Configuring an external tab to a Dynamic Object 5 2.2.1 Creating an external tab linking to a Dynamic Object 6 2.3 Application console 6 2.3.1 Manage Application 7 2.3.2 Application Information 8 2.4 Customizing an application 8 2.5 Writing custom code for applications 10 2.6 Deleting an application 11 3 Pleadings sample application 12 3.1 Judge Information tab 12 3.1.1 Add a new judge information record 12 3.2 Pleadings tab 13 3.2.1 Add a new pleading record 13 3.3 Pleadings application objects 14 3.3.1 Fields 14 3.3.2 Choices 15 3.3.3 Views 15 3.3.4 Layouts 15 3.3.5 Tabs 15 4 Installing an application 15 4.1 Install to a workspace 16 4.2 Install to the Application Library in Admin mode 16 4.3 Installing from application library 16 4.4 Importing from external file 19 4.4.1 Importing from an external file 19 4.5 Installing applications in Admin mode 23 4.6 Import status 25 4.7 Resolving errors 26 4.7.1 Locking conflicts 27 4.7.2 Name conflicts 27 Relativity Application Deployment System Guide - 2
4.7.3 Other errors 28 4.8 Common installation errors 28 4.9 Mapping tips 29 5 Exporting an application 29 5.1 Automatic lock and applicationisdirty flag reset on export 30 6 Application errors and validation 31 6.1 Troubleshooting applications 31 6.1.1 Can't export due to unassigned event handlers or agents 32 6.1.2 Can t find assembly for event handler on an object type 33 6.2 Application validation requirements 34 6.2.1 Exportability requirements 35 7 Guidelines for applications 37 7.1 Understanding application versions 37 7.1.1 Setting the application version 37 7.1.2 Application upgrades with versioning 38 7.2 Locking or unlocking an application 39 7.2.1 System secured applications 39 7.2.2 Locking an application 39 7.2.3 Unlocking an application 40 8 Upgrading an application 41 8.1 Steps to upgrade a Relativity application 42 8.2 FAQ - Upgrading applications 42 Relativity Application Deployment System Guide - 3
1 Application Deployment System You can use Relativity's Application Deployment System (ADS) to develop and implement custom solutions for improved case and matter management. Based on the needs of your environment, you can build custom applications to manage tasks and information to support the large-scale review of structured data. The Application Deployment System provides functionality for developing applications in the web interface and managing Relativity applications across workspaces. Relativity application development requires no extensive training or programming knowledge. You can package a collection of any of the following components to build a custom Relativity application: Agents Object types (Fields, Choices, Views, Layouts, and Tabs) Event handlers Object rules Relativity scripts Custom pages If you've already built a basic application and have an idea for adding advanced automation functionality to it, contact kcura Client Services. 1.1 System secured applications Relativity ships with several key features that are developed with the Application Deployment System. These out-of-box features are called system secured applications. You can't modify or edit system secured applications. In Admin mode, the Application Library tab includes these system secured applications: Analytics Fact Manager Processing (requires licensing) Review Manager At the workspace level, the Relativity Applications tab lists the following system secured applications that are shipped with Relativity: Imaging OCR Search Term Report Transform Set 2 Getting started with Relativity applications You can create, customize, and delete applications directly in the web interface. You can also use custom pages to enhance application flexibility by incorporating a specific page or component into your Relativity application. Use the following actions to manage Relativity applications within and across workspaces: Relativity Application Deployment System Guide - 4
Export - saves an application configuration in XML or RAP format to easily import the application into another workspace or Relativity environment. Import - installs an application in another workspace or Relativity environment with an existing application configuration file (XML or RAP). Using Relativity's web interface, install an application to a workspace or to the environment's Application Library. Upgrade - updates an existing application with new or updated objects. 2.1 Creating an application Create custom Relativity applications to perform specialized functions in a workspace. You can configure new objects or link to existing objects for use with your application. To create a new Relativity application: 1. Select the Relativity Applications tab. 2. Click New Relativity Application. 3. In the Application Type section, select the Create a New Relativity Application. 4. Enter the application name in the New Application Name field. 5. (Optional) Type the application version in the Version field. If you don't add a version number, Relativity automatically assigns one on export of an application. See Setting the application version on page 37. Note: Type the application version in the Version field using the format X.X.X (Major.Minor.Build). For example: 1.0.0. 6. In the Tab Display section, select the direction you want child tabs to display below the application's parent tab (Vertical or Horizontal). 7. Click Save. The application configuration page opens. The application configuration page provides access to the Application Console as well as available associative objects, which you can use to customize the application. See Customizing an application on page 8. 2.2 Configuring an external tab to a Dynamic Object You can create external tabs that link to Relativity Dynamic Objects and package them in Relativity applications. You can configure an external tab to link directly to one instance of a Relativity Dynamic Object, bypassing the list view and essentially creating a shortcut tab. This is useful if you only have one instance of that object or if Relativity Application Deployment System Guide - 5
you have a particular instance of the object that is most commonly used. In the latter case, you can create one tab that links to a Relativity Dynamic Object and keep the default object tab to have access to the item list view. 2.2.1 Creating an external tab linking to a Dynamic Object To create an external tab: 1. Select the Tabs tab and click New Tab. The New Tab form appears with required fields in orange and optional fields in gray. 2. In the Name field, enter the name of the tab. The name must be between 1 and 50 characters. 3. In the Order field, enter the numerical position of the tab. Click View Order to display a list of active tabs and their current order. 4. In the Link Type field, select Externalfrom the menu. The Link field displays below the Parent field. 5. Enter the following in the Link field, where [identifier] is the Artifact ID or the GUID of the Dynamic Object. ObjectArtifactIdentifier=[identifier] For example, ObjectArtifactIdentifier=1039242 6. (Optional) From the Parent menu, select a parent workspace tab for this external tab to appear under. 7. From the Is Default menu, select Yes to set this tab as the default when a reviewer logs in; otherwise, select No. 8. (Optional) From the Relativity Applications field, click to associate this tab with an application. 9. Click Save. 2.3 Application console To open the application configuration page, click the name of an application on the Relativity Applications tab. The application configuration page provides access to the Application Console. Relativity Application Deployment System Guide - 6
Note: If application errors exist, Relativity disables Export, Push to Library, and Show Application Breakdown. Click Show Errors to view application error list. 2.3.1 Manage Application The Manage Application section contains the following command options: Upgrade Application - upgrade the application in your workspace. Export Application - save the application in XML or RAP format for use when importing an application into another workspace. If you attempt to export a Single or Multiple Choice field without any linked choices, an alert message appears before you can continue with the export. Lock/Unlock Application - provides the following functionality: o o Lock Application prevents the ability to edit an application configuration and any associative objects of an application. Unlock Application removes the application lock to allow application editing. You can't unlock system secured applications. For more information, see System secured applications on page 4. Locking and unlocking an application requires the Edit security permission under Relativity Application, and the Manage Relativity Applications permission under Admin Operations. Note: To edit workspace permissions, go to Workspaces mode and point to the Administration::Workspace Details tab. Click the Manage Workspace Permissions link in the Relativity Utilities console, and then click Edit Permissions for the group you want to modify. Push To Library - adds an application to the Application Library. After you add the application to the library, you can install it on workspaces throughout your Relativity environment, and you can upload files to it from the Resource Files tab. This button is visible only to Relativity Script Admins when no errors exist in the application. See the Resource files page in the Relativity 8 documentation site. Relativity Application Deployment System Guide - 7
Note: You override any existing applications with the same GUID when you push an application from a workspace to the library. 2.3.2 Application Information The Application Information section contains the following links: Show Application Breakdown - create and view an application configuration summary in HTML format. Visualizations vary per application. Show Errors - displays any application configuration errors that exist. you must resolve all application errors before you can use the export feature. Click the Refresh Page link to refresh the current page. 2.4 Customizing an application You can customize an application with the available associative objects on the application configuration page. To open a Relativity application for customization: 1. In the target workspace, select the Relativity Applications tab. 2. Click the name of the application to be customized. 3. Associative object lists for Relativity applications contain the following options: New - creates a new object and link it to the application. Note: The New button is not available for event handlers, object rules, or agent types. Relativity Application Deployment System Guide - 8
Link - adds existing objects to the application. Objects already linked to an application do not appear in the Select Items pop-up list when you click the Link button. Unlink - removes a selected object from the associative object list. The Link and Unlink buttons will display for the Agent Type associative list only or system administrators. Note: You must unlock the application before adding, linking, and unlinking objects for locked applications. See Locking or unlocking an application on page 39. If you're not a system administrator, you can't link or unlink an agent type from an application. 4. Click New, Link, or Unlink on any of the following associative object lists to add or remove application objects: Object Type (Relativity Applications) - associates object types with the application. There is no New option available for this object. Field (Relativity Applications) - associates fields with the application. Choice (Relativity Applications) - associates choices with the application. View (Relativity Applications) - associates views with the application. Layout (Relativity Applications) - associates layouts with the application. Tab (Relativity Applications) - associates tabs with the application. Event Handler (Relativity Applications) - associates Console, Pre Cascade Delete, Pre Delete, Pre Load, Pre Save, and Post Save event handlers with the application. (Add Pre-Install and Post- Install event handlers to the Install Event Handler list.) There is no New option available for this object. Only those event handlers associated with an object type are available in the selection list. Refer to the Event Handlers Guide for details. Object Rule (Relativity Applications) - associates an object rule with this application. Relativity Script (Relativity Applications) - associates scripts with the application. Custom Page (Relativity Applications) - associates a Custom Page with the application. Agent Type (Relativity Applications) - associates an agent type with the application. There is no New option available for this object. Only system administrators can link or unlink an agent type from an application. See the Agents Guide for more information. Install Event Handler (Relativity Applications) - associates Pre Install or Post Install event handlers, which are run prior to or after the installation of the an application respectively. This list also indicates the order used to execute a series of Pre Install or Post Install event handlers as well as the execution type of each event handler. You can designate the order used to execute the event handlers of each type, such as run the first Post Install event handler then the second one. Relativity Application Deployment System Guide - 9
The execution type determines when the event handler is run in the workspace. Event handlers set to run once are executed when you initially install an application. If the installation fails, these event handlers are re-executed until the application is successfully installed, and then no longer run. Other event handlers run every time the application is installed. Use the New button to add Pre and Post Install event handlers to an application. The Add Install Event Handler pop-up provides you with the ability to select an event handler and to specify the order in which it is run. 4. (Optional) Click Edit to modify the object type settings. 5. Complete the following: Lock the application to prevent additional changes. (Optional) Add the application to the Application Library. You can then install the application on workspaces throughout your Relativity environment, and you can upload files to it from the Resource Files tab. 2.5 Writing custom code for applications The main components of a Relativity application generally include event handlers, custom pages and agents. These components can share common code by using interfaces available in the Relativity.API.dll. The interfaces provided by Relativity.API expose functionality used to interact with database, obtain the Relativity Services URI, retrieve authentication tokens, and perform other operations. In addition, your application should reference the kcura.relativity.client.dll, which contains the ArtifactManagerProxy. All method calls that go through the ArtifactManagerProxy use the Relativity business engine. This proxy communicates with the Relativity Services API, which you can use when developing application code. The Services API ensures backwards compatibility and eliminates errors that may occur when writing direct SQL calls. The component that you are developing determines the.dlls that you need to reference in your Visual Studio project. The following diagram illustrates assemblies referenced when developing event handlers, custom pages and agents. The Relativity.API and kcura.relativity.client assemblies are common to all three components. Relativity Application Deployment System Guide - 10
As a best practice, use GUIDs to reference Artifacts, since ArtifactIDs and Names may change throughout the life of an application. You may want to create a class that contains constants based on the GUIDs of Artifacts (such as Fields, Choices, Object Types, and so on) used in an application. The following code sample illustrates how to develop a class containing these constants. using System; using System.Collections.Generic; using System.Linq; using System.Text; namespace Relativity.Samples.Core { public static class ApplicationConstants { public static readonly Guid OLD_CODING_FIELD_GUID = new Guid("eb174a88-068e-40a9-8835-5f020f80a089"); public static readonly Guid NAME_FIELD_GUID = new Guid("0761E9D6-F775-48BB-91CC-1DB39B2CE9F0"); public static readonly Guid RELATED_DOCUMENT_FIELD_GUID = new Guid ("513B40E6-1FC5-4E59-9191-1C52D66C89AD"); public static readonly Guid CONTAINS_EXTRACTEDTEXT_FIELD_GUID = new Guid ("181724B3-AB4E-4E9F-82B7-6852D7DBFCBE"); public static readonly Guid HAS_IMAGES_FIELD_GUID = new Guid("DB80E2CB- CE37-4813-8AAA-45AE54C8AB7B"); } } 2.6 Deleting an application You can remove an application from a workspace using the Delete button. Note: Before deleting an application, you must unlock it. See Unlocking an application on page 40. Perform the following steps to delete a Relativity application: Relativity Application Deployment System Guide - 11
1. In the target workspace, select the Relativity Applications tab. 2. Click the name of the application to be deleted. 3. Click the Delete button. 4. (Optional) Click the Dependencies button to review the following: Application children to be deleted with application Application associative objects to be unlinked from application Note: Deleting an application does not delete associative objects linked to the application. Associative objects are unlinked upon deletion of an application. 5. Click Delete to confirm deleting the application and application children, and to unlink any associative objects. 3 Pleadings sample application Pleadings is an example application that serves as a file repository for case pleadings and stores additional case details for quick sorting and retrieval. For this example, open and save the RA_Pleadings application file. Next, import the Pleadings application to your workspace. See Importing from external file on page 19. Pleadings adds two new tabs with a new view and layout for each tab, the Judge Information tab and the Pleadings tab. 3.1 Judge Information tab The Judge Information tab allows you to save the following details regarding the judge and clerk for a case using the Judge Information Layout: Name of Judge Name of Clerk City Street Address State Zip Code Phone 3.1.1 Add a new judge information record Complete the following steps to add a new judge information record with the Pleadings application: Relativity Application Deployment System Guide - 12
1. On the RelativityJolly Pumpkin Developers site, download the RA_Pleadings.zip file from the Pleadings sample application page. 2. Select the Pleadings::Judge Information tab. 3. Click New Judge Information button. 4. Enter a value for each field in the Judge Information Layout: a. Judge Lastname, Firstname: Type name of judge in Last name, First name format. b. Clerk Lastname, Firstname: Type name of clerk in Last name, First name format. c. City: Type the name of the city in which the judge presides. d. Street Address: Type the address of the judge. e. State: Select or add the address state. Click Add and complete the New Choice form to add a new State field choice. f. Zip Code: Type the address zip code. g. Phone: Type the phone number for the judge. 5. Save the new Judge Information record. Note: Values saved in the Judge Lastname,Firstname field are available as choices for the Judge Name field in the Pleadings Layout. 3.2 Pleadings tab The Pleadings Tab allows you to enter the following details for a new pleading: Pleading name Date Docket Number Parties Subject Type Attorneys of Record Judge Name Response Action Venue Scanned pleading document 3.2.1 Add a new pleading record Complete the following steps to add a new pleading record with the Pleadings application: 1. Select the Pleadings tab. 2. Click New Pleadings button. 3. Enter a value for each field in the Pleadings Layout: a. Pleading: Type name of pleading. b. Date: Click the ellipsis button and select the pleading date. c. Docket Number: Select or add the docket number(s). Click Add and complete the New Choice form to add a new Docket Number field choice. d. Parties: Select or add the parties. Click Add and complete the New Choice form to add a new Parties field choice. e. Subject: Type the subject of the pleading. Relativity Application Deployment System Guide - 13
f. Type: Select or add the pleading type. Click Add and complete the New Choice form to add a new Type field choice. g. Attorneys of Record: Select or add the attorneys of record. Click Add and complete the New Choice form to add a new Attorneys of Record field choice. h. Judge Name: Click the ellipsis button and select the judge. i. Response Action: Type the response action. j. Venue: Select or add the venue. Click Add and complete the New Choice form to add a new Venue field choice. k. Link to Scanned Doc: Click Browse and select the pleading document. 4. Save the new Pleading record. 3.3 Pleadings application objects Pleadings includes two object types: Pleadings Judge Information The following sections provide a breakdown of all application objects associated with the Pleadings or Judge Information object types. 3.3.1 Fields Field Name Field Type Object Type Artifact ID Whole Number Pleadings Pleading Fixed-Length Text (255) Pleadings Docket Number Multiple Choice Pleadings Venue Single Choice Pleadings Parties Multiple Choice Pleadings Attorneys of Record Multiple Choice Pleadings Subject Fixed-Length Text (255) Pleadings Date Date Pleadings Response Action Long Text Pleadings Type Single Choice Pleadings Judge Name Single Object Pleadings Link to Scanned Doc File Pleadings Link to Scanned Doc File Icon File Pleadings Link to Scanned Doc File Size Whole Number Pleadings Link to Scanned Doc Text Long Text Pleadings Artifact ID Whole Number Judge Information Judge Lastname, Firstname Fixed-Length Text (255) Judge Information Clerk Lastname, Firstname Fixed-Length Text (255) Judge Information Phone Fixed-Length Text (20) Judge Information Street Address Fixed-Length Text (255) Judge Information Relativity Application Deployment System Guide - 14
Field Name Field Type Object Type City Fixed-Length Text (100) Judge Information State Single Choice Judge Information Zip Code Fixed-Length Text (10) Judge Information 3.3.2 Choices Choice Name Field Object Type Electronic Type Pleadings Paper Type Pleadings 3.3.3 Views View Name Object Type All Pleadings Pleadings All Judge Informations Judge Information 3.3.4 Layouts Layout Name Pleadings Layout Judge Information Layout Object Type Pleadings Judge Information 3.3.5 Tabs Tab Name Pleadings Judge Information Object Type Pleadings Judge Information 4 Installing an application Using Relativity's web interface, you can create an application in the workspace or install an existing application. To install an application, you must be a Script Administrator. Depending on how you're going to use the application, you can either install it to a specific workspace or install to Relativity's Application Library. Note: If you don't see three Application Type options, then you don't have Relativity Script Administrator permissions. You need to be added to the Relativity Script Admin group to install an application. For more information, see Security permissions in the Relativity 8 documentation site. Relativity Application Deployment System Guide - 15
4.1 Install to a workspace You can install an application to a workspace by either importing from an external file or installing an application from the Application Library. To install an existing Relativity application, perform the following steps: 1. Select the Relativity Applications tab. 2. Click New Relativity Application. 3. Choose either Select from Application Library or Import from File to import the application from an external file. 4.2 Install to the Application Library in Admin mode To more easily manage application installations across multiple workspaces, you can install an application to the Application Library in Admin mode. To install an application from an external file directly to the Application Library, see Installing applications in Admin mode on page 23. 4.3 Installing from application library If an application is stored in the Application Library in Relativity, you can install it to a workspace using the following steps. Note: Only members of the Relativity Script Admin group can install an application from the Application Library. System Administrators have read/write access to the Application Library but can't import an application. For more information, see Security permissions in the Relativity 8 documentation site. 1. From Workspaces mode, go to the Relativity Applications tab, and click New Relativity Application. 2. In the Application Type section, click the Select from Application Library radio button. A new field, Choose from Application Library, displays. Relativity Application Deployment System Guide - 16
3. To populate the Choose from Application Library field, click. A list of applications stored in the Application Library displays. 4. Select the appropriate application from the list, and click Ok. The application now appears in the Choose from Application Library field. The Version field displays the version of the application being installed. The Application Artifacts section displays the application's object types and other components. If necessary, click Clear to clear the field and select a different application. 5. The Map Fields section allows you to prevent application installation errors by mapping application fields to workspace fields of the same field type. For example, a date field in the application can be mapped only to a date field in the workspace. For field mapping to occur, application fields must have corresponding fields in the workspace. When you attempt to install an application for which no corresponding fields are present, a message appears, alerting you that no fields are available for mapping. Note: When mapping fixed length text fields during Relativity Application import, you can only map the application s fixed length text field to a workspace fixed length text field of equal or lesser length in the field properties. Fields with a higher length aren't displayed in the Workspace Fields section and are thus unavailable for mapping. Relativity Application Deployment System Guide - 17
If there are corresponding fields in the workspace, the Map Fields section displays a field mapping interface. 6. (Optional) Map application fields to workspace fields in the field mapping interface. You can map as many or as few of the available application fields as you want before beginning the installation. a. In the field mapping interface, move items from the Application Fields box at left to the center mapping box by highlighting the field and clicking the right arrow between the two boxes. The Workspace Fields box displays all potential matches in the target workspace for that application field. If no fields in the target workspace match up to the highlighted application field, no fields will appear in the Workspace Fields box. b. Highlight the workspace field and click the left arrow to move it to the center mapping box. To move a field from the mapping box back to the Application Fields box, highlight it and click the left arrow. Note: You can also move fields from one box to another by double-clicking the field name. Relativity Application Deployment System Guide - 18
7. Click Import to save the selection and import the application. The import process begins, and an "Import in progress" message displays. 8. After the import process completes, the import status displays. You can either verify that the install was successful or resolve errors on the fly. 4.4 Importing from external file When you import an external application file to a workspace, the install also affects corresponding installs in the Application Library. If the application has shared components event handlers, scripts, custom pages and/or agents it'll be stored in the Application Library automatically, overwriting any lower versions. 4.4.1 Importing from an external file To install an existing application stored in a file external to Relativity, perform the following steps: Note: Only Script Administrators can install an application from an external file. System Administrators have read/write access to the Application Library but cannot install an application. Relativity Application Deployment System Guide - 19
1. From the Application Type section, click the Import from File radio button. A new field, File, displays. 2. To populate the File field, click Browse. Navigate to the location of the application, then select the application file and click Open. While Relativity loads the file, the message Uploading appears to the right of the field. After the file uploads, a new Clear button displays, giving you the option to remove the application file and populate the field with a different file. Note: If you attempt to install an application that includes a custom page of a restricted file type, an error message will display and you won't be able to install the application. See Configuring custom page restricted file types in the Custom Pages guide. 3. Once the application file is loaded, the Application Information section appears. The Application Name field displays the name of the application, the Version field displays the version of the application being installed, and the File Name field displays the name of the application file. Note: Relativity Applications can be XML files or RAP files. If the file you upload is of a different file type, the error message "The uploaded file is not a valid Relativity Application file" will appear. Below the Application Information section, a new section called Application Artifacts displays. This section identifies the artifacts associated with your application, broken down into Object Types, External Tabs, Scripts, Custom Pages, Agent Types, as well as Pre and Post Install Event Handlers. Expand the hierarchy tabs to view the artifacts associated with each. Relativity Application Deployment System Guide - 20
Below the Application Artifacts section, an additional section called Map Fields displays. You can use field mapping functionality to map application fields to workspace fields of the same field type. For example, a date field in the application can be mapped only to a date field in the workspace. This field mapping process prevents you from encountering errors when installing the application. For field mapping to occur, the application fields must have corresponding fields existing in the workspace. When you attempt to install an application for which no corresponding fields are present, a message appears, alerting you that no fields are available for mapping. If there are corresponding fields in the workspace, the Map Fields section is populated with a field mapping interface. Relativity Application Deployment System Guide - 21
4. (Optional) Map application fields to workspace fields in the field mapping interface. You can map as many or as few of the available application fields as you want before beginning the import. a. In the field mapping interface, move items from the Application Fields box at left to the Mapping box in the middle by highlighting the field and clicking the right arrow between the two boxes. The Workspace Fields box will display all potential matches found in the target workspace for that application field. If no fields in the target workspace match up to the application field you attempted to map, no fields will appear in the Workspace Fields box. b. Highlight the workspace field and click the left arrow to move it to the Mapping box. To remove a field from the Mapping box and place it back in the Application Fields box, highlight and click the left arrow. You can also move fields from one box to another by double-clicking the field name. Relativity Application Deployment System Guide - 22
5. Click Import to save the selection and install the application. The install process begins, and a screen displays with the message "Import in Progress." 6. After the import process completes, the import status displays. You can either verify that the install was successful or resolve errors on the fly. 4.5 Installing applications in Admin mode To more easily manage application installations across multiple workspaces, you can upload an application from an external file to the Application Library in Admin mode. Perform the following steps to upload an external application file to the Application Library. 1. In Admin mode, go to the Application Library tab. 2. Click Upload Application, then click Browse to select the application file. Relativity Application Deployment System Guide - 23
3. Click Save to upload the application to the Application Library. The application is now uploaded to the Application Library, but it's not yet installed to any workspaces. 4. In the Application Library tab, click the name of the application that you want to install to a workspace (s). 5. To install the application to the selected workspaces, click Install. 6. Under Workspaces, click to open the Select Workspaces form. In this form, select the check box for each workspace to which you want to install the application. Select the top check box to install to all workspaces. Click Ok. 7. The names of the selected workspaces now appear under Workspaces. If you've added an incorrect workspace, click Clear to remove the workspace names, and then click Install again to add the correct ones. Click Save to install the application to the selected workspaces. 8. Under Workspaces Installed, you can view the application's installation status for each of the selected workspaces. Relativity Application Deployment System Guide - 24
Potential statuses include the following: Application Install Status Pending... Errors Application out of date. May not work properly. Installation in progress... Installed Description The workspace has been flagged for installation but is not yet installing. To cancel the installation, select the check box next to the workspace name and click Cancel. The install failed due to one or more errors. Click Errors to try to resolve conflicts within Relativity. See Resolving errors on the next page. The version of the application that's installed to this workspace is lower than what's installed to the Application Library. Select the workspace's check box and click Install to upgrade the application in the workspace. The application is currently installing to the workspace; you can no longer cancel the installation. The application has successfully installed to the workspace. Click the Installed link to view the import status details. To install the application to another workspace, click Install again. 4.6 Import status After you install an application on the Relativity Application tab, you can view the status page, which displays immediately after this process completes. The Import Status section indicates whether your installation was successful. If the installation was not successful, the Import Status section indicates that your application failed to install. This message lists the number of errors encountered during the installation. For both successful and failed installations, you can click the Export Status Details link to export the Status section report to a.csv file. Relativity Application Deployment System Guide - 25
Below the Import Status message, an artifact status section displays a list of all the artifacts in your application along with the corresponding Artifact Type, Artifact ID, and the install status for each artifact. If an artifact was installed without errors, the message Updated successfully appears in the Status column. The artifact status section describes each error encountered during the failed install. See Resolving errors below to resolve the installation errors within the Import Status page. Note: You can also view status information for the installation of an application from the Application Library tab in Admin mode. Click on an application to display a detail view, and then click an Installed link to display the status page. 4.7 Resolving errors The import status screen allows you to resolve conflicts on the fly without having to revise the original application or artifacts in the target workspace. The list of errors is organized by error type. For example, an import can encounter Locking Errors, Name Conflicts, or Other Errors. For each error listed, you can view the Artifact Name, Artifact Type, Artifact ID, and the Status of the error. In the artifact status section, you may have the option to resolve an error before retrying the installation. Error resolution options vary according to error type. Relativity Application Deployment System Guide - 26
After specifying a resolution action for all conflicts in the report, click the Retry Import button at the top of the screen to attempt the import again with errors resolved. The Retry Import button is disabled until you resolve all errors. 4.7.1 Locking conflicts If there's a Locking Conflict, select the Unlock check box, and click the Retry Import button to resolve the error(s). This action allows you to temporarily unlock the application to address a conflict resulting from a Locking Error before proceeding with the import. Once the application is imported, it will be locked again. 4.7.2 Name conflicts For Name Conflicts, the Resolve Errors column displays a drop-down menu from which you can select a resolution. To rename an object or field, select Rename from the drop-down menu. This option allows you to rename the item in the target workspace if you encounter a conflicting artifact, which then allows the components of your application to be imported. When you select Rename from the drop-down menu, a field displays to the right. Enter a new name in this field to resolve the Name Conflict error. When you've entered a valid name to resolve the error, a green check mark displays to the right of the new name field. Relativity Application Deployment System Guide - 27
You may also have the option to resolve Name Conflict errors using a Map Field operation from the dropdown. Selecting this option will automatically map the field you're importing to the conflicting field in the target workspace. 4.7.3 Other errors For Other Errors, the Resolve Errors column may display a message that the error can only be resolved manually in the workspace. This means that you must resolve the issue in the target workspace before proceeding with the import. 4.8 Common installation errors Depending on the application you're attempting to install, you may see errors as a result of any of the following situations. These are not all of the possible errors you can receive, only the most common. Possible resolutions to these common errors are listed below. You can perform some of the following manually in the source or target workspace, or you can perform them on the fly through the install process. Cause of Error Application contains duplicate Object Type or field names Application XML file contains a relational field that uses a friendly name already used by a relational field in the target workspace Application contains an Object Type that already exists in the target workspace inside a locked application Possible Resolutions Rename the item in the target workspace Rename the item in the application Remove the item from the application Remove the item from the target workspace Map fields before installing Change the friendly name of the relational field in the target workspace Change the friendly name of the relational field in the application Map fields before installing Unlock the application in the target workspace Remove the object type from the application Application has a malformed XML file Re-export the application and try again Application contains an external resource of a restricted file type Remove the external resource from the application and re-install Relativity Application Deployment System Guide - 28
4.9 Mapping tips When mapping application items, be aware of the following behavior. Renaming an item after it's mapped will have no impact on future upgrades of the application. An application will own the field you map to, and the field in the target workspace will be renamed to whatever it was called in the application. If you remove an item (choice, field, object rule, etc.) from an application in Workspace A, export the application and then import it again to Workspace B, the items on Workspace B are left intact, including the field that's no longer part of the imported application. If you rename a field in an application on Workspace A, export the application, and then import it into Workspace B, the field will be renamed on Workspace B (with the exception of Document System Fields.) 5 Exporting an application The Export Application operation allows you to save an application for the purpose of importing or upgrading the application in another workspace. Applications are exported as either XML or RAP files. Applications that do not contain any external resources, such as custom pages, are exported in XML format. The XML application format is supported for import into all versions of Relativity. Applications that contain external resources are exported as RAP files. The RAP application format is supported for import into Relativity version 7.4 or higher. Perform the following steps to export a Relativity application: 1. In the target workspace, select the Relativity Applications tab. 2. Click the name of the application to be exported. 3. Click Export Application in the Application Console. Relativity Application Deployment System Guide - 29
Note: If you didn't assign a version number to your application, Relativity automatically assigns a version number on export of an application. See Setting the application version on page 37. When you click Export Application, the application is checked for external resources, such as custom pages. If no external resources exist, the export process runs without interruption, and the application is exported as an XML file. If any external resources are present, the following dialog displays, alerting you that the application will be exported as a RAP file. Click Export to export the application in RAP format. 4. Save the application file when prompted by your web browser. Note: Opening the file when prompted by your web browser doesn't automatically save the exported application configuration settings. Click Save or Save As instead of Open and download the application file to a specific location. 5. Click the Refresh Page link in the Application Console. 5.1 Automatic lock and applicationisdirty flag reset on export Upon exporting an application, Relativity automatically changes two settings related to the state of an application: Lock state applicationisdirty flag If an application is unlocked at the time of export, the export operation automatically locks the application. To unlock an application, click Unlock Application in the Application Console. See Locking or unlocking an application on page 39. If an application was ever unlocked and the applicationisdirty flag was set to True, the export operation automatically resets applicationisdirty back to False. The value of False for the applicationisdirty flag indicates the application is in a clean, unedited state. In an upgrade scenario, the applicationisdirty flag is referenced to help determine the type of upgrade installation required for an application in a workspace. See Setting the application version on page 37. Relativity Application Deployment System Guide - 30
6 Application errors and validation In order to export an application, it must satisfy Relativity's Application validation requirements on page 34. If application validation errors exist, Relativity enables the Show Errors link and disables the Export Application button and the Show Application Breakdown link in the Application Console. Click Show Errors to open the Errors window: Application validation error messages listed in the Errors list are based on application validation requirements. 6.1 Troubleshooting applications Use the following troubleshooting information to resolve issues associated with applications. Relativity Application Deployment System Guide - 31
6.1.1 Can't export due to unassigned event handlers or agents When you attempt to export your application, you receive the following error message: Event Handler XXXX is not assigned to the correct application domain. Agent YYYY is not assigned to the correct application domain. Install Event Handler ZZZZ is not assigned to the correct application domain. This error occurs when the assemblies referencing these objects are loaded for the wrong application in ResourceFile table. Complete the following steps to resolve this issue: 1. On the Relativity Applications tab in your workspace, click the application name. 2. Complete the following tasks on the detail view of the application: Install Event Handler section - delete the event handler from application. Agent Type section - unlink the agent from the application. Event Handler section - unlink the event handler from the application. Object Type section - click the Edit link for the object associated with event handler. Navigate to the detail view of the object type, select the event handler, and click Delete. 3. In Admin mode, select the Resource Files tab. 4. Complete these steps for the agent and each event handler: a. Click the Edit link for the.dll that contains that contains the event handler, install event handler, or agent that you want in your application. b. On the detail view, click the file name to download the.dll file. c. On the Resource Files tab, click New Resource File. d. Click Browse to select the.dll that you downloaded. e. Click to select your application. (If you don't see your application listed, use the listed Push to Library button on the detail view of the application to add it to Application Library.) f. On the Relativity Application tab in your workspace, click on the name of your application. g. Add the event handler, install event handler, or agent to your application. Verify that the your application name is associated with the.dll that you selected. Relativity Application Deployment System Guide - 32
6.1.2 Can t find assembly for event handler on an object type Your application runs but it throws an error when attempting to access an object that is attached to an event handler. The stack trace indicates that the assembly for the event handler can t be found. This error occurs when the assembly associated with an event handler isn t linked to the application. Complete the following steps to resolve this issue: 1. In your workspace, select the Object Type tab. 2. Click the name of the object type associated with the event handler in error. 3. On the details view, note the name of the.dll file. 4. Select the Relativity Applications tab. 5. Click the name of your application. Relativity Application Deployment System Guide - 33
6. On the details view, scroll down to the Event Handler section. 7. Verify that the Application Name column displays the correct information. Perform one of the following tasks: Application name matches - unlink the event handler. Next, select the correct event handler for your application. The assembly is available in this case, but it points to the wrong application. (If you don't see the event handler listed for your application listed, you may need to add the application to the Application Library. See Application console on page 6.) You should now be able to run the application without errors. Missing assembly - continue with step 8. 8. In Admin mode, select the Resource Files tab. 9. Filter on the application name to locate the correct assembly. Perform one of the following tasks: Missing assembly - add the assembly as a resource file. (Click New Resource File to select the.dll and application that you want to associate with it. For more information, see the Resource files page on the Relativity 8 documentation site.) You should now be able to run the application without errors. Correct assembly and application - The database reference to the assembly may be incorrect. Continue with step 10. 10. Run the following script on the case database to identify event handlers that you may need to relink: SELECT DISTINCT AssemblyArtifactID, ResourceFile.ApplicationGuid FROM ActiveSyncs INNER JOIN EDDS.eddsdbo.ResourceFile ON ActiveSyncs.AssemblyArtifactID = ResourceFile.ArtifactID WHERE ActiveSyncs.ApplicationGuid <> ResourceFile.ApplicationGuid 11. To relink event handlers, run the following statement on the query results from step 10: UPDATE ActiveSyncs SET ApplicationGuid = # ApplicationGuid # WHERE AssemblyArtifactID = # AssemblyArtifactID # 6.2 Application validation requirements A Relativity application is considered valid if all Fields, Scripts, Layouts, Views, Object Types, Object Rules, Choices, Event Handlers, and Tabs are exportable. Failure to meet any of the following validation requirements causes application errors and disables the Export Application button in the Application console. Relativity Application Deployment System Guide - 34
6.2.1 Exportability requirements Review the following exportability requirements to troubleshoot application validation errors. Note: Agent types, custom pages, and Relativity scripts are always exportable from Relativity. 6.2.1.1 Choices Choices are considered exportable if all of these conditions are met: The Object Type owning the choice is included in the application. The Field owning the choice is included in the application. A child/nested choice has its parent choice in the application. 6.2.1.2 Event handlers Event handlers are considered exportable if all of these conditions are met: The Object Type of the Event Handler must be included in the application. 6.2.1.3 Fields Fields are considered exportable if all of the following conditions are met: The Object Type owning the field is included in the application. Single/Multiple Object fields have their Associated Object Type included in the application or one of the following: o o o o o Field Search Search Index Production Object Type Fields with a filter type of popup picker with a specific view (any view other than <All Items>) have the view included in the application. Single/Multiple Object Fields included in the Field Tree with a specific view (any view other than <All Items>) have the view included in the application. Document System fields are not exportable. If you attempt to export a Single or Multiple Choice field where no choices are included, you will receive a message stating, The application contains the choice <Name of Choice> but does not contain of its choices. Do you want to continue exporting? Click Ok to continue with the export. 6.2.1.4 Layouts Layouts are considered exportable if all of these conditions are met: The Object Type owning the layout is included in the application. All fields included in the layout are included in the application. Views referenced by Associative or Child lists are included in the application. Views references by popup picker fields must be included in the application. 6.2.1.5 Object rules Object rules are considered exportable if all of these conditions are met: Relativity Application Deployment System Guide - 35
The Object Type of the Object Rule must be included in the application. All Layouts associated with the Object Rule must be included in the application. All single choice fields associated with the Object Rule must be included in the application. All choices associated with the Object Rule must be included in the application. All Layouts referenced by Object Rules must be included in the application. All Choice Fields referenced by Object Rules must be included in the application. All Choices referenced by Object Rules must be included in the application. 6.2.1.6 Object types Object types are considered exportable if all of these conditions are met: A child object type must have its parent object type included in the application (or have a parent of Document or Workspace). 6.2.1.7 Tabs Tabs are considered exportable if all of these conditions are met: Parent tabs are not exportable. Object Type tabs must have their associated object type included in the application. External tabs are exportable, but the URL associated with them may become invalid upon importing. Use at your own risk. Note: If you previously built an application with a parent tab, upgrading to Relativity 6.10 or higher will automatically remove that tab for you. Note the following rules regarding tab behavior during initial installation and upgrades: On first-time install, if no tab exists in the workspace with the name of the application you are installing, all tabs in the application are placed under a tab named after the application. On first-time install, if a tab exists in the workspace with the name of the application you are installing, all tabs in the application are placed under that existing tab. On upgrade, if a tab already exists with the name of the application you are installing, new tabs will go under it. On upgrade, if a tab with the name of the application you are installing does not exist and all original application tabs are spread across multiple parent tabs or live on the root level, a new tab is created with the name of the application you are installing. 6.2.1.8 Views Views are considered exportable if all of these conditions are met: The Object Type owning the view is included in the application or is Document. All fields included in the view are included in the application. Indented List views are exportable. Field, Search, Search Index, Production, and Object Type views do not require any fields to be included in the application. For Choice conditions, the specific choice used in the condition is included in the application. Only the following view conditions are supported when exporting applications: o o Choice Currency Relativity Application Deployment System Guide - 36
You can either set the version number for each Relativity application, or you can leave the Version field blank to allow Relativity to automatically set the version number for an application. Set the application version with the following steps: 1. Select the Relativity Applications tab in your workspace. 2. Click the application name to open your application. 3. Click Edit. 4. Set the application version number in the Version field. 5. Click Save. Note: If an application version number already exists when you edit the Version field value, the new application version number must be greater than the current version. 7.1.1.1 Version format Relativity Applications requires the following version number format for all applications: Major.Minor.Build.Revision o Example: 2.0.0.0 It Edit mode, The Version field exposes the Major, Minor, and Build version number fields. Relativity automatically increments the Revision number field during an application Export operation if any modifications were made to the application since the last export. 7.1.1.2 Automatic version assignment If an application does not have a version number assigned, Relativity Applications automatically assigns a version number. The default application version number is 0.0.0.1. 7.1.1.3 Automatic revision increment The export operation automatically increments the revision number for an application version number. Each time you export an application in one of the following scenarios, the revision number increases by one. For example: 0.0.0.1 to 0.0.0.2: Application has been unlocked since the last export Application is new and being exported for the first time 7.1.2 Application upgrades with versioning In order to determine the type of installation required to properly upgrade an application that currently exists in a workspace, Relativity verifies the following and performs a full or incremental installation accordingly during an upgrade: Unlocked state: Is the target application currently unlocked? o If the target application is unlocked at the point the upgrade takes place, the application is in an unknown state. This scenario requires a full installation of the application. applicationisdirty state: Has the application been unlocked since the last upgrade? o Relativity sets the applicationisdirty flag to True for an application anytime it is unlocked. Even if an application is locked after being unlocked, the application state is considered unknown. This scenario requires a full installation of the application. Relativity Application Deployment System Guide - 38
Matching Origin: Does the version of the application being installed originate from the same source workspace as the current target application? o If the origin of the application being installed does not match the origin of the application that exists in the target workspace (mismatching Origin Signatures), a full installation of the application is performed. Versions: Is the application being installed assigned a version number greater than the target application version? o If the following conditions are true, an incremental application upgrade is performed. An incremental upgrade only installs the new or modified application objects and removes objects that no longer exist in the application. Target application has not been unlocked Source workspace from which the application originates matches in both applications (in the application being installed and the target application) Version number of the application being installed is greater than the version of the target application The application version being installed had objects added, modified, or removed. 7.2 Locking or unlocking an application By locking or unlocking an application, you can control the ability to edit its associative objects and other components. The console on the Relativity Application tab displays the Lock Application and Unlock Application buttons that you can use to perform these operations. You must be a Relativity system administrator or have Manage Relativity Applications permissions to lock or unlock an application. 7.2.1 System secured applications You don't have the option to lock or unlock system secured applications that are shipped with Relativity The Relativity Application tab doesn't display the Lock and Unlock buttons in the console for the following applications: Analytics Assisted Review Imaging Method 2.1 OCR Processing Search Term Report Transform Set 7.2.2 Locking an application A locked application can't be modified or edited from anywhere within Relativity. If you attempt to edit a locked application or its associative objects, an error message is displayed on the Edit and Create pages for the following items: Choice Field Relativity Application Deployment System Guide - 39
Layout Object Type Relativity Script Tab View Use these steps to lock a Relativity application: Note: An unlocked application is automatically locked on export. See Exporting an application on page 29. 1. In the target workspace, select the Relativity Applications tab. 2. Click the name of the application that you want to locked. 3. Click the Lock Application in the Application Console. 7.2.3 Unlocking an application You can edit an unlocked application. When an application is unlocked, the applicationisdirty property on the RelativityApplication object is set to True. This setting indicates that the application has been opened and may be in an unknown state. The applicationisdirty property is referenced to determine the type of upgrade installation is required for an application in a workspace. See Understanding application versions on page 37. Use these steps to unlock a Relativity application: 1. In the target workspace, select the Relativity Applications tab. 2. Click the name of the application that you want to unlock. Relativity Application Deployment System Guide - 40
3. Click Unlock Application in the Application Console. 4. Click OK on the confirmation message. After the application is unlocked, you can modify the application and its components. 8 Upgrading an application You can upgrade an existing application to a new version through the Relativity Applications tab. To upgrade an application, you must be a member of the Relativity Script Admins group. Some Relativity applications are pre-populated with instances of objects types used to store settings, which you can modify to control application functionality. Upgrading the application resets these instances, so any modifications made to them are lost. As a best practice, create new instances of these object types in your application instead of modifying the default settings. For example, you might create a new profile with your custom settings in the Imaging application. You can avoid resetting instances of object types by developing applications that use Post Install event handlers set to run only once. Using these event handlers, you can create instances of objects and set default values on them during the initial application installation, but not on subsequent upgrades. See the Post Install event handlers information in the Event Handlers guide. Relativity Application Deployment System Guide - 41