Create and manage vocabularies to use with rulesets using the Microsoft Rules Composer (Preview)
Applies to: Azure Logic Apps (Standard)
Important
This capability is in preview and is subject to the Supplemental Terms of Use for Microsoft Azure Previews.
A vocabulary is a collection of vocabulary definitions that use friendly names for the facts used in rule conditions and actions. Vocabulary definitions make rules in your ruleset easier to read, understand, and shareable by multiple people in a specific business domain. For example, tool developers responsible for integrating rule authoring into new or existing applications can consume vocabularies. Vocabularies bridge the gap between business semantics and implementation.
This guide shows how to create and define vocabularies that are placed in the shared rule store by using the Microsoft Rules Composer. You can select the data sources to use, create a new vocabulary, and add vocabulary definitions. You can save a version of your vocabulary to the rule store.
Prerequisites
Download and install the Microsoft Rules Composer.
The XML file that contains the rule store where you want to add a vocabulary.
How does a vocabulary make rules easier to read and understand?
The terms that you use to define rule conditions and actions are often expressed using domain or industry-specific nomenclature. For example, an e-mail user writes rules using terms such as "messages received from" and "messages received after". An insurance business analyst writes rules using terms such as "risk factors" and "coverage amount".
As another exmaple, a variable for an approval status might point at a certain value in an XML schema. Rather than insert this complex representation in a rule, you might instead create a vocabulary definition that is associated with that variable value, and use "Status" as the friendly name. You can then use "Status" in any number of rules. Technology artifacts, such as XML objects and XML documents, that implement the rule conditions and rule actions lie under this domain-specific terminology. However, the rules engine can retrieve the corresponding data from the table that stores that data.
Rule conditions and actions are based on data sources that might have detailed, difficult-to-read binding information, which tells the user little or nothing about what the bindings reference. The rules engine empowers you to create vocabularies that simplify the rules development by offering intuitive, domain-specific terminology that you can associate with rule conditions and actions.
Create a vocabulary
Open the Microsoft Rules Composer. From the Rule Store menu, select Load.
Find and select the XML file that contains the rule store that you want to work on.
In the Facts Explorer window, select the Vocabularies tab.
On the Vocabularies tab, find the Vocabularies folder.
Open the folder's shortcut menu, and select Add New Vocabulary.
The Microsoft Rules Composer creates a new empty vocabulary with a vocabulary version numbered 1.0 as the default version.
Before you can use a vocabulary, the vocabulary needs to have a version stamp. This requirement guarantees that the vocabulary definitions won't change and preserves referential integrity, which means that any rulesets that use that particular version doesn't unexpectedly fail due to changes in the underlying vocabulary.
The following table describes other shortcut commands you can use to work with vocabularies:
| Shortcut command | Task |
|---|---|
| Add New Version | Create a new empty vocabulary version from the selected vocabulary. You can copy vocabulary definitions from other vocabulary versions and paste them into the new version. |
| Paste Vocabulary Version | In the selected vocabulary, paste the previously copied vocabulary definitions from another vocabulary version as a new version. |
| Delete | Delete the selected vocabulary and all its versions. |
The following table describes other shortcut commands you can use to work with vocabulary versions:
| Shortcut command | Task |
|---|---|
| Add New Definition | Launch the Vocabulary Definition Wizard to create a new definition in the selected vocabulary version. |
| Save | Save the changes made to the selected vocabulary version and its definitions. |
| Reload | Reload the selected vocabulary version and its definitions, including the option to discard any current changes made in that version and restore the contents from the rule store. |
The following table describes other shortcut commands you can use to work with vocabulary versions:
| Shortcut command | Task |
|---|---|
| Modify | Launch the Vocabulary Definition Wizard to change the selected definition. |
| Go to source fact | For the selected vocabulary definition, go to the corresponding source fact in a .NET assembly or XML schema. |
| Shortcut command | Task |
|---|---|
| Select Root Node | From an XML schema that contains multiple root nodes, select a root node to load. |
The following sections provide more information about these tasks.
Copy a vocabulary version
When you want to make changes in a vocabulary, create a new vocabulary version to reflect the changes. You can create a copy from an existing vocabulary version but with a different version number.
In the Facts Explorer window, open the vocabulary version's shortcut menu, and select Copy.
Open the vocabulary's shortcut menu, and select Paste RuleSet Version.
The Microsoft Rules Composer creates a new vocabulary version with the same definitions as the copied version but with a different number.
Important
When you create a new vocabulary version, the rules built using a previous vocabulary version still reference the previous version. Make sure that you update the references between thoes rules and the new vocabulary version.
Create an empty vocabulary version
After you add definitions to a vocabulary version, you can create a new empty vocabulary version with a different number, and save that version for you to work on later.
In the Facts Explorer window, select the Vocabularies tab.
On the Vocabularies tab, find the vocabulary from which to create a new version.
Open the vocabulary's shortcut menu, and select Add New Version.
The Microsoft Rules Composer creates a new empty vocabulary version with a different number.
Open the new vocabulary version's shortcut menu, and select Save.
You can now copy vocabulary definitions from other vocabulary versions, and paste them into the new version.
Rename a vocabulary
Before you can rename a vocabulary or a ruleset, you must save everything, which means all versions of the vocabulary definitions.
In the Facts Explorer window, select the Vocabularies tab.
On the Vocabularies tab, in the Vocabularies folder, find the vocabulary that you want to rename.
Select the vocabulary, and in the Properties window, edit the name.
Create a vocabulary definition
You can create a vocabulary definition as a constant value, a range of values, a set of values, or elements from a .NET assembly or an XML document. To create a vocabulary definition, you can use the Vocabulary Definition Wizard.
Alternatively, you can create a new vocabulary definition by selecting a fact from either the .NET Classes tab or XML Schemas tab, such as or a member of a .NET class—dragging the fact over to the Vocabularies tab.
—for example, an XML node,
If you select a public variable, Get and Set options are still available, just like in the XML definition wizard.
Add a constant value as a vocabulary definition
On the Vocabularies tab, in the Vocabularies folder.
In the Vocabularies folder, open the shortcut menu for the vocabulary version that you want.
From the vocabulary version's shortcut menu, select Add New Definition.
You can also drag items from the .NET Classes tab and XML Schemas tab.
The Vocabulary Definition Wizard launches to help you create the definition.
In the wizard, select Constant Value, Range of Values, or Set of Values, and then select Next.
Provide the following information:
Property Description Definition name The definition's name. Description The definition's description. Definition type For this task, select Constant Value. When you're ready, select Next.
Provide the following information:
Property Description Definition type Select a system data type for the definition. Display name Enter a name that doesn't exceed 512 characters. Value Enter a value for the constant. When you're done, select Finish.
Add a value range as a vocabulary definition
On the Vocabularies tab, in the Vocabularies folder.
In the Vocabularies folder, open the shortcut menu for the vocabulary version that you want.
From the vocabulary version's shortcut menu, select Add New Definition.
You can also drag items from the .NET Classes tab and XML Schemas tab.
The Vocabulary Definition Wizard launches to help you create the definition.
In the wizard, select Constant Value, Range of Values, or Set of Values, and then select Next.
Provide the following information:
Property Description Definition name The definition's name. Description The definition's description. Definition type For this task, select Range of Values. When you're ready, select Next.
From the Definition type list, select a system data type for the definition.
Under Step 1 - Specify the display name/value for Range Low and Range High, in the table, select Range Low, and then select Edit.
In the Parameter Definition box that opens, only the Use Constant Value option is available.
Enter a constant value to specify the lower range, and select OK.
Repeat the preceding steps for Range High, which must exceed the Range Low value.
Under Step 2 - Specify the display format string for the range, in the Display format string property, enter the display format string. To revert to the default display format string, select Default.
Note
Make sure that your format string includes parameter indexes using curly braces, for example, use
{0}and{1}to serve as placeholders for the high and low range parameters.The following example shows a sample vocabulary definition for a range of values:
When you're ready, select Finish.
Add a set of values as a vocabulary definition
On the Vocabularies tab, in the Vocabularies folder.
In the Vocabularies folder, open the shortcut menu for the vocabulary version that you want.
From the vocabulary version's shortcut menu, select Add New Definition.
You can also drag items from the .NET Classes tab and XML Schemas tab.
The Vocabulary Definition Wizard launches to help you create the definition.
In the wizard, select Constant Value, Range of Values, or Set of Values, and then select Next.
Provide the following information:
Property Description Definition name The definition's name. Description The definition's description. Definition type For this task, select Set of Values. When you're ready, select Next.
Provide the following information:
Property Description Definition type Select a system data type for the definition. Display name Enter a name that doesn't exceed 512 characters. Under Define values, only the Use Constant Value option is available.
To add a member to the set, enter a constant value, and select Add.
Repeat the previous step for as many values as you want to include in your set.
The following example shows multiple values in the set:
To move a value within the relative order of the set, in the Values box, select the value, and then select Up or Down.
To remove a member from the set, in the Values box, select the value, and select Remove.
When you complete your set, select Finish.
Add a .NET class or class member as a vocabulary definition
Before you start, make sure to put your .NET assemblies in a directory local to the Microsoft Rules Composer. If you update the .NET assembly, make sure to update your ruleset version's references to that assembly. For more information, see Update .NET assembly references.
On the Vocabularies tab, in the Vocabularies folder.
In the Vocabularies folder, open the shortcut menu for the vocabulary version that you want.
From the vocabulary version's shortcut menu, select Add New Definition.
You can also drag a .NET class or class member from the .NET Classes tab.
The Vocabulary Definition Wizard launches to help you create the definition.
In the wizard, select .NET Class or Class Member, and then select Next.
Provide the following information:
Property Description Definition name The definition's name. Description The definition's description. In the Class member information section, select Browse.
Find and select the assembly that you want, and then select Open.
In the Select Binding box, expand the assembly node.
Select a class, or expand a class and select a class member, and then select OK.
Choose one of the following steps:
If you select a class, for Display name, enter a name that doesn't exceed 512 characters, and select Finish.
You're now done with this section.
If you select a class member that has parameters, select Next.
The Specify the Display Name - .NET Class or Class Member Definition page appears for you to provide a value and display format string for each parameter.
Under Step 1 - Specify the display name/value for each parameter, in the Parameters box, select a parameter, and then select Edit.
For Parameter value, only the Use Constant Value option is available, so enter a constant value.
Under Step 2 - Specify the display format string, in the Display format string property, enter the display format string. To revert to the default display format string, select Default.
Note
Make sure that your format string includes parameter indexes using curly braces, for example, use
{0}and{1}to serve as placeholders for the parameters.Repeat the previous steps for each parameter in your class member.
The following example shows multiple parameters in the class member:
Create a vocabulary definition from a .NET assembly
You can create vocabulary definitions from classes or class members in a .NET assembly to define predicates, arguments, and actions. Before you start, make sure to put your .NET assemblies in a directory local to the Microsoft Rules Composer. If you update the .NET assembly, make sure to update your ruleset version's references to that assembly. For more information, see Update .NET assembly references.
In the Facts Explorer window, select the .NET Classes tab.
From under .NET Assemblies, drag a class or class member onto an existing vocabulary definition, which appears on the Vocabularies tab.
Create a vocabulary definition from an XML document element or attribute
You can create vocabulary definitions from XML elements and attributes by browsing through XSD schemas and dragging items to the conditions editor or actions editor to define predicates, arguments, and actions.
On the Vocabularies tab, in the Vocabularies folder.
In the Vocabularies folder, open the shortcut menu for the vocabulary version that you want.
From the vocabulary version's shortcut menu, select Add New Definition.
The Vocabulary Definition Wizard launches to help you create the definition.
In the wizard, select XML Document Element or Attribute, and then select Next.
Provide the following information:
Property Description Definition name The definition's name. Description The definition's description. In the XML document information section, select Browse.
Find and select a schema (.xsd) file, and select a document element or attribute.
From the Type list, select a type that is compatible with the type for the selected element or attribute from the schema.
Note
The engine doesn't validate defined element's existence and the document type. If you assert an XML document that doesn't have the element, you get an error at runtime. If you assert an XML document with an unknown document type, the engine just ignores the document.
If the engine can't perform a valid cast between the specified type and the type for the selected document element or attribute, you get an error at run time.
In the Select operation section, select the operation type that indicates whether you plan to get the element or attribute's value or set the value.
If you chose to set the value, select Next, and specify the display format.
The Specify the Display Name - XML Document Element or Attribute page appears for you to provide a value and display format string to use.
Under Step 1 - Specify the display name/value for each parameter, in the Parameters box, select a parameter, and then select Edit.
For Parameter value, only the Use Constant Value option is available, so enter a constant value.
Under Step 2 - Specify the display format string, in the Display format string property, enter the display format string. To revert to the default display format string, select Default.
Note
Make sure that your format string includes parameter indexes using curly braces, for example, use
{0}and{1}to serve as placeholders for the parameters.
When you're done, select Finish.
The following example shows the details for a vocabulary definition based on an XML document element or attribute:
When you create vocabulary definitions for XML nodes, the XPath expressions for the bindings have similar default values, based on the rules described earlier. However, you can edit these values in the Vocabulary Definition Wizard. Changes to the expressions are put in the vocabulary definition and are reflected in any rule arguments that you build from the vocabulary definitions.
