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
<script>
<!-- children -->
</script>
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
<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 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
<script>
<!-- string value -->
</script>
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
<configuration>
<!-- string value -->
</configuration>
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
<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 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
<description>
<!-- string value -->
</description>
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
<key>
<!-- string value -->
</key>
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
<security>
<!--child elements -->
</security>
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
<security>
<acl id="" typeartifactid="" type="" />
</security>
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
<acl
id = string
typeartifactid= string
typeartifactguid= string
type = string
/>
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
<action reportname = string
timeout = string
returns = string
displaywarning = bool
allowhtmltagsinoutput = bool
name = string
sourceflag = string>
<!-- children -->
</action>
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 &.
<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 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
<version>
<!-- string value -->
</version>
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
<display type = string
assembly = string>
<!-- children –->
</display>
3.9.0.3 Attributes
Name
type
Description
Data
Type
declares what data type the output should be when the script string
is executed. Valid values:
n
n
n
Required
yes
Report - outputs data as a DevExpress report
Table - outputs data as a standard item list
ItemList - outputs data as a standard item list
3.9.0.4 Children
Name
settings
Description
defines certain attributes about your report. Currently you can define the report
title.
3.9.1 settings
This tag defines certain attributes about your report. Currently you can define the report title.
Relativity | Scripts Guide - 15
Hierarchy
n
script
n
display
n
settings
Syntax
<settings reporttitle= string>
</settings>
Attributes
Name
reporttitle
Description
defines the title of the report that appears in the report header when the script is
rendered as a report. If nothing is defined, Relativity uses the script name instead.
3.10 input
This tag allows you to define the orientation of your report as well as define various attributes about your
report.
3.10.0.1 Hierarchy
n
script
n
input
3.10.0.2 Syntax
<input>
<!-- children -->
</input>
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
<constant id = string
name = string
type = string
required = bool>
<!-- children – >
</constant>
Attributes
Name
Description
id
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 string
Relativity script runs.
name
Relativity | Scripts Guide - 17
Data
Type
string
Required
yes
yes
Name
type
Description
Data
Type
determines what sorts of input field(s) render on the script run string
screen. The available types are:
n
n
n
n
n
Required
yes
Date
Datetime
Text
User
Number
Precision - the digit count of a number
Scale - the digit count of the numbers to the right
of a decimal
the acceptable values for this attribute are true and false. If not Boolean no
set, the script interprets it as true. If the input is marked as
required, its input section field is rendered as required.
o
o
required
Children
Name
option
Description
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.
Example
<input>
<!-- Field input goes here -->
<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 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
<sql id = string
name = string>
</sql>
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
<input>
<sql id="one" name="two">
SELECT
Display = [Name],
ID = [ArtifactID]
FROM
[View]
</sql>
</input>
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
<field id = string
name = string>
<!-- children -->
</field>
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
<input>
<field id="ProductionName" name="Production:">
<filters>
<type>5</type>
<category>6</category>
Relativity | Scripts Guide - 20
</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 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
<filters>
<!-- children –->
</filters>
Children
Name
type
category
Description
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.
Example
<field id="ProductionName" name="ProductionName">
<filters>
<category>6</category>
Relativity | Scripts Guide - 21
<type>5</type>
</filters>
</field>
type
This tag defines which Relativity field types appear in the filters drop-down.
3.10.4 Hierarchy
n
script
n
input
n
fields
n
filters
n
type
3.10.5 Syntax
<type>
<!-- integer value -->
</type>
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 <not in use in Relativity>
Object <not in use in Relativity>
User
LayoutText <do not use>
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
<category>
<!-- integer value -->
</category>
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
<not in use>
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
<field id="DuplicateIndicator" name="Duplicate Indicator">
<filters>
<category>0</category>
<type>3</type>
</filters>
</field>
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
<search id = string
name = string>
</search>
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
<script>
<name>Sample Saved Search</name>
<description>Used to demonstrate how saved searches are used in
RelativityScript </description>
<category>Sample</category>
Relativity | Scripts Guide - 24
<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 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
<searchprovider id = string
name = string>
</searchprovider>
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
<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 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
<object id = string
name = string
required = bool
typeartifactid = integer
rdoviewartifactid = integer
displaytype = string
typeartifactguid = string
rdoviewartifactguid = string />
Relativity | Scripts Guide - 27
Attributes
Name
displaytype
Data
Type
determines how the field is referenced in the SQL action sec- string
tion of the script.
determines how the field appears to the user when the
string
Relativity script runs.
controls whether or not the object field is required for the
boolean
script to run.
the Artifact ID of the object field that you want to use inside integer
of the Relativity script
the Artifact ID of the view for the object field that you want integer
to appear inside the Relativity script.
controls how the object renders inside the Relativity script: string
typeartifactguid
rdoviewartifactguid
dropdown
checkboxlist
n radiobutton
n singlepicker
n multipicker
specifies the object type's Artifact GUID.
specifies the view's Artifact GUID.
id
name
required
typeartifactid
rdoviewartifactid
Description
Required
yes
yes
no
no
no
yes
n
n
string
string
no
no
Note: You have to specify either the Artifact GUID or the Artifact ID of the view and object type for the field
to render successfully.
4 Guidelines for Relativity scripts
Relativity scripts are a powerful way to extend Relativity. Because of this, they can cause problems if used
incorrectly. This section outlines some of those potential problems and how to avoid them.
4.1 Relativity Script Admins
We 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 more
information about script permissions, see Security permissions on the Relativity 8 documentation site.
4.2 Avoiding errors and performance issues
Any statement that can be written in SQL can be written into a Relativity script. In theory, you could create a
script that completely erases your workspace's document table.
Relativity | Scripts Guide - 28
In addition, some scripts can negatively impact system performance if run during peak hours.
You can avoid these problems by:
n
n
n
Allowing only experts to write scripts
Allowing only experts to run scripts
Testing scripts in test workspaces only, not in those being used for an actual case
4.3 Scripts and upgrades
kCura occasionally makes changes to the database schema. Accordingly, not all scripts work on all versions of
Relativity. 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 Server
Management Studio. If the script fails, it will throw an error message and attempt to identify the problem. If it
succeeds, it will either advise you how many 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 the
production environment.
4.4 Support
kCura Client Services is available to assist with any questions, comments, or concerns. You can contact Client
Services at [email protected].
kCura offers Relativity Infrastructure Training. We recommend that your script writer attend this training to
ensure they understand the Relativity architecture. See Relativity Training.
Relativity | Scripts Guide - 29
Proprietary Rights
This documentation (“Documentation”) and the software to which it relates (“Software”) belongs to kCura
Corporation and/or kCura’s third party software vendors. kCura grants written license agreements which
contain restrictions. All parties accessing the Documentation or Software must: respect proprietary rights of
kCura and third parties; comply with your organization’s license agreement, including but not limited to
license restrictions on use, copying, modifications, reverse engineering, and derivative products; and refrain
from any misuse or misappropriation of this Documentation or Software in whole or in part. The Software and
Documentation is protected by the Copyright Act of 1976, as amended, and the Software code is protected
by the Illinois Trade Secrets Act. Violations can involve substantial civil liabilities, exemplary damages, and
criminal penalties, including fines and possible imprisonment.
©2013. kCura Corporation. All rights reserved. Relativity® and kCura® are registered trademarks of kCura
Corporation.
Relativity | Scripts Guide - 30