How to validate data entered into fields

Task Description

This document describes how to validate data entered into one or more fields in a CollectionSpace record.

Prerequisites

The tasks described in this document can be performed by a software developer with at least basic to intermediate-level knowledge of the Java programming language and/or the JavaScript programming language. Familiarity with CollectionSpace's Services and/or User Interface (UI) layer source code can also be helpful, although it is not required.

Procedure

You can validate the values of fields in a record, when that record is created or updated, in either or both of:

• The CollectionSpace back-end, in the service that handles that type of record (e.g. Intakes, Loans Out).
• The CollectionSpace front-end, in a JavaScript script that that type of record.

Generally, you will perform validation in the back-end, as this ensures that all requests to create or edit records will be handled uniformly with respect to validation.

In addition, you can optionally perform complementary validation in the front-end, to improve the user experience by providing early indication of invalid field values. Without doing so, the user won't be informed that one or more of their values is invalid until they attempt to save their changes.

The process of adding validation for a record type in the back-end services is described here:

Check out a copy of the source code for the CollectionSpace Services layer

First, if you haven't already done so, Check out a copy of the source code for the CollectionSpace Services layer.

Find and edit the relevant ValidatorHandler.java file

In the directory containing the Services layer source code, use a text editor to edit the validate() method in the relevant ValidatorHandler.java file for the record type you wish to validate. You can find this file using the following generic path:
services/{name of record type}/service/src/main/java/org/collectionspace/services/{name of record type}/nuxeo/{capitalized name of record type}/ValidatorHandler.java}

As an example, to to add or change validation behavior for Intake records, edit the validate() method in the file:
services/intake/service/src/main/java/org/collectionspace/services/intake/nuxeo/IntakeValidatorHandler.java.

There is an existing validation example you can follow, for Cataloging (aka CollectionObject) records, in which validation is performed upon both creation and updating of records. (Currently, this example requires that the objectNumber field in those records be non-empty, both when creating and updating records.)

• The CollectionObjectValidatorHandler class provides an example of how this is done.
• This class also inherits some of its routines from its parent, the ValidatorHandlerImpl class.

Deploy the changed ValidatorHandler file

To make your validation changes to CollectionSpace's back-end services take effect:

• Shut down the CollectionSpace servers
• Within the top-level directory of the Services layer source code you've downloaded, enter the following commands:

  mvn clean install -DskipTests
  ant deploy
  

• Start up the CollectionSpace servers

Test

1. Log into your CollectionSpace system by visiting http://<ip-address>:8180/collectionspace/ui/{tenantname}/html/ in your Web browser. (Make sure to substitute <ip-address> with the hostname or IP address of the server on which you installed CollectionSpace.)
   For example, if your CollectionSpace system was hosted at www.example.com, and you were using tenant core you would type:

   http://www.example.com:8180/collectionspace/ui/core/html

2. Log in by entering a username and password.
3. Click the Create New tab.
4. Click the radio button next to the type of record you'd like to create.
5. Click the Create button.
6. Enter data into certain fields (or leave certain fields empty) in a manner that will trigger the validation behavior you have added.
7. Click the Save button. You should see an error message.
8. Edit the data in those fields so that they will successfully pass your validation check(s).
9. Click the Save button. The record should successfully be saved.

Summary

By following this procedure, you will have changed the behavior of CollectionSpace's back-end services to validate data for one or more of the fields in a particular type of record.