Relativity Services API (RSAPI) DTOs have been deprecated and are no longer supported. For more information and alternative APIs, see RSAPI deprecation process.

RelativityScript

Using the Services API, you can execute SQL-based scripts that have been added to workspaces through the Relativity web UI. These scripts extend the functionality of the Services API by working directly with the database to retrieve or modify data for report generation or other purposes. For more information, see Script development.

The Services API supports read and query operations on the RelativityScript DTO, as well as the functionality for executing a script and retrieving its inputs.

To perform operations of the Script DTOs, you must be a member of the Relativity Script Admin and System Administrators groups.

Note: You can also read Relativity scripts using the common DTO ReadSingle method. For more information, see Single-artifact access.

This page contains the following information:

Read a RelativityScript

To read Field values, you can use the Read() method on the RelativityScript repository as illustrated in this code sample.

public static bool Read_RelativityScript_Using_Repository(IRSAPIClient proxy)
{
     // STEP 1: Create a RelativityScript DTO for the RelativityScript that you want to read.
     DTOs.RelativityScript relScriptDTO = new DTOs.RelativityScript(1015032);
     relScriptDTO.Fields = DTOs.FieldValue.AllFields;
      
     // STEP 2: Attempt to read the RelativityScript.
     DTOs.ResultSet<DTOs.RelativityScript> relScriptReadResults = 
          new DTOs.ResultSet<DTOs.RelativityScript>();
      
     try
     {
          relScriptReadResults = proxy.Repositories.RelativityScript.Read(relScriptDTO);
     }
     catch (Exception ex)
     {
          Console.WriteLine("An error occurred reading the Relativity Script: {0}", ex.Message);
          return false;
     }
      
     // STEP 3: Check for success.
     if (!relScriptReadResults.Success)
     {
          Console.WriteLine("An error occurred reading the Relativity Script: {0}", relScriptReadResults.Message);
           
          foreach (DTOs.Result<DTOs.RelativityScript> readResult in relScriptReadResults.Results)
          {
               if (!readResult.Success)
               {
                    Console.WriteLine(" An error occurred in read request: {0}", readResult.Message);
               }
          }
          return false;
     }
      
     relScriptDTO = relScriptReadResults.Results[0].Artifact;
      
     // STEP 4: Retrieve the body as XML and output the name.
     XmlDocument bodyXml = relScriptDTO.Body;
     Console.WriteLine("Successfully read the Relativity Script '{0}'!", relScriptDTO.Name);
      
     return true;
}        

Query for a RelativityScript

This code sample illustrates how to set query conditions, call the Query() method on the RelativityScript repository, and iterate through the result set.

public static bool Query_RelativityScript_Using_Repository(IRSAPIClient proxy)
{
     // STEP 1: Create the query criteria.
     TextCondition nameCondition = new TextCondition(DTOs.RelativityScriptFieldNames.Name, 
          TextConditionEnum.Like, "Billing Statistics");
     DTOs.Query<DTOs.RelativityScript> relScriptQuery = new 
      
     DTOs.Query<DTOs.RelativityScript>
     {
          Condition = nameCondition,
          Fields = DTOs.FieldValue.AllFields
     };
      
     // STEP 2: Attempt to query for the RelativityScript.
     DTOs.QueryResultSet<DTOs.RelativityScript> relScriptQueryResults = null;
     try
     {
          relScriptQueryResults = proxy.Repositories.RelativityScript.Query(relScriptQuery);
     }
     catch (Exception ex)
     {
          Console.WriteLine("An error occurred querying for Relativity Scripts: {0}", ex.Message);
          return false;
     }
      
     // STEP 3: Check for success.
     if (!relScriptQueryResults.Success)
     {
          Console.WriteLine("An error occurred querying for Relativity Scripts: {0}", relScriptQueryResults.Message);
          return false;
     }
      
     // STEP 4: Display the results.
     Console.WriteLine("Number of Relativity Scripts returned: {0}", relScriptQueryResults.Results.Count);
      
     foreach (DTOs.Result<DTOs.RelativityScript> relScriptResult in relScriptQueryResults.Results)
     {
               DTOs.RelativityScript curRelScript = relScriptResult.Artifact;
               Console.WriteLine("Relativity Script Name: {0}", curRelScript.TextIdentifier);
               Console.WriteLine("Relativity Script ArtifactID: {0}", curRelScript.ArtifactID);
     }
      
     return true;
}        

Execute a RelativityScript

You can use the ExecuteRelativityScript() method to run a Relativity script by passing in the script ID, and the script input as a string. (You can perform a query to obtain the script ID.) The ExecuteRelativityScript() method may return a list of Artifacts and Fields, or the status of database rows affected by the script. You must be a member of the System Administrators group to use this method.

The script should be configured with a return type of Table and have an integer column named ArtifactID. For each row in the output table, an Artifact object will be created with the ArtifactID from the ArtifactID column, and a set of Fields will be created for the remaining columns. The column names will be the Field names.

When you execute a Relativity script, you can pass values for input parameters that are defined in the script body. In addition to the standard script properties, the following script called Script for Sample Project includes the input parameter _identifier that is named ControlNumber. See Script development for more information.

<script>
     <name>Script for Sample Project</name>
     <description></description>
     <category></category>
     <input>
          <constant id="_identifier" name="ControlNumber" type="text" />
     </input>
     <action returns="table"><![CDATA[
           SELECT ArtifactID, ControlNumber, ExtractedText FROM [Document]
           WHERE ControlNumber = #_identifier#]]>
     </action>
</script>

The following code sample illustrates how to pass a value for a script parameter when running a script by calling the ExecuteRelativityScript() method on a RelativityScript DTO Repository object.

public static bool ExecuteRelativityScript(IRSAPIClient proxy)
{
     // STEP 1: Query by name for the script that you want to run.
     // Alternatively, if you have the ArtifactID, you can create a 
     // RelativityScript object without querying as exemplified here:
     // DTOs.RelativityScript script = new DTOs.RelativityScript(1036254);
     DTOs.RelativityScript script;
     TextCondition nameCondition = 
          new TextCondition(DTOs.RelativityScriptFieldNames.Name, TextConditionEnum.EqualTo, 
               "Script For Sample Project");
     DTOs.Query<DTOs.RelativityScript> relScriptQuery = new 
      
     DTOs.Query<DTOs.RelativityScript>
     {
          Condition = nameCondition,
          Fields = DTOs.FieldValue.NoFields
     };
      
     try
     {
          DTOs.QueryResultSet<DTOs.RelativityScript> relScriptQueryResults = null;
          relScriptQueryResults = proxy.Repositories.RelativityScript.Query(relScriptQuery);
      
          if (!relScriptQueryResults.Success)
          {
               Console.WriteLine(string.Format("An error occurred finding the script: {0}", 
                    relScriptQueryResults.Message));
               return false;
          }
          script = relScriptQueryResults.Results[0].Artifact;
     }
     catch (Exception ex)
     {
          Console.WriteLine("An error occurred querying for Relativity Scripts: {0}", ex.Message);
          return false;
     }
      
     // STEP 2: Set the input parameter used in the Relativity Script.
     // The following sample Relativity Script contains an input parameter called "ControlNumber":
     // <input>
     //   <constant id="_identifier" name="ControlNumber" type="text" />
     // </input>
      
     RelativityScriptInput input = new RelativityScriptInput("ControlNumber", "AS000005");
     List<RelativityScriptInput> inputList = new List<RelativityScriptInput> { input };
      
     // STEP 3: Call the script.
     RelativityScriptResult scriptResult = null;
     try
     {
          scriptResult = 
               proxy.Repositories.RelativityScript.ExecuteRelativityScript(script, inputList);
     }
     catch (Exception ex)
     {
          Console.WriteLine(string.Format("An error occurred: {0}", ex.Message));
          return false;
     }
      
     //Check for success.
     if (!scriptResult.Success)
     {
          Console.WriteLine(string.Format(scriptResult.Message));
          return false;
     }
     else
     {
          Int32 observedOutput = scriptResult.Count;
          Console.WriteLine(string.Format("Number of documents returned: {0}", observedOutput));
           
          foreach (Artifact art in scriptResult.Artifacts)
          {
               Console.WriteLine(string.Format("{0}: {1}", art.ArtifactID, art.Fields[1].Value));
          }
     }
     return true;
}
        

Retrieve input for a RelativityScript

You can use the GetRelativityScriptInputs() method to retrieve a list of input data for a script. An individual input parameter is represented by an instance of the RelativityScriptInputDetails class. You must be a member of the System Administrators group to use the GetRelativityScriptInputs() method. The following code sample illustrates how to use this method.

public static IList<RelativityScriptInputDetails> GetRelativityScriptInputs(IRSAPIClient proxy)
{
     List<RelativityScriptInputDetails> scriptInputList = null;
     .
     // STEP 1: Using ArtifactID, set the script you want to run.
     DTOs.RelativityScript script = new DTOs.RelativityScript(1036254);
      
     // STEP 2: Call GetRelativityScriptInputs.
     try
     {
          scriptInputList = proxy.Repositories.RelativityScript.GetRelativityScriptInputs(script);
     }
     catch (Exception ex)
     {
          Console.WriteLine(string.Format("An error occurred: {0}", ex.Message));
          return scriptInputList;
     }
      
     // STEP 3: Each RelativityScriptInputDetails object can be used to generate a RelativityScriptInput object, 
     // but this example only displays information about each input.
     foreach (RelativityScriptInputDetails relativityScriptInputDetails in scriptInputList)
     {
          Console.WriteLine("Input Name: {0}\nInput Id: {1}\nInput Type: {2}\nInput Is Required: {3}\n",
          relativityScriptInputDetails.Name,
          relativityScriptInputDetails.Id,
          relativityScriptInputDetails.InputType,
          relativityScriptInputDetails.IsRequired);
     }
      
     return scriptInputList;
}