Auto increment field on object

Note: Some of the recipes listed below now exist as knowledge base articles on the Relativity Community. When you click those links, you must enter valid Community credentials to access those articles. The remaining recipes will soon be integrated into their corresponding feature documentation so that they'll show up either as new topics or new headings within existing topics. Once this relocation is complete, we will be deprecating this home page, and all of the content below will be accessible via search on our sites.

You must have valid Relativity Community credentials in order to download any Community file linked to the documentation site. You'll need to enter those credentials on the Community login screen if you're not already logged in. If you're already logged in to the Community at the time you click a link, the file is automatically downloaded in the bottom left corner of your screen. If you get an error message stating "URL No Longer Exists" after clicking a Community link, it may be due to a single sign-on error related to the SAML Assertion Validator, and you should contact your IT department.

The Auto Increment Field on Object solution calculates and adds an incremental value to a field automatically each time a user creates a new record for an object. This solution is not supported for the document object.

To download the solution files, visit the Relativity Community.

This page contains the following sections:

Before you begin

The Auto Increment Field on Object solution calculates and adds an incremental value to a fixed-length text or long text field automatically each time a user creates a new record for an object. The value uses the format <prefix><padded number>, where prefix is a set of characters that you can optionally specify for the first part of the value. Padded number is the number of digits that you want to pad the second, numeric part of the value with. When you configure the solution, you can also specify the starting value and increment to use when calculating values. To see examples of how the solution calculates values based on various configuration settings, see Creating a configuration record.

Supported versions

This solution is supported in Relativity 8.1 – Server 2021 and RelativityOne.

Solution version Supported Relativity version
2.5.0.2 10.3.287.3 - Server 2021, RelativityOne
2.4.0.2 9.2 - 10.3
2.3 9.2 - 9.7
2.1 8.1 - 9.2

Components

This solution consists of the following components:

  • Event handler
  • Custom object
  • Relativity application

Considerations

  • This solution calculates and adds an incremental value to a field only when a user creates a record by clicking the Save, Save and Next, or Save and New button in a layout.
  • This solution doesn't support the client domains (multi-tenancy) and Data Grid features of Relativity.

Deploying and configuring the solution

To deploy this solution, add it to the Application Library by doing the following:

  1. Log in to Relativity.
  2. Click the user drop-down menu in the upper-right corner of Relativity, and then click Home.
  3. Click the Applications & Scripts tab, and then click the Application Library tab.
  4. Click Upload Application.
  5. Next to Application File, click Choose File.
  6. Navigate to and select the RA_Auto_Increment_Field_on_Object.rap file, and then click Open.
  7. Click Save.

Preparing the workspace

After you add the solution to the Application Library, you're ready to prepare a workspace to use the solution. Preparing a workspace consists of three basic tasks:

  1. Install the solution to the workspace.
  2. Create a configuration record that specifies how to increment and format values and which field to add those values to.
  3. Associate the solution with the object type that contains the field you want to add values to.

Installing the solution

If you currently have a previous version of this solution, any previous configurations are updated when you upgrade to a new version.

To install the solution in a workspace:

  1. On the Application Library tab for the Relativity instance, click the name of the Auto Increment Field on Object application.
  2. Next to Workspaces Installed, click Install.
  3. Click Ellipsis (...) button next to Workspaces, and then select the check box next to the workspace that you want to install the solution in. To install the solution in more than one workspace, select the check box next to each additional workspace that you want.
  4. Click OK.
  5. Click Save.

Creating a configuration record

After you install the solution in the workspace, the next step is to create a configuration record with settings that define how you want to increment and format values and which field you want to add those values to. The key settings are:

  • Starting value - the numeric value used when calculating the value for the first record that a user creates after you start running the solution. This setting also defines an optional standard prefix for all values.

    Note: As of version 2.3, you can't change this value after the configuration record is created.

  • Increment by - the numeric increment used when calculating values.
  • Padding - the number of digits that you want to pad the second, numeric part of the value with.

The following table provides examples that demonstrate the logic that the solution uses to define the correct incremental value based on various scenarios and sample settings.

Scenario Highest existing value Starting value Increment by Padding Incremented value
The field doesn't contain any existing values for existing records. The solution settings specify a standard prefix ("MyID"), starting value, and padding value. None MyID000001 1 6 MyID000001
The field doesn't contain any existing values for existing records. The solution settings don't specify a standard prefix or starting value but do specify a padding value. None Not set 1 6 000001

To create a configuration record:

  1. Navigate to the workspace where you installed the solution.
  2. On the Auto Increment Field on Object tab, click the Configuration tab.
  3. Click New Auto Increment Configuration.
  4. Complete the following fields:
    • Name - enter a descriptive name for the configuration record.
    • Field to populate - click the name of the fixed-length text or long text field that you want to calculate and add incremental values to.
    • Layout artifact Id(s) - type the Artifact ID of the layout to calculate and add incremental values to the field only when the field appears on a specific layout. To specify more than one layout, enter the Artifact ID of each appropriate layout, and separate each ID with a semi-colon (;). To calculate and add values to the field on all layouts, leave this field blank.
    • Start value - (optional) type a starting value for the first value that the solution calculates. If you want to include a standard prefix for all the values that the solution calculates, type the prefix followed by the starting value. If you don't specify a value, then 0 is used as the starting value.

      For example, you could set the start value to ABC01, the increment value to 2, and the padding to 5. The first RDO field would then be set to ABC00001, the second to ABC00003, and so on.

      Note: You can only set the Start value when you create the configuration. After setting this value and saving the configuration, you can't modify it or the Current value field.

    • Increment by - enter the numeric increment that you want to use when calculating new values. For example, to increase each value by an increment of "10", type 10 in this field.
    • Pad number to - (optional) type the number of digits that you want to pad each value with.
  5. Click Save.

Associating the object type

The final step in preparing the workspace is to associate the event handler, which is included in the solution, with the object type that contains the field you want to add incremental values to.

To associate the event handler with the object type:

  1. In the workspace, click the Administration tab, and then click the Object Type tab.
  2. Click the name of the object type that contains the field. This must be the object type that you selected when you created the configuration record and specified which field to add values to.
  3. Next to Event Handlers, click New.
  4. Select the KCD_1042103.AutoIncrement.dll file.
  5. Click OK.

Running the solution

After you complete all the steps for deploying and configuring the solution in a workspace, the solution automatically starts using the settings that you specified to calculate and add incremental values to the field. This occurs each time a user creates a new record by clicking the Save, Save and Next, or Save and New button in an appropriate layout. You don't need to take any additional steps to run the solution.

Viewing the results

To view the results of running the solution, navigate to any view, layout, or other area containing the field that the solution calculates and adds values to automatically.