BOM customization through the API

When a vocabulary is automatically generated, the verbalization of each attribute is based on its name in the BOM. The naming follows simple rules such as replace a camel case word with the same words in lowercase, separated by spaces. For example, if an attribute firstName in the BOM is verbalized as first name, it looks like this in a business rule:

then set the first name of ‘the customer’ to “Jane”;

For business rule authoring, you can customize the automatically generated label to use forename instead of first name, so that the business rule looks like this:

then set the forename of ‘the customer’ to “Jane”;

To achieve this, you must customize the automatically generated vocabulary.

Customizing an attribute label

An attribute within a vocabulary is represented by an IlrFactType object. This object is, in turn, associated with one or more IlrRole objects that contain the label used when authoring rules. You can retrieve the IlrFactType for an attribute directly from the vocabulary:

IlrFactType factType = vocabulary.getFactType(attribute);

A factType can have an owner role or an owned role (or both). For an owned role, the label is used as the subject in a sentence. For an owner role, the label is used as the object in a sentence. A setter always has an owned role. By default, a single setter is generated for each attribute. You can add more sentences (setters) if you want to.

Using the IlrFactType, you can obtain the IlrRole objects by using the IlrVocabularyHelper class:

IlrRole ownedRole = IlrVocabularyHelper.getOwnedRole(factType);
IlrRole ownedRole = IlrVocabularyHelper.getOwnerRole(factType);

The required role varies, depending on where the attribute is used within a rule. For example the owned role is used as the subject in a sentence. You update the label for an IlrRole by using the setLabel(String) method:

ownedRole.setLabel(“forename”);

Updating the verbalization

When you customize a label, you must also update the verbalization. You must update the template in each IlrSentence that uses IlrFactType, otherwise the verbalization is inconsistent for authoring business rules.

You generate a verbalization by using IlrVerbalizer. You can obtain a default implementation from IlrVerbalizerRegistry:

IlrVerbalizer verbalizer =
      IlrVerbalizerRegistry.getDefault().getVerbalizer(
         vocabulary.getLocale()
      );

IlrVerbalizer requires an IlrSentence as input to the generation process. You can retrieve these sentences, like IlrRole objects, by using the IlrVocabularyHelper:

List<IlrSentence> sentences = (List<IlrSentence>)
   IlrVocabularyHelper.findSentencesForCategory(
      IlrSentenceCategory.SETTER_LITERAL, factType
   );

The first argument IlrSentenceCategory describes which type of sentence is being searched for. Depending on the type of attribute, for example whether it is a collection, how it is used, you must invoke findSentencesForCategory multiple times for each relevant IlrSentenceCategory.

For each IlrSentence, you must call the generateTemplate method of the IlrVerbalizer. This call generates the verbalization template which you then store in the IlrSentence object by using the setTextTemplate method:

for(IlrSentence sentence : sentences)
{
   String template =
      verbalizer.generateTemplate(
	       setter, setter.getSyntacticRoles()
      );
   sentence.setTextTemplate(template);
}

Example method that updates setter methods for an attribute

The following method updates the label for an attribute, and refreshes the verbalization for the setter method:

private void changeSettersForAttribute(
    String propertyDisplayName, 
    IlrAttribute attr,
    IlrBOMVocabulary voc)
{ 
               
     // Retrieve the vocabulary element associated with this attribute
     IlrFactType factType = voc.getFactType(attr); 

     // A fact-type can have either or both the owner and owned roles:
     // -- The owned role is where the label is used as the subject in a sentence. 
     // -- The owner role is where the label is used as the object in a sentence.
     //
     // A setter will only use the owned role, so the label for that role is 
     // updated here 
     IlrRole ownedRole = IlrVocabularyHelper.getOwnedRole(factType); 
     ownedRole.setLabel(propertyDisplayName); 

     // Once the label is updated, the sentences using that label also 
     // need to be recreated to use the new label. These sentences are
     // generated using an IlrVerbalizer
     IlrVerbalizer verbalizer =           
           IlrVerbalizerRegistry.getDefault().getVerbalizer(
                voc.getLocale()
            );
 
     if (verbalizer != null) { 

        // Retrieve all the setting sentences for this attribute. By default, 
        // only one setter sentence will be generated for each attribute. 
        // There will only be more than one element found if the vocabulary has 
        // been customised to add extra setters.
        List setters =         
                IlrVocabularyHelper.findSentencesForCategory(
                    IlrSentenceCategory.SETTER_LITERAL, factType
                );
 
        // Update all the sentences found using the IlrVerbalizer. 
        for(IlrSentence sentence : sentences) {
	          String template = 
                    verbalizer.generateTemplate(
                         sentence, sentence.getSyntacticRoles()
               );
            sentence.setTextTemplate(template);
             } 
       } 
}