First released in version: 3.4 / Last updated in version: 3.8.3

Rules engine developer

SmartSpace Rules engine developer provides you with the graphical environment to capture logic and relationships between objects in rules and event handlers that reflect your business processes. These definitions are then used by the Business rules engine.

The Business rules workspace in SmartSpace Config provides an editing environment which aids the creation of rule and event definitions. Definitions are constructed by dragging and dropping properties and keywords into available slots in templates. Visual cues in the interface and real-time error messages support the creation of valid definitions.

You can create the following kinds of definition:

• Events

  Actions defined in an event definition run when a value or a fact about a property changes. Events can be used to create or delete objects, set a property, set or unset representations, or send notifications.

  More than one action can be included in an event, and further tests and conditions can be specified within the definition.
  The template for an event definition is based around a statement that begins with “when…”.

• Timeouts

  A timeout is triggered when the time specified by a property (whose type must be time) is reached. Timeouts can be used to create or delete objects, set a property, set or unset representations, or send notifications.

  More than one action can be included in a timeout, and further tests and conditions can be specified within the definition.
  The template for the definition of a timeout is based around a statement that begins with “when…”.

• Rules

  Rules are an invariant statement of fact.

  The template for the definition of a rule is based around a statement that begins “property whenever…”.

• External definitions

  External definition rules are used to create a named list of properties to be used in the creation of a .NET plugin. See External Definition API for information.

Workflow

The steps to create a business rule in SmartSpace are as follows:

1. Create a new definition.
   See Adding a definition.
2. Open the definition in the editor.
   The features of the editor are described in The Business rules workspace.
3. Build the logic.
   Drag properties and keywords into the definition and select or enter values to construct a logical expression.
   See Editing a definition.

Follow these steps to create the collection of rules you require and then publish them to activate them in your system. See Publishing definitions.

You can also use the BUSINESS RULES workspace to load rule definitions (and dependencies, such as types or representations) and also assets such as searches or screens for web forms that have been developed in other SmartSpace installations, and you can export rule definitions and other items you have created, for use elsewhere. See Managing definitions.

After definitions have been published, you can trace the behavior of business rules in real time in the Rules engine trace workspace in SmartSpace Config. See Rules engine trace.

Requirements for Rules engine developer

You will need SmartSpace version 3.4 or later with a license for Business rules and Rules engine developer.

The Business rules workspace

The Business rules workspace in SmartSpace Config provides tools to create and edit business rules.

Click on BUSINESS RULES to display the workspace.

Features of the Business rules workspace are described in the following sections.

Building definitions

Adding a definition

To create a definition, you first give it a name and choose the kind of definition it is. Double-click <Create new definition>, enter a name, and choose one of:

• whenever to create a rule
• when fact changes to create an event where a property of a Boolean type changes
• when value changes to create an event where the value of a property changes
• when timeout is triggered to create a timeout
• external definition to create a named list of properties to be used in the creation of a .NET plugin. See External Definition API for information.

Click Create and the definition is added to the list, where it is shown as an unsaved work in progress.

Editing a definition

Now when you drag the definition into the editor, the empty template for the definition’s type opens and you can begin to build the logic of your definition:

In this example, the property ‘Office’ contains ‘Person’ is dragged into the Property slot in the template. Note the color used to display properties matches the display color of the prompt.

The Action for this event is shown being built. The set property action (whose color matches the Action slot in the template) has been dragged into the scratchpad. Its Property slot is filled with a property with the integer type, the occupancy of Office. The Value slot is filled with an expression built from the + operator with one value provided by a property and the other by a literal, in this case the integer 1, which can be entered by double-clicking the slot and typing a value. This entire chunk of logic can be dragged to the Action slot in the expression.

As you work the error messages change to reflect the state of the definition. At this stage, the definition is still incomplete and clicking an error will highlight a missing term:

Where a list of values is available, you can double-click to select one from a dropdown:

When all the slots have been filled and configured correctly, there will be no error messages, and the definition is no longer flagged with the work in progress icon. At this point, you can publish it and it will become active. (See Publishing definitions for how to do this.)

After publishing the definition, you can see the event in action. Go to the Types and Objects workspace in SmartSpace Config and open a window showing the properties of the object Office 2 and another window for the ‘Office’ contains ‘Person’ complex property.

Create a new property row in Office contains Person:

When you save this row, the occupancy of the office has been increased by 1.

Keywords for definitions

The following are the keywords available in the toolbox.

Actions

Available for events and timeouts

if then

Performs an action if a specific fact is true.

if then else

Performs an action if a specific fact is true, otherwise perform another action.

set property

Sets the value of a property.

set representation

Sets the representation for a specified representation mode of an object.

unset representation

Unsets the representation for a specified representation mode of an object.

notify

Sends a notification to a role on the web map.

• Requires roles to have been configured in the Users and roles workspace.

notify near

Sends a notification to a role on the web map including a specific object.

• Requires roles to have been configured in the Users and roles workspace.
• Requires the Visibility component to display the web map.

notify near using

Sends a notification to a role on the web map including an object located using a search.

• Requires roles to have been configured in the Users and roles workspace and a search to have been defined in Web searches.
• Requires the Visibility component to display the web map.

Operators

Available for rules, events and timeouts

and

This is true if all the slots are true.

or

This is true if any one of the slots is true.

not

This returns true if none of its contents are true.

=

The equals operator returns true if the two slots have the same value.

!=

Returns true if the two values do not have the same value.

is a

Tests the type of an object

contains

Tests spatial containment.

Terms

as string

Converts a non-string value to a string.

now

Returns the current date/time.

null

Unsets a value.

hours between

Gets a difference in time based on a specified shift.

• Requires shift patterns and shifts to have been configured in the Shift patterns workspace (or in the Shifts screen in SmartSpace web if you have licensed the Visibility component).

hours in the future

Gets a time in the future based on a specified shift.

• Requires shift patterns and shifts to have been configured in the Shift patterns workspace (or in the Shifts screen in SmartSpace web if you have licensed the Visibility component).

shift

Returns the string which is the value of log duration in shift for an object, or No Shift.

The object's type must be a descendant of the Ubisense Object type (see Types and objects)

• Requires shift patterns and shifts to have been configured in the Shift patterns workspace (or in the Shifts screen in SmartSpace web if you have licensed the Visibility component).

Terms for String Manipulation

Terms introduced in the 3.5 release can be used to extract information from string properties.

When using string manipulation terms the following should be noted:

• Any expression with a null argument returns null
• The index of a substring that is not found is -1
• A substring expression with index equal to the string length returns the empty string
• A substring expression with index greater than the string length returns null
• If a substring length extends past the end of the string, the expression returns the rest of the string

• A negative substring length is implicitly converted to an unsigned value before applying the previous rule. This effectively means that a negative number is treated as a very large positive number that extends past the end of the string. For example:

  the substring of "abcde" at 3 with length -1

  returns "de".

  Use this special case to get the remainder of a string from a specified position to the end.

The following terms are available for string manipulation.

substring

Display only characters from position X and a length of Y.

replaced by

Search for occurrence of STRING X and replace it with STRING Y. Replacing the empty string with anything has no effect.

index of

The index of the substring.

length of

The length of the substring.

trimmed

Trimmed substring.

uppercase

Convert the string to uppercase characters. Does not take the server locale into account.

lowercase

Convert the string to lowercase characters. Does not take the server locale into account.

Adding comments to your definitions

You can add a comment to a definition by double-clicking the “when” or “whenever” in its first line. This opens a dialog where you can enter explanatory text. Click OK to save. You can add comments to actions in a similar way.

Elements with comments are tagged with a triangular earmark. Click an earmark to display the comment inline. Double-click to edit a comment. (You can delete a comment by opening it, deleting all the text, and clicking OK.)

Organizing definitions

As you build up your collection of business rules, the list of definitions can become long and particular definitions hard to find. You can organize definitions and make them easier to locate by creating and applying labels to them. Definitions can be tagged with more than one label.

Labels are also used to organize definitions for saving. See Managing definitions

Create a label by double-clicking <Create new label>, entering the name for the label and clicking Save. Drag a label into a definition to tag it: the label is shown at the top of the definition.

(You can edit a label’s name by double-clicking its current one. Enter a new name and click Save.)

You can limit the contents of the list of definitions to those tagged with particular labels by dragging the labels into <Drag here: filter by LABELS>. Only those definitions tagged with matching labels will be shown.

Publishing definitions

When you have finished creating definitions, or loading them from other sources, and you want to make them active in SmartSpace, you publish them.

Note: Only definitions that are complete and contain valid logic can become active in SmartSpace. However, incomplete or invalid definitions can be kept alongside published definitions to be completed or corrected later.

If definitions have already been published, the new definitions will replace them. Each collection of definitions that is published is identified by a version number. Past versions are retained in SmartSpace, unless you explicitly delete them.

To publish a new version of your definitions or to delete superseded versions you no longer require:

1. Click Publish. A list of versions is displayed and you can mark them for publication or deletion. No changes are saved until you commit them.

   

   The status of each version is indicated. Status can be:

   • Unpublished: the definitions currently loaded in the Business rules workspace. There can be only one unpublished version

     Double-click the unpublished version to give it a description and then select the Publish check box if you are ready to make this the active version. The number of valid definitions that can be published is indicated, along with the number of invalid or incomplete definitions.

     

   • Active: the definitions currently in use in SmartSpace. There can be only one active version

     Double-click the active version to give it a description. Select the active version's details and press Delete if you want to delete it (its details will be displayed in gray). When you commit your changes, the most recent superseded version will become the active version.

   • Superseded: versions of definitions that were active in SmartSpace in the past. There can be multiple superseded versions

     Double-click a superseded version to give it a description. Select a superseded version's details and press Delete if you want to delete it (its details will be displayed in gray). When you commit your changes, it will be removed from your installation.

2. Click Commit to confirm.

Managing definitions

In addition to developing and maintaining the rules in your current SmartSpace installation, you can load collections of rules called modules that have been developed in another SmartSpace installation, and save your rules—along with other items required by them—for use in other installations. The content of modules can extend beyond rule definitions to include other assets you might want to move, such as searches, screens for web forms, or report definitions. Again, you can choose to save dependencies along with these assets. For a full description, see Module import and export.

Use the Load and Save buttons in the Business rules workspace to manage your rule definitions.

Loading definitions

When you first open SmartSpace Config and go to the Business rules workspace, the list of definitions is empty. You can start adding new definitions immediately, or you can load and edit:

• the definitions currently active in SmartSpace
• superseded definitions stored in SmartSpace
• a module containing definitions and other items saved from a Ubisense installation

You can load definitions from more than one source, for example to merge definitions from different versions, and then publish a new combined version. When loading, alongside the rule definitions you may also be offered types and objects and other items required by the rules. When you load definitions, you specify how any conflicts between different items are handled.

When you add new definitions, or make changes to active or superseded definitions, these updates are not applied to your system until you publish a new version. Similarly, when you load a module file with definitions, searches, types, properties, etc, everything except the business rules definitions is applied immediately. The definitions must be published after they have been loaded.

You can load definitions along with any included dependencies from a file, or currently active business rule definitions, or previously published versions in your installation. When you choose a file or collection of rules, you will be offered a list of items to load. By default, new and unchanged items are selected. Items that are different to those which are current in your installation (for rule definitions this means those that are available for editing in the Business rules workspace), are not selected. This is to avoid accidentally overwriting locally edited rule definitions. You can choose changed items for loading to replace the current ones.

Note: It is important to remember that loading business rule definitions does not make them active in SmartSpace. When you are ready to make them active, you must publish them.

To load definitions, in the Business rules workspace:

1. Click Load to open a dialog where you can choose the source of the definitions and select items to be loaded.

   

2. Choose the file or rules to be loaded.

   • To load from an external file, select Load file and enter the path and filename for the saved definitions, or use the Browse button to navigate to a file. By default, you are offered files with a .ssc extension
   • To load current or past rule definitions, select Load published rules and select the current rules—labeled active—or a previous set from the dropdown

3. With the definition source selected, all available items are displayed in the categories: New Items, Changed Items, and Unchanged Items. By default, unchanged and new items are selected; changed items are not selected in order to avoid writing over locally edited rule definitions.

   Note: If the property contents are altered while the load screen is open, refresh the display by pressing F5 to update the view.

   Select the items to load.

   • Use the Expand all button to display available items
   • Selecting a parent item selects all child items in that category
   • At <Type here: search by NAME> enter text (case sensitive) to search for items whose names match your input. Click to remove the filter.

   As you select items, information in the STATUS column indicates the result of loading those items, and the number of items currently selected for loading is shown in the Load x item(s) from source button.

   If you already have definitions loaded, choose how any conflicts will be handled during loading by:

   • Selecting any changed items where otherwise they would be skipped and the current version retained
   • Choosing Cancel to abandon the process completely

   To help you identify which items to load, you can open a second source for comparison. Choose Compare with another set of items and choose another file or published version (as described in step 2). Items are displayed in categories: Only in source, Only in source for comparison, Identical, Different.

4. If you want to have only the items you select loaded and any definitions currently available in the Business rules workspace to be cleared away, select Discard previously loaded rule definitions.

5. When you have selected the items you require, click Load x item(s) from source.

   All selected items are loaded and rule definitions are available in the Business rules editor. However, the definitions are not yet active in SmartSpace until you publish them— see Publishing definitions.

 

Saving definitions

Saving definitions allows you to keep a copy of the definitions currently loaded in the Business rules workspace, for example if you want to merge them into another SmartSpace installation. Saving definitions does not make them active in your SmartSpace installation: to make definitions active, you must publish them— see Publishing definitions.

When you save one or more definitions, you can also save other items they reference, and you can use this functionality to create a collection of types, objects, searches, rules and so on to encapsulate specific business processes for use in other SmartSpace installations.

The recommended workflow for saving definitions is:

1. Select a file to save the definitions to
2. Create labels and apply them to assets
3. Use the Add required labels button to apply labels to any additional items required by labeled assets
4. Select the items you want to save
5. Save the file

To save definitions, in the Business rules workspace:

1. Click Save to open a dialog where you can specify the content and destination of a collection of saved definitions:

   

   All items available for saving are listed with any previously-applied labels shown in the LABELS column.

   At any time you can:

   • Use the Expand all button to display available items
   • At <Type here: search by NAME> enter text (case sensitive) to limit the display to items whose names match your input. Click to remove the filter.

2. At Select a file to save enter the path and filename for the definitions, or use the Browse button to navigate to a location or file.

   By default, files are given a .ssc extension.

3. Create and apply labels.

   • Create a label by double-clicking <Create new label>, entering the name for the label and clicking Save.
   • Drag labels from the AVAILABLE LABELS list onto assets. Other items required by a labeled asset are indicated by the relevant label appearing in the REQUIRED LABELS column. Items labeled as required are those which are necessary for the module to work and whose omission will cause a future import to fail.
   • Slowly double-click an asset's current labels to open a dropdown from which you can select a single label to replace the current ones, or the blank entry to delete all labels from the asset.
   • Highlight one or more assets (using Shift+click or Ctrl+click) and labels associated with the highlighted items are listed under LABELS ON THE SELECTED ITEMS. If labels are attached to only some of the highlighted items, they are shown inside [square brackets]. Deleting a label from the LABELS ON THE SELECTED ITEMS list, removes it from any items with which it has been associated without deleting the label itself.

4. While you are adding labels, you can click Add required labels if you want any dependencies to be labeled too. If no items require labeling, the button is unavailable.

   When structuring sets of definitions it can be useful to ensure that each definition gets one single label, corresponding to the activity that 'owns' the definition. If you check Add to existing labels, then a required label is always added to every definition; if you leave Add to existing labels unchecked, then a required label is only added to definitions that had no labels before Add required label was selected.

5. Select the items to be saved.

   • Drag labels to the filters at the top of the screen to limit the displayed items to those that match the criteria you define.

   • Use the Select all and Unselect all buttons to select all or none of the displayed items.
   • Selecting a top-level category, such as Roles or Types, selects all items in that category.

   As you add to your selection, the number of items to be saved is shown in the Save x item(s) button.

   Make sure all required items are selected to ensure successful import of the module.

6. When you have specified the destination and selected the items to be saved, click Save x item(s).

Saving Reports and Logged Locations and Logged Properties

When saving reports, you might need to label types and properties manually, since report dependencies are not computed automatically.

Saving modules examples

Saving without labeling

Whilst the recommended method for saving makes use of labels, you can save selected assets without the use of labels. For example, to save just the business rules and no other items you:

1. Select the file to save to
2. Check Business rules in the list of items to save and all listed rules are selected
3. Click Save x item(s)

In this case, no dependencies are saved, and there would be no guarantee that the rules would function if loaded into a different SmartSpace installation.

Saving all items

You can save all available items by:

1. Selecting the file to save to
2. Clicking Select All
3. Clicking Save x item(s)

Saving a web form and all dependencies by using a label

With the use of labels, as the following example shows, all dependencies can be identified and (optionally) selected to build a meaningful collection of items into a module. Here, a form that lists products ready for dispatch to a selected country is to be saved.

First a label is created and is dragged onto the name of the form:

The label is added to the REQUIRED LABELS column for the following related assets:

• The search on which the form is based
• The types and properties used in the search
• The roles to which the screen and form have been assigned

Additionally, the objects used in the search filter, here a list of countries for selection when the form displays are available for saving. This is because the Country type has only a name property and inherit an enumeration type. See Items that can and cannot be included in a module

Clicking Add required labels adds the label to all the identified items. Note that nothing has as yet been selected for inclusion in the module. The most reliable way to ensure all labeled items are selected is to use one of the filters. Drag the despatch label into a filter:

The list of items now shows only those items with the corresponding label:

Clicking Select all and then Save 19 items adds all the required assets to the module.

Saving a module with space properties

The following example shows how a module that includes types with space properties and a containment relationship requires a little more work to ensure all dependencies are identified and included in a module.

In TYPES / OBJECTS, the Product and Workspace types each have an extent property:

In SPATIAL PROPERTIES, specific spaces have been defined for the area of each workspace, a default space has been created for the product type, and a request to monitor their spatial relationship has been defined. (See Spatial properties for further information.)

A complex property is defined for the spatial relationship between the two types:

A business rule then makes use of the complex property:

To create a module containing this rule and all dependencies, in BUSINESS RULES with the rule loaded, click Save. Creating a label and dragging it onto the business rule and then clicking Add required labels results in dependencies being identified. These are shown filtered by their label below:

Missing from the items identified for saving are extent of 'Product' and extent of 'Workspace'. The easiest way to ensure these properties are also identified is to drag the label onto the autogenerated Business rule for the 'Workspace' extent contains 'Product' extent complex property (remove the filter first). Clicking Add required labels again adds the label to the two properties:

Selecting all the labeled items and saving them will create a module with all dependencies satisfied.

Managing modules from the command line

The command-line tool, ubisense_smartspace_module_admin, allows you to load and publish a module, or to remove a module ("unpublish") from your dataset.

You can download ubisense_smartspace_module_admin using the Ubisense Application Manager where it can be found in the DOWNLOADABLES task under Ubisense > SmartSpace core > Module admin tools.

For example, to publish a module packing-bay.ssc, use the command:

C:\Ubisense>ubisense_smartspace_module_admin publish packing-bay.ssc

ubisense_smartspace_module_admin (version 3.8 build 8545)
Copyright 2023 Ubisense Limited, all rights reserved.
Please report any bugs to <support@ubisense.com>.
For more information visit <http://www.ubisense.net>.

> Reading packing-bay.ssc
> Found 16 items
> Skipping type "Crate" (already in the dataset)
> Skipping property "extent of 'thing'" (already in the dataset)
> Skipping property "capacity of 'Crate'" (already in the dataset)
> Skipping property "color of 'Crate'" (already in the dataset)
> Skipping property "name of 'Crate'" (already in the dataset)
> Skipping property "the extent of 'Crate' contains the extent of 'component'" (already in the dataset)
> Skipping property "extent of 'Crate'" (already in the dataset)
> Skipping type "Forklift" (already in the dataset)
> Skipping property "range of 'Forklift'" (already in the dataset)
> Skipping property "the range of 'Forklift' contains the extent of 'Crate'" (already in the dataset)
> Skipping property "in range of 'Forklift'" (already in the dataset)
> Skipping property "registration of 'Forklift'" (already in the dataset)
> Skipping property "loaded of 'Crate'" (already in the dataset)
> Skipping property "loaded of 'Forklift'" (already in the dataset)
> Loading rule "full crate"
> Loading rule "forklift in range"
> Loaded 2 items (14 skipped)
> Published rule definitions as version 9

Note: You must always include the .ssc extension of the module's filename when using ubisense_smartspace_module_admin.

The options --overwrite and --skip-modified allow you to either overwrite items in the dataset where these items are different in the module or leave existing properties unchanged where they differ from the module.

To remove a module's content from a dataset, use, for example:

ubisense_smartspace_module_admin unpublish --force-removal module-01.ssc

Including the --force-removal option ensures that modified items and dependent items that were omitted from the module are also deleted.

You can also use list with ubisense_smartspace_module_admin to view the items in a specified module. For example:

C:\Ubisense>ubisense_smartspace_module_admin list packing-bay.ssc

...

> Reading packing-bay.ssc
> Found 11 items
| Kind                    | Name                                                     | Status                          |
------------------------------------------------------------------------------------------------------------------------
| type                    | Crate                                                    | unchanged, 2 unsaved dependants |
|  |-> dependent property | the extent of 'Crate' contains the extent of 'Component' | not in packing-bay.ssc          |
|  |-> dependent property | extent of 'Crate'                                        | not in packing-bay.ssc          |
| property                | capacity of 'Crate'                                      | unchanged                       |
| property                | color of 'Crate'                                         | unchanged                       |
| property                | name of 'Crate'                                          | unchanged                       |
| type                    | Forklift                                                 | unchanged, 2 unsaved dependants |
|  |-> dependent property | range of 'Forklift'                                      | not in packing-bay.ssc          |
|  |-> dependent property | loaded of 'Forklift'                                     | not in packing-bay.ssc          |
| property                | the range of 'Forklift' contains the extent of 'Crate'   | unchanged                       |
| property                | in range of 'Forklift'                                   | unchanged                       |
| property                | registration of 'Forklift'                               | unchanged                       |
| property                | loaded of 'Crate'                                        | unchanged                       |
| rule                    | full crate                                               | unchanged                       |
| rule                    | forklift in range                                        | unchanged                       |

Rules engine trace

The Rules engine trace workspace in SmartSpace Config allows you to monitor the published business rule definitions in real time.

The Rules engine trace workspace

Click on BUSINESS RULE TRACE to display the workspace.

You can zoom in and out by using either Ctrl+mouse wheel or Ctrl+Plus sign and Ctrl+Minus sign.

Features of the Business rule trace workspace are described in the following sections.

Using Rules engine trace

Because tracing can have an adverse impact on the performance of the Business rules engine, it is not enabled by default or when the server restarts. Before you can see any trace results you must enable tracing. Click Start tracing on the server and confirm the operation. You can halt tracing, by clicking Stop tracing on the server. Also, when you close SmartSpace Config, if you still have tracing enabled, you will be asked to choose whether to leave it running or shut it down.

After you have enabled tracing, click Start listening. A green progress bar indicates that you are listening to the trace, and transactions will begin to populate the trace viewer.

Step forward and back through the trace using the playback buttons. A single definition is displayed at any time in the viewer and the current definition's position in the trace viewer is indicated by a green arrow.

You can also double-click a definition's name in the trace viewer to go directly to its contents.

Using Breakpoints

You can add breakpoints to an event by double-clicking its name in the set breakpoints list and displaying the definition in the viewer. Click an action (indicated by brown text) in the code to add a breakpoint. To remove a single breakpoint, display the definition and click on the breakpoint icon or the action. You can remove all breakpoints you have set by clicking Delete breakpoints and confirming the deletion.

You can also double-click a property to add breakpoints wherever that property is set.

To enable breakpoints, click Options and check Stop listening when a breakpoint is hit.

Breakpoints are highlighted in definitions, and events with breakpoints are identified, by one of the following symbols:

Copying Trace Data

To copy trace data to the Clipboard, click Copy trace to clipboard and the trace data for all tests currently listed is copied. Clear the contents of the trace viewer by clicking Clear.