Relativity Scripts Guide - Relativity Developer Documentation

Transcript

Scripts Guide Version 8.0 | October 14, 2013 For the most recent version of this document, visit our developer's website. Table of Contents 1 Script development 1.1 Using scripts in Relativity 2 Creating a new script 4 4 4 2.1 Admin mode 5 2.2 Workspace mode 5 3 Script properties 5 3.1 script 8 3.2 name 9 3.3 category 9 3.4 description 10 3.5 key 11 3.6 security 11 3.6.1 acl 12 3.7 action 13 3.8 version 14 3.9 display 15 3.9.1 settings 3.10 input 15 16 3.10.1 constant 17 3.10.2 sql 18 3.10.3 fields 20 3.10.4 Hierarchy 22 3.10.5 Syntax 22 3.10.6 Type Values 22 3.10.7 Hierarchy 23 3.10.8 Syntax 23 3.10.9 Category Values 23 3.10.10 Example 23 3.10.11 search 24 3.10.12 searchprovider 25 3.10.13 object 27 4 Guidelines for Relativity scripts 28 4.1 Relativity Script Admins 28 4.2 Avoiding errors and performance issues 28 Relativity | Scripts Guide - 2 4.3 Scripts and upgrades 29 4.4 Support 29 Relativity | Scripts Guide - 3 1 Script development You can use custom scripts to extend Relativity functionality and modify data sets in workspaces. For example, you can develop scripts to generate custom reports, auto-populate fields, or reformat data based on predetermined parameters. To create a Relativity script, you use a defined set of inputs to turn a basic XML document into a SQL script. This allows you to manipulate data in Relativity without needing direct access to the SQL Server. See Script properties on the next page. Relativity scripts are powerful. Therefore, only Relativity and SQL experts who are familiar with XML should create, test, maintain, or alter them. 1.1 Using scripts in Relativity In Relativity, scripts are Relativity artifacts. This means they are securable and eligible for auditing, just like fields and views. In the Scripts tab in Workspaces mode, you can select from the following script options: n n Create New Workspace Script - allows a Script Administrator to create and edit their own environment and workspace scripts in the Scripts tab. Select from Script Library - allows any user with rights to add scripts to the workspace to choose from the predefined set of scripts in the Relativity Script Library. If you add a script to a workspace from the library, then the workspace points to the library script. Any changes to the library script are automatically reflected in the workspace . Note: For more information on running a library script, see the Admin Manual. n Relativity Applications - associates the script with an application created on the Relativity Applications tab. All existing applications are available when you click . This option is available only to users who have the Manage Relativity Applications permission under Admin Operations. For information on applications, see the Applications guide. 2 Creating a new script If you're a Script Administrator, you can create and edit scripts in Relativity. Before creating a script, it's important to read the script formatting section. Due to the complexity and impact a script can have, only expert users of Relativity and SQL should create scripts. You can create a script in either Admin mode or Workspace mode. Relativity | Scripts Guide - 4 2.1 Admin mode In Admin mode, the script is stored in the Relativity Script Library. Any changes made to the library script are reflected in every workspace that points to the script. To create a new script from Admin mode, perform the following steps: 1. 2. 3. 4. Select the Relativity Script Library tab. Click the New Relativity Script button. Enter your script into the Script Body box. Click Save. The script will now be available under the Relativity Script Library tab. To run the script, click the script's name. In the script information screen, click the Run Script button in the Script console. 2.2 Workspace mode When adding the script code directly to a workspace, a copy of the script exists only in the workspace. To create a new script from Workspace mode, perform the following steps: 1. 2. 3. 4. Select the Script tab. Choose the Create New Workspace Script option (default). Enter your script into the Script Body box. Click Save. The script will now be available under the Scripts tab. To run the script from the Scripts tab, click the Run link next to the script name. Note: The script information is populated by the properties entered within the body of the XML. See Script properties below for more details. 3 Script properties Properties are the metadata XML tag attributes used to populate the script information, including the name, description, category, and version. Enter any of these metadata values directly into your XML script. If you don't give a value to the property, it's blank. Relativity | Scripts Guide - 5 The following table lists the available script properties. For complete documentation, see Script properties on the Relativity 8 developers site. Name description key security    acl Type element element element element element element element       id       typeartifactid       typeartifactguid       type action    timeout    returns    displaywarning    allowhtmltagsinoutput attribute attribute attribute attribute element attribute attribute attribute attribute    name attribute version display element element    settings element Relativity | Scripts Guide - 6 Description the top XML element in the Relativity script body. names (and populates the Name column of) the script. helps you define the script type. used to populate the description column of the script. a key is a mechanism used to lock a script within Relativity. enables you to reference the current user ACL lists in your scripts. pulls back a list of ACL ID's for the current user based on the attributes values so you can reference them inside a script. the ID for the field you want to reference inside the Relativity script. the Artifact ID for the object type that the ACL ID's are referencing. the Artifact Guid for the object that the ACL ID's are referencing. the permission type for the ACL ID's. pulls back more than one data table from SQL. defines how long the script can run. defines how query results are returned. allows a pop-up warning message to appear when running the script. allows HTML tags to be interpreted by the browser instead of rendered as markup. the name used to reference the scripts in the item list drop-down as well as to populate the subreport header when displayed as a report. tracks the internal script version. gives you a place holder to add child attributes like "Assembly", which gives you the ability to add attributes to the overall script. defines certain attributes about your report. Currently you can define Name Type    type attribute input element    orientation attribute    constant element       id attribute       name attribute       type       option attribute attribute       required attribute    sql       id       name    fields       id element attribute attribute element attribute       name attribute       filters          type          category element element element    search       id element attribute       name attribute    searchprovider       id element attribute       name attribute Relativity | Scripts Guide - 7 Description reporttitle. declares what data type the output should be when the script is executed. allows you to define the orientation of your report as well as define various attributes about your report. allows you to determine how the Relativity script's run page's layout renders. Valid values: values (either static or user input) that get passed into the SQL action section. defines how the field or constant is referenced in the script's SQL action section. defines how the field or constant appears to the user when the Relativity script runs. determines what sorts of input field(s) render on the script run screen. limits the available inputs of the constant to the list of options specified. Its entry in the input section is rendered as a drop-down list. the acceptable values for this attribute are true and false. If not set, the script interprets it as true. If the input is marked as required, its input section field is rendered as required. populates a drop-down with the return value of an inline SQL statement. defines how the field is referenced in the SQL action section of the script. defines how the field appears to the user when the Relativity script runs. allows you to reference Relativity case fields. determines how the field is referenced in the SQL action section of the script. determines how the field appears to the user when the Relativity script runs. the types of fields in the drop-down are designated by a filter. defines which Relativity field types appear in the drop-down. allows you to narrow the field type to a sub-set, based on a specific attribute. populates a drop-down list of saved searches in the inputs section. determines how the field is referenced in the SQL action section of the script. determines how the field appears to the user when the Relativity script runs. populates a drop-down list of search providers in the case. determines how the field is referenced in the SQL action section of the script. determines how the field appears to the user when the Relativity script runs. Name    object       id       name       required       typeartifactid       rdoviewartifactid       displaytype       typeartifactguid       rdoviewartifactguid Type Description element populates the specified display type with the current instances of the specified object type. attribute determines how the field is referenced in the SQL action section of the script. attribute determines how the field appears to the user when the Relativity script runs. attribute controls whether or not the object field is required for the script to run. attribute the Artifact ID of the object field that you want to use inside of the Relativity script attribute the Artifact ID of the view for the object field that you want to appear inside the Relativity script. attribute controls how the object renders inside the Relativity script. attribute specifies the object type's Artifact GUID. attribute specifies the view's Artifact GUID. 3.1 script The top XML element in the Relativity script body. 3.1.0.1 Hierarchy n script 3.1.0.2 Syntax 3.1.0.3 Child elements These child elements are the metadata XML tags used to populate the script information, such as name, version, category, etc. Enter any required properties directly into your XML script. If you don't give a value to the property, it displays blank. Name action category description input key name Description the parent of all the attributes listed below. You can use this multiple times to pull back more than one data table from SQL. the is used to populate the description column of the script. the value is used to populate the description column of the script. defines the constants and fields, which are then submitted to the SQL action. a mechanism used to lock a script within Relativity. the value is used to name (and populate the Name column of) the script Relativity | Scripts Guide - 8 Name display Description gives you a place holder to add child attributes like Assembly, which give you the ability to add attributes for the overall script. the value is used to track the internal script version. sets up the acl values that are pulled to be used as tokens in scripts. version security 3.1.0.4 Example 3.2 name The value between these tags is used to name (and populate the Name column of) the script. 3.2.0.1 Hierarchy n script n name 3.2.0.2 Syntax 3.3 category Categories are text fields on the Relativity script object that can help you define the script type. You can also create your own categories. Relativity | Scripts Guide - 9 3.3.0.1 Hierarchy n script n category 3.3.0.2 Syntax 3.3.0.3 Default categories By default, all Relativity library scripts have one of the following: n n n n Environment Optimization scripts allow you to monitor and maintain the performance of your environment. Case Optimization scripts allow you to monitor and maintain the performance of your workspace. Case Functionality scripts perform functions against a specific workspace. For example, flag or populate a new field. Billing scripts perform administrative tasks providing statistics on your Relativity environment. 3.3.0.4 Example 3.4 description The value between these tags is used to populate the description column of the script. 3.4.0.1 Hierarchy n script n description Relativity | Scripts Guide - 10 3.4.0.2 Syntax 3.5 key A key is a mechanism used to lock a script within Relativity. If a script has an associated key tag, then it will be locked. You can preview a locked script, but you can't modify it in any way regardless of your permissions. Once a script has been locked, it's no longer possible to edit it. On upgrade to a new version of Relativity, the installer may attempt to deploy new scripts in your Relativity environment. Any new scripts with a higher version and the same key as those in your current instance may be overwritten. 3.5.0.1 Hierarchy n script n key 3.5.0.2 Syntax 3.5.0.3 Editing a locked script If you want to edit a locked script, preview the script and copy the body. Make your required edits then paste the body into a new script. Make sure you remove the key before saving if you want the script to be editable. 3.6 security This element enables you to reference the current user ACL lists in your scripts. 3.6.0.1 Hierarchy n script n security 3.6.0.2 Syntax 3.6.0.3 Child elements Name acl Description represents a single list of ACL ID's that are able to be referenced in a script. Relativity | Scripts Guide - 11 3.6.0.4 Example 3.6.1 acl This tag pulls back a list of ACL ID's for the current user based on the attributes values so they can be referenced inside of a script. Hierarchy n script n security n acl Syntax Attributes Name id typeartifactid typeartifactguid type Description Data Type the ID for the field you want to reference inside the Relativity string script. the Artifact ID for the object type that the ACL ID's are refstring erencing. the Artifact Guid for the object that the ACL ID's are refstring erencing. the permission type for the ACL ID's. Accepted values: string n n n Required yes no no yes View Edit Delete Note: You have to specify either the artifact guide or the artifact ID of the object type in order for the list to return correctly. Relativity | Scripts Guide - 12 3.7 action You can use this tag multiple times to pull back more than one data table from SQL. 3.7.0.1 Hierarchy n script n action 3.7.0.2 Syntax 3.7.0.3 Attributes Name Description Required defines how long the script can run. Data Type string timeout The value is in seconds It's possible to enter "indefinite", which allows the script to run for an indefinite period of time. defines how query results are returned. returns string yes no n n status returns the number of rows affected by the query. n table returns the output of the query in tabular form. displaywarning If set to "true", allows a pop-up warning message to appear when running the script. By default, this is set to "true" if not included. allowhtmltagsinoutput if set to "true", allows HTML tags to be interpreted by the browser instead of rendered as markup. name the name used to reference the scripts in the item list dropdown as well as to populate the subreport header when displayed as a report. n Relativity | Scripts Guide - 13 boolean no boolean no string no 3.7.0.4 Referencing inputs The body of an action is a SQL script that allows you to pass in inputs. Inputs are referenced in the body of the action by wrapping their ID values in # symbols. 3.7.0.5 Example When the following script runs, it replaces #dateReviewedField# with the actual column name of the field picked in the "Date Reviewed Field" drop-down. In addition, #dateReviewed# is replaced with the contents of the "Date Reviewed" field in the run page. Relativity inserts a CDATA tag. A CDATA tag is a token in XML that indicates anything following it up to the ]]> token is to be interpreted as unformatted text. This is important because, in SQL, the inequality operator is <>, which is an empty entity in an XML document. If you use <>, the resulting script would be invalid. This also means that you don't have to escape characters in that text block such as &. 3.8 version The value between these tags is used to track the internal script version. 3.8.0.1 Hierarchy n script n version Relativity | Scripts Guide - 14 3.8.0.2 Syntax 3.9 display The display element gives you a place holder to add child attributes like "Assembly", which gives you the ability to add attributes to the overall script. 3.9.0.1 Hierarchy n script n display 3.9.0.2 Syntax 3.10.0.3 Attributes Name Description orientation allows you to determine how the Relativity script's run page's layout renders. Valid values: n n Data Type string Required no vertical horizontal 3.10.0.4 Children Name constant Description values (either static or user input) that get passed into the SQL action section. Relativity | Scripts Guide - 16 Name sql fields search Description if used, populates a drop-down with the return value of an inline SQL statement. allows you to reference Relativity case fields. if used, populates a drop-down list of saved searches in the inputs section. The selected search is then converted into the FROM clause of its respective saved search. if used, populates a drop-down list of search providers in the case. The selected value is converted into the selected search provider's ID. if used, populates the specified display type with the current instances of the specified object type. searchprovider object 3.10.1 constant Constants are values (either static or user input) that get passed into the SQL action section. Each constant in the input is entered using XML and contains three main parts. For an example, see Example on the next page. Hierarchy n script n input n constant Syntax List item 1 List item 2 3.10.2 sql This tag, if used, populated a drop-down with the return value of an inline SQL statement. Relativity | Scripts Guide - 18 Hierarchy n script n input n sql Syntax Attributes Name id name Description Data Type defines how the field is referenced in the SQL action section of string the script. defines how the field appears to the user when the Relativity string script runs. Required yes yes Input The inputs are the same ID and name tags consistent with other input types. The contents of the SQL tag should be an SQL statement that returns at least two columns; one has to be named Display and the other has to be named ID. When this input appears on the run page, a drop-down list type of field is created. The drop-down display value is whatever resides in the Display column and the behind-the-scenes value is whatever is populated in the ID column. Example SELECT Display = [Name], ID = [ArtifactID] FROM [View] Relativity | Scripts Guide - 19 3.10.3 fields This tag allows you to reference Relativity case fields. Hierarchy script n n input n field Syntax Attributes Name Description id determines how the field is referenced in the SQL action section of the script. determines how the field appears to the user when the Relativ- string ity script runs. name Data Type string Required yes yes Children Name filters Description the types of fields in the drop-down are designated by a filter. This allows you to easily select the correct case field. Remark The field input allows you to reference the Relativity work space fields. Each field input must be assigned a name and an ID attribute. Each field in the input is entered using XML. It contains two attributes and a filter sub-element. Example 5 6 Relativity | Scripts Guide - 20 0 1 4 0 4 0 3.10.3.1 filters In addition to the id and name, each field input has a filters sub-section, and each filter is defined by a code. When a script is run, Relativity presents the input fields as drop-downs. The types of fields in the drop-down are designated by a filter. This allows the user to easily select the correct case field. If a value is not specified, the tag automatically defaults to zero. Hierarchy n script n input n fields n filters Syntax 3.10.6 Type Values Filter ID 0 1 2 3 4 5 6 7 8 9 10 11 12 13 Field Type Fixed-Length Text Whole Number Date Yes/No Long Text Single-Choice List Decimal Currency Multiple-Choice List File Object User LayoutText Objects Relativity | Scripts Guide - 22 category This element allows you to narrow the field type to a sub-set based on a specific attribute. 3.10.7 Hierarchy n script n input n fields n filters n category 3.10.8 Syntax 3.10.9 Category Values Filter ID 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 Field Category Generic FullText Identifier Associative Comments Relational ProductionMarker AutoCreate FolderName FileInfo ParentArtifact MarkupSetMarker GenericSystem MultiReflected Batch 3.10.10 Example The following example demonstrates the use of field ID filter codes. Relativity | Scripts Guide - 23 0 3 3.10.11 search This tag, if used, populates a drop-down list of saved searches in the inputs section. The selected search is then converted into the FROM clause of its respective saved search. Hierarchy n script n input n search Syntax Attributes Name Description id determines how the field is referenced in the SQL action section of the script. determines how the field appears to the user when the Relativ- string ity script runs. name Data Type string Required yes yes Input The search input allows you to enter a drop-down list of saved searches. Each search input must be assigned a search ID and name. Example When run, a drop-down contains a list of all saved searches in the system. In Relativity, all saved searches get turned in SQL statements and those SQL statement are run to retrieve document results. When you select a saved search in the input, the replace value in the scripts turns into the FROM clause in the generated SQL associated with the search. 3.10.12 searchprovider This tag, if used, populates a drop-down list of search providers in the case. The selected value is converted into the selected search provider's ID. Relativity | Scripts Guide - 25 Hierarchy n script n input n searchprovider Syntax Attributes Name Description id determines how the field is referenced in the SQL action section of the script. determines how the field appears to the user when the Relativ- string ity script runs. name Data Type string Required yes yes Input The search provider input allows you to enter a drop-down list of search providers in the workspace. Each search provider input must be assigned a search provider ID and name. Example This is displayed in the inputs section as another drop-down list, but this one contains a list of all the available search provider artifacts in the system. When one is selected, its return value is the Artifact ID of that selected search provider. This is then used to populate an existing suite of SQL-based functions that interface with dtSearch and Analytics: Relativity | Scripts Guide - 26 3.10.13 object This tag, if used, populates the specified display type with the current instances of the specified object type. Hierarchy n script n input n object Syntax