Nuxeo Studio Rocks: Configure a Core Business Rule for a Field

We recently released the version 31 of Nuxeo Studio, and I had the opportunity to let the world know how much happiness this version brings(1). I promised that we will write more blogs explaining the new features in detail, and so here we are! In an earlier blog, Fred showed you how to edit text resources from Studio, and today I will talk about a cool and very important feature: binding a field to a vocabulary.

Build your Business Rule

A vocabulary is a list of values, where each value has a unique ID, a label, and some other fields. The Nuxeo Platform stores the ID and displays the label: simple list, or hierarchical (any depth you want). This is the best way to ensure that a user will not make a typo when entering data, or will not add extra spaces inadvertently, or can search only on values that can be found. Binding such list of values to a field is a core business rule: It means you want to make sure that whatever the way a value is set to the field (UI, REST Call, bulk-import server side, etc.), it exists in the vocabulary, and if it does not, then the creation/modification must be rejected.

The Nuxeo Platform allows you to configure such strong rules and it also lets you add more rules of course, such as maximum length, pattern (For instance, to make sure an email field is a well formatted email), etc. What’s new is that you can now do it literally within seconds with Nuxeo Studio version 31. Here is an example.

Say we have a Claim document, which contains fields storing an address, including the claim:address_state field. We also have a vocabulary listing all the US states:

Our golden rule is: “The value stored in claim:state must exist in the USStates vocabulary”.

Doing it in Studio took me far less time than taking the screenshots and explaining the steps in this article:

• In the Claim schema editor, select Directory as field type for the field:

• Click the little “Edit” button (on the right of the field), and just pick the USStates vocabulary (see above, the first screenshot of this article)

And Voilà.

Yes. That’s it! The business rule will be applied next time you deploy these changes on the server. Now, if a user inadvertently tries to store a value that is not in the USStates vocabulary, an error is displayed:

And if the creation/modification is done via an Automation Chain, a REST client, a plug-in, etc. the same rule applies: The action will be rejected (the transaction is rolled-back, etc.)

Because Studio is our friend, it went quite a few steps further! For example, whenever you drop the claim:address_state field in a layout, the widget is automatically set to “Single Directory Suggestion”, the vocabulary already set to USStates:

This actually means that my previous example displaying an error will never happen, since you will not have a single Text widget for this field, but a vocabulary. There’s no way for the user to make a mistake. But I still wanted to show you this nice red error, because it _is_ nice.

Resolve Values in a Single REST Call

There also is a big bonus where Studio is not involved(2): Now that you built this strong business rule, the indestructible link between a vocabulary and a field, you can resolve it automatically when doing a REST call. Just add the correct header, and claim:adress_state will be resolved. You won’t need to send two requests (one to get the vocabulary ID, one to get the label). Just use the following headers for your request: X-NXproperties: claim X-NXfetch.document: claim:address_state

X-NXproperties tells Nuxeo which schema(s) to return (instead of no schemas, which is the default). X-NXfetch.document is a quite powerful header, since it resolves the values that are declared as references using a marshaller.

So after a call to the Nuxeo Platform, for example {yourserver:port}/nuxeo/api/v1/id/8bcf4503-26fa-4c73-a1d5-9397881ec454, with these headers (using the ID of a Claim here), you will get the following result. Check the “claim:address_state“ property- it is 100% resolved:

{
  "entity-type": "document",
  . . .
  "properties": {
    "claim:address_street_1": "1234 12th Avenue",
    "claim:address_street_2": "Best Hot-Dogs",
    "claim:address_city": "New York",
    "claim:address_state": {
      "entity-type": "directoryEntry",
      "directoryName": "USStates",
      "properties": {
        "ordering": 0,
        "obsolete": 0,
        "id": "NY",
        "label": "New York"
      }
    },
    "claim:address_zip": "11234",
    "claim:date_closed": null,
    . . .
  },
  . . .
}

And it will work exactly the same if the field references a Document (for example, we could have a claim:customer field storing a reference to a Customer Document) or a User/Group (Imagine a claim:main_assignee field).

Told you, you’ll be happy with Studio!

(1) Yes. Nuxeo Studio can do that: Bring happiness (2) As far as I know. I suspect it is involved, but too shy to tell us.