Relativity Scripts Guide · Relativity|ScriptsGuide-2 TableofContents 1Scriptdevelopment 4...

Scripts GuideVersion 8.0 | October 14, 2013

For the most recent version of this document, visit our developer's website.

http://kcura.com/relativity/Portals/0/Documents/8.0 Developers Site/index.htm#Relativity Platform/Home.htm

Relativity | Scripts Guide - 2

Table of Contents

1 Script development 4

1.1 Using scripts in Relativity 4

2 Creating a new script 4

2.1 Admin mode 5

2.2Workspacemode 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 15

3.10 input 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


4.3 Scripts and upgrades 29

4.4 Support 29


1 Script developmentYou can use custom scripts to extend Relativity functionality and modify data sets in workspaces. Forexample, you can develop scripts to generate custom reports, auto-populate fields, or reformat data basedon 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 Scriptproperties on the next page.Relativity scripts are powerful. Therefore, only Relativity and SQL experts who are familiar with XML shouldcreate, test, maintain, or alter them.

1.1 Using scripts in RelativityIn Relativity, scripts are Relativity artifacts. This means they are securable and eligible for auditing, just likefields and views. In the Scripts tab in Workspaces mode, you can select from the following script options:

n Create New Workspace Script - allows a Script Administrator to create and edit their own environmentand workspace scripts in the Scripts tab.

n Select from Script Library - allows any user with rights to add scripts to the workspace to choose fromthe predefined set of scripts in the Relativity Script Library. If you add a script to a workspace from thelibrary, then the workspace points to the library script. Any changes to the library script are auto-matically 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 whohave theManage Relativity Applications permission under Admin Operations. For information onapplications, see the Applications guide.

2 Creating a new scriptIf you're a Script Administrator, you can create and edit scripts in Relativity. Before creating a script, it'simportant to read the script formatting section. Due to the complexity and impact a script can have, onlyexpert users of Relativity and SQL should create scripts.You can create a script in either Admin mode orWorkspacemode.


2.1 Admin modeIn Admin mode, the script is stored in the Relativity Script Library. Any changes made to the library script arereflected in every workspace that points to the script.To create a new script from Adminmode, perform the following steps:

1. Select the Relativity Script Library tab.2. Click theNew Relativity Script button.3. Enter your script into the Script Body box.4. Click Save.

The script will now be available under the Relativity Script Library tab. To run the script, click the script'sname. In the script information screen, click the Run Script button in the Script console.

2.2 Workspace modeWhen adding the script code directly to a workspace, a copy of the script exists only in the workspace.To create a new script fromWorkspacemode, perform the following steps:

1. Select the Script tab.2. Choose the Create New Workspace Script option (default).3. Enter your script into the Script Body box.4. Click Save.

The script will now be available under the Scripts tab. To run the script from the Scripts tab, click the Run linknext to the script name.

Note: The script information is populated by the properties entered within the body of the XML. See Scriptproperties below for more details.

3 Script propertiesProperties are themetadata XML tag attributes used to populate the script information, including the name,description, category, and version. Enter any of thesemetadata values directly into your XML script. If youdon't give a value to the property, it's blank.


The following table lists the available script properties. For complete documentation, see Script properties onthe Relativity 8 developers site.

Name Type Descriptionelement the top XML element in the Relativity script body.element names (and populates the Name column of) the script.element helps you define the script type.

description element used to populate the description column of the script.key element a key is a mechanism used to lock a script within Relativity.security element enables you to reference the current user ACL lists in your scripts. acl element pulls back a list of ACL ID's for the current user based on the attributes val-

ues so you can reference them inside a script. id attribute the ID for the field you want to reference inside the Relativity script. typeartifactid attribute the Artifact ID for the object type that the ACL ID's are referencing. typeartifactguid attribute the Artifact Guid for the object that the ACL ID's are referencing. type attribute the permission type for the ACL ID's.action element pulls back more than one data table from SQL. timeout attribute defines how long the script can run. returns attribute defines how query results are returned. displaywarning attribute allows a pop-up warning message to appear when running the script. allowhtmltagsinoutput attribute allows HTML tags to be interpreted by the browser instead of rendered

as markup. name attribute 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.version element tracks the internal script version.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. settings element defines certain attributes about your report. Currently you can define


Name Type Descriptionreporttitle.

type attribute declares what data type the output should be when the script isexecuted.

input element allows you to define the orientation of your report as well as define vari-ous attributes about your report.

orientation attribute allows you to determine how the Relativity script's run page's layoutrenders. Valid values:

constant element values (either static or user input) that get passed into the SQL action sec-tion.

id attribute defines how the field or constant is referenced in the script's SQL actionsection.

name attribute defines how the field or constant appears to the user when the Relativityscript runs.

type attribute determines what sorts of input field(s) render on the script run screen. option attribute 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. required attribute 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 sec-tion field is rendered as required.

sql element populates a drop-down with the return value of an inline SQL statement. id attribute defines how the field is referenced in the SQL action section of the script. name attribute defines how the field appears to the user when the Relativity script runs. fields element allows you to reference Relativity case fields. id attribute determines how the field is referenced in the SQL action section of the

script. name attribute determines how the field appears to the user when the Relativity script

runs. filters element the types of fields in the drop-down are designated by a filter. type element defines which Relativity field types appear in the drop-down. category element allows you to narrow the field type to a sub-set, based on a specific attrib-

ute. search element populates a drop-down list of saved searches in the inputs section. id attribute determines how the field is referenced in the SQL action section of the


runs. searchprovider element populates a drop-down list of search providers in the case. id attribute determines how the field is referenced in the SQL action section of the


runs.


Name Type Description object element populates the specified display type with the current instances of the spe-

cified object type. id attribute determines how the field is referenced in the SQL action section of the


runs. required attribute controls whether or not the object field is required for the script to run. typeartifactid attribute the Artifact ID of the object field that you want to use inside of the Relativ-

ity script rdoviewartifactid attribute the Artifact ID of the view for the object field that you want to appear

inside the Relativity script. displaytype attribute controls how the object renders inside the Relativity script. typeartifactguid attribute specifies the object type's Artifact GUID. rdoviewartifactguid attribute specifies the view's Artifact GUID.

3.1 scriptThe top XML element in the Relativity script body.

3.1.0.1 Hierarchyn script

3.1.0.2 Syntax

<script>

</script>

3.1.0.3 Child elementsThese child elements are themetadata 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 tothe property, it displays blank.

Name Descriptionaction the parent of all the attributes listed below. You can use this multiple times to pull

back more than one data table from SQL.category the is used to populate the description column of the script.description the value is used to populate the description column of the script.input defines the constants and fields, which are then submitted to the SQL action.key a mechanism used to lock a script within Relativity.name the value is used to name (and populate the Name column of) the script


Name Descriptiondisplay gives you a place holder to add child attributes like Assembly, which give you the

ability to add attributes for the overall script.version the value is used to track the internal script version.security sets up the acl values that are pulled to be used as tokens in scripts.

3.1.0.4 Example

<script><name></name><description></description><category></category><input></input><output></output><version></version><key></key>

<security></security><action returns="table">

<![CDATA[

]]></action>

</script>

3.2 nameThe value between these tags is used to name (and populate the Name column of) the script.


n name

3.2.0.2 Syntax

<script>

</script>

3.3 categoryCategories are text fields on the Relativity script object that can help you define the script type. You can alsocreate your own categories.



n category

3.3.0.2 Syntax

<configuration>



</configuration>

3.3.0.3 Default categoriesBy default, all Relativity library scripts have one of the following:

n Environment Optimization scripts allow you to monitor and maintain the performance of yourenvironment.

n Case Optimization scripts allow you to monitor and maintain the performance of your workspace.n Case Functionality scripts perform functions against a specific workspace. For example, flag or

populate a new field.n Billing scripts perform administrative tasks providing statistics on your Relativity environment.

3.3.0.4 Example

<script>

<name>Category Example</name>

<description></description>

<category>test</category>

<input></input>

<version></version>

<action returns="table">

<![CDATA[

Select Top 10 * from artifact

]]>

</action>

</script>

3.4 descriptionThe value between these tags is used to populate the description column of the script.


n description


3.4.0.2 Syntax

<description>

</description>

3.5 keyA key is a mechanism used to lock a script within Relativity. If a script has an associated key tag, then it will belocked. 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, theinstaller may attempt to deploy new scripts in your Relativity environment. Any new scripts with a higherversion and the same key as those in your current instancemay be overwritten.


n key

3.5.0.2 Syntax<key>

</key>

3.5.0.3 Editing a locked scriptIf you want to edit a locked script, preview the script and copy the body. Make your required edits then pastethe body into a new script. Make sure you remove the key before saving if you want the script to be editable.

3.6 securityThis element enables you to reference the current user ACL lists in your scripts.


n security

3.6.0.2 Syntax

<security>

</security>

3.6.0.3 Child elements

Name Descriptionacl represents a single list of ACL ID's that are able to be referenced in a script.


3.6.0.4 Example

<security><acl id="" typeartifactid="" type="" />

</security>

3.6.1 aclThis tag pulls back a list of ACL ID's for the current user based on the attributes values so they can bereferenced inside of a script.

Hierarchy

n scriptn security

n acl

Syntax

<aclid = stringtypeartifactid= stringtypeartifactguid= stringtype = string

/>

Attributes

Name Description DataType

Required

id the ID for the field you want to reference inside the Relativityscript.

string yes

typeartifactid the Artifact ID for the object type that the ACL ID's are ref-erencing.

string no

typeartifactguid the Artifact Guid for the object that the ACL ID's are ref-erencing.

string no

type the permission type for the ACL ID's. Accepted values:n Viewn Editn Delete

string yes

Note: You have to specify either the artifact guide or the artifact ID of the object type in order for the list toreturn correctly.


3.7 actionYou can use this tag multiple times to pull back more than one data table from SQL.


n action

3.7.0.2 Syntax

<action reportname = stringtimeout = stringreturns = stringdisplaywarning = boolallowhtmltagsinoutput = bool

name = stringsourceflag = string>



</action>

3.7.0.3 Attributes


Required

timeout defines how long the script can run.n The value is in secondsn It's possible to enter "indefinite", which allows the

script to run for an indefinite period of time.

string no

returns defines how query results are returned.n status returns the number of rows affected by the

query.n table returns the output of the query in tabular form.

string yes

displaywarning If set to "true", allows a pop-up warning message to appearwhen running the script. By default, this is set to "true" if notincluded.

boolean no

allowhtmltagsinoutput if set to "true", allows HTML tags to be interpreted by thebrowser instead of rendered as markup.

boolean no

name the name used to reference the scripts in the item list drop-down as well as to populate the subreport header when dis-played as a report.

string no


3.7.0.4 Referencing inputsThe body of an action is a SQL script that allows you to pass in inputs. Inputs are referenced in the body of theaction by wrapping their ID values in # symbols.

3.7.0.5 ExampleWhen the following script runs, it replaces #dateReviewedField# with the actual column name of the fieldpicked in the "Date Reviewed Field" drop-down. In addition, #dateReviewed# is replaced with the contents ofthe "Date Reviewed" field in the run page. Relativity inserts a CDATA tag. A CDATA tag is a token in XML thatindicates anything following it up to the ]]> token is to be interpreted as unformatted text. This is importantbecause, 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 textblock such as &.

<script><name>Update Script</name><input>

<constant id="dateReviewed" name="Date Reviewed" type="date"/><field id="dateReviewedField" name="Date Reviewed Field">

<filters><category>0</category><type>2</type>

</filters></field>

</input>

<action returns="status" name="Update Script" sourceFlag="sql"><![CDATA[

UPDATE[Document]

SET[#dateReviewedField#] = '#dateReviewed#'

]]></action></script>

3.8 versionThe value between these tags is used to track the internal script version.


n version


3.8.0.2 Syntax

<version>

</version>

3.9 displayThe display element gives you a place holder to add child attributes like "Assembly", which gives you theability to add attributes to the overall script.


n display

3.9.0.2 Syntax

<display type = stringassembly = string>

</input>

3.10.0.3 Attributes


Required

orientation allows you to determine how the Relativity script's run page'slayout renders. Valid values:

n verticaln horizontal

string no

3.10.0.4 Children

Name Descriptionconstant values (either static or user input) that get passed into the SQL action section.


Name Descriptionsql if used, populates a drop-down with the return value of an inline SQL statement.fields allows you to reference Relativity case fields.search 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 savedsearch.

searchprovider if used, populates a drop-down list of search providers in the case. The selectedvalue is converted into the selected search provider's ID.

object if used, populates the specified display type with the current instances of the spe-cified object type.

3.10.1 constantConstants are values (either static or user input) that get passed into the SQL action section. Each constant inthe input is entered using XML and contains threemain parts. For an example, see Example on the next page.

Hierarchy

n scriptn input

n constant

Syntax

<constant id = stringname = stringtype = stringrequired = bool>

<constant id="OldVersion" name="Old Version" type="text" required="true"/>

<constant id="NewVersion" name="New Version" type="text" required="true"/>

<constant id="NewVersionList" name="New Version List" type="text" ><option>List item 1</option><option>List item 2</option>

</constant><constant id="UserToVersion" name="Version User" type="user" /><constant id="counter" name="Numeric Counter" type="number" precision="18"scale="2" required="false" /></input>

3.10.2 sqlThis tag, if used, populated a drop-down with the return value of an inline SQL statement.


Hierarchy

n scriptn input

n sql

Syntax

<sql id = stringname = string>

</sql>

Attributes


Required

id defines how the field is referenced in the SQL action section ofthe script.

string yes

name defines how the field appears to the user when the Relativityscript runs.

string yes

Input

The inputs are the same ID and name tags consistent with other input types. The contents of the SQL tagshould be an SQL statement that returns at least two columns; one has to be named Display and the otherhas to be named ID.When this input appears on the run page, a drop-down list type of field is created. The drop-down displayvalue is whatever resides in the Display column and the behind-the-scenes value is whatever is populated inthe ID column.

Example

<input>

<sql id="one" name="two">

SELECTDisplay = [Name],ID = [ArtifactID]

FROM[View]

</sql></input>


3.10.3 fieldsThis tag allows you to reference Relativity case fields.

Hierarchy

n scriptn input

n field

Syntax

<field id = stringname = string>



</field>

Attributes


Required

id determines how the field is referenced in the SQL action sec-tion of the script.

string yes

name determines how the field appears to the user when the Relativ-ity script runs.

string yes

Children

Name Descriptionfilters the types of fields in the drop-down are designated by a filter. This allows you to eas-

ily select the correct case field.

Remark

The field input allows you to reference the Relativity work space fields. Each field input must be assigned aname and an ID attribute.Each field in the input is entered using XML. It contains two attributes and a filter sub-element.

Example

<input><field id="ProductionName" name="Production:"><filters>

<type>5</type><category>6</category>


</filters></field><field id="ParentID" name="Production Parent ID Field:">

<filters><type>0</type><type>1</type><type>4</type><category>0</category>

</filters></field><field id="AttachmentIDs" name="Production Attachment IDs Field:">

<filters><type>4</type><category>0</category>

</filters></field>

3.10.3.1 filtersIn 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-downare 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 scriptn input

n fieldsn filters

Syntax

<filters>

</type>

3.10.6 Type Values

Filter ID Field Type0 Fixed-Length Text1 Whole Number2 Date3 Yes/No4 Long Text5 Single-Choice List6 Decimal7 Currency8 Multiple-Choice List9 File <not in use in Relativity>10 Object <not in use in Relativity>11 User12 LayoutText <do not use>13 Objects


category

This element allows you to narrow the field type to a sub-set based on a specific attribute.

3.10.7 Hierarchyn script

n inputn fields

n filtersn category

3.10.8 Syntax

<category>

</category>

3.10.9 Category Values

Filter ID Field Category0 Generic1 FullText2 Identifier3 Associative4 Comments5 Relational6 ProductionMarker7 AutoCreate8 <not in use>9 FolderName10 FileInfo11 ParentArtifact12 MarkupSetMarker13 GenericSystem14 MultiReflected15 Batch

3.10.10 ExampleThe following example demonstrates the use of field ID filter codes.


<field id="DuplicateIndicator" name="Duplicate Indicator"><filters>

<category>0</category><type>3</type>

</filters></field>

3.10.11 searchThis tag, if used, populates a drop-down list of saved searches in the inputs section. The selected search isthen converted into the FROM clause of its respective saved search.

Hierarchy

n scriptn input

n search

Syntax

<search id = stringname = string>

</search>

Attributes


Required


string yes


string yes

Input

The search input allows you to enter a drop-down list of saved searches. Each search input must be assigned asearch ID and name.

Example

<script><name>Sample Saved Search</name><description>Used to demonstrate how saved searches are used inRelativityScript </description><category>Sample</category>


<input><search id="iSavedSearch" name="Saved Search" />

</input><action returns="table">

<![CDATA[SELECT[Document]. * #iSavedSearch#]]></action>

</script>

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 retrievedocument results. When you select a saved search in the input, the replace value in the scripts turns into theFROM clause in the generated SQL associated with the search.

3.10.12 searchproviderThis tag, if used, populates a drop-down list of search providers in the case. The selected value is convertedinto the selected search provider's ID.


Hierarchy

n scriptn input

n searchprovider

Syntax

<searchprovider id = stringname = string>

</searchprovider>

Attributes


Required


string yes


string yes

Input

The search provider input allows you to enter a drop-down list of search providers in the workspace. Eachsearch provider input must be assigned a search provider ID and name.

Example

<searchprovider id="searchProviderId" name="Name" />

This is displayed in the inputs section as another drop-down list, but this one contains a list of all the availablesearch provider artifacts in the system. When one is selected, its return value is the Artifact ID of that selectedsearch provider. This is then used to populate an existing suite of SQL-based functions that interface withdtSearch and Analytics:


3.10.13 objectThis tag, if used, populates the specified display type with the current instances of the specified object type.

Hierarchy

n scriptn input

n object

Syntax

<object id = stringname = stringrequired = booltypeartifactid = integerrdoviewartifactid = integerdisplaytype = string

typeartifactguid = stringrdoviewartifactguid = string />


Attributes


Required


string yes

name determines how the field appears to the user when theRelativity script runs.

string yes

required controls whether or not the object field is required for thescript to run.

boolean no

typeartifactid the Artifact ID of the object field that you want to use insideof the Relativity script

integer no

rdoviewartifactid the Artifact ID of the view for the object field that you wantto appear inside the Relativity script.

integer no

displaytype controls how the object renders inside the Relativity script:n dropdownn checkboxlistn radiobuttonn singlepickern multipicker

string yes

typeartifactguid specifies the object type's Artifact GUID. string nordoviewartifactguid specifies the view's Artifact GUID. string no

Note: You have to specify either the Artifact GUID or the Artifact ID of the view and object type for the fieldto render successfully.

4 Guidelines for Relativity scriptsRelativity scripts are a powerful way to extend Relativity. Because of this, they can cause problems if usedincorrectly. This section outlines some of those potential problems and how to avoid them.

4.1 Relativity Script AdminsWe recommend that only Relativity and SQL experts who are familiar with XML be in charge of creating,testing, maintaining, and altering Relativity scripts.These users must be System Administrators who are also in the Relativity Script Admins group. For moreinformation about script permissions, see Security permissions on the Relativity 8 documentation site.

4.2 Avoiding errors and performance issuesAny statement that can be written in SQL can be written into a Relativity script. In theory, you could create ascript that completely erases your workspace's document table.


In addition, some scripts can negatively impact system performance if run during peak hours.You can avoid these problems by:

n Allowing only experts to write scriptsn Allowing only experts to run scriptsn Testing scripts in test workspaces only, not in those being used for an actual case

4.3 Scripts and upgradeskCura occasionally makes changes to the database schema. Accordingly, not all scripts work on all versions ofRelativity. If upgrading to a new version, you may need to update your references.To test whether your script references need updating, run the SQL portion of the script in SQL ServerManagement Studio. If the script fails, it will throw an error message and attempt to identify the problem. If itsucceeds, it will either advise you howmany rows were affected or return the rows queried for.If you have a Relativity test instance, deploy the latest version and test your scripts prior to upgrading theproduction environment.

4.4 SupportkCura Client Services is available to assist with any questions, comments, or concerns. You can contact ClientServices at [email protected] offers Relativity Infrastructure Training. We recommend that your script writer attend this training toensure they understand the Relativity architecture. See Relativity Training.

mailto:[email protected]

http://kcura.com/relativity/support/training


Proprietary RightsThis documentation (“Documentation”) and the software to which it relates (“Software”) belongs to kCuraCorporation and/or kCura’s third party software vendors. kCura grants written license agreements whichcontain restrictions. All parties accessing the Documentation or Softwaremust: respect proprietary rights ofkCura and third parties; comply with your organization’s license agreement, including but not limited tolicense restrictions on use, copying, modifications, reverse engineering, and derivative products; and refrainfrom any misuse or misappropriation of this Documentation or Software in whole or in part. The Software andDocumentation is protected by the Copyright Act of 1976, as amended, and the Software code is protectedby the Illinois Trade Secrets Act. Violations can involve substantial civil liabilities, exemplary damages, andcriminal penalties, including fines and possible imprisonment.©2013. kCura Corporation. All rights reserved. Relativity® and kCura® are registered trademarks of kCuraCorporation.

Date post:	08-Aug-2018
Category:	Documents
Upload:	vuanh
View:	223 times
Download:	0 times