Web maps

Searches and Web maps

Searching by Property

A “search” in SmartSpace is a configured query that uses a single property to retrieve a set of objects. These are returned in a table, along with selected other property values of each object. This result table can then be presented to users in different ways, including displaying the objects on a web map or tabulating them in a web form.

Some examples of searching by property include:

1. Retrieving all objects of a particular type by their unique “name” property
2. Retrieving all objects of a particular type based on a string property called “country code”
3. Retrieving all objects of a particular type based on an integer property that’s being used as a counter

In addition, the search can include an optional filter specified by the user to restrict the results returned. This allows you to filter the results using a property that is common to all of the objects in the set. For example:

• Filtering the result set for example B by a common string property, such as a category value
  In this way, users can choose to retrieve only objects that have the values [DE, USA, UK] but ignore objects that have the values [JP, FR, SP].
• Filtering the result set for example C by integer values of the property
  An example would be to retrieve only objects who have their counter value = 5.

Any property can be used as the basis for a search, and if a complex property is used, multiple filters can be defined based on the property columns, to help filter the results further.

The key facts to remember about these “searches” are:

• They are predefined in structure
• They are based on a single type
• Their results can be presented in different visualization forms

Detailed information about configuring searches is available in Configuring web searches.

Applying Representation Modes to Objects on the web map

To be able to display the objects returned by a search filter in the SmartSpace web map, the web map must be told which representations to use for the objects. You apply representations to the objects in a result set by choosing one (or several) representation modes which have previously been allocated to objects of that type (see Adding a representation to a type). This has the effect of overlaying the origin of the representation referenced by the representation mode onto the origin of the object in the web map. A single object can have multiple representation modes included for any particular search as shown below:

For examples of using representation modes to add labels, see Adding a label to the representation of an object.

The use of representation modes is most useful when it is possible to assign them to and remove them from objects based on their status, which requires the Business rules engine to be licensed.

Foreground and Background Searches

Search filters allow you to retrieve a single set of objects based on properties of that class of object. But what if you wanted to display more than one object type on the web map at once? To this end, SmartSpace supports the concept of foreground and background searches, which allow the primary search (called the foreground search) to call other searches (called background searches) in order to display different sets of objects alongside the objects returned in the primary search.

An example might be a foreground search for objects of type Product and a background search for objects of type Workstation. This would allow you to visualize where all the products are, and also see which workstations are currently occupied or available, as shown above.

Foreground and background representation modes

When a search filter is expected to be used as both a foreground and a background search, as described above, it can be useful to switch between different representations depending on how the search was run. An example would be a foreground search that retrieves and renders all objects with a particular property value (say a Boolean property set to true) onto the web map. Then, because knowing the location of objects of the same type that didn't meet the criteria provides a useful decision-making context, you might also want to see them rendered on the map as well. How would you distinguish between the object returned in the primary search versus objects returned in the secondary (background search)?

In this case SmartSpace has two built-in representation modes called foreground and background. If both foreground and background rep modes are added to a single search definition, the foreground rep mode is displayed when the search is run as a foreground search and, similarly, the background rep mode is displayed when the search is run as a background search. In this way it is possible to use a different representation for objects depending on which mode the search is run in, and visually distinguish between sets of objects displayed on the map.

Views

When a search filter is used to display located objects in the web map, an additional spatial parameter must be configured which provides a “spatial window” for objects returned by the search. The effect of adding this window is that objects that don’t fall inside the window (by virtue of their location) are removed from the result set and not displayed on the map. This windowing capability is the result of configuring one or more “Views” for the site. Views are based on the cellular structure of the platform, so can be the whole site, or specific parts of the site. This makes it possible to segment a site into viewable areas which can be assigned to different user roles or departments, for example returning cars in the "Rework" area for the rework team.

Web maps at runtime

The SmartSpaceweb map is a browser-based rendering of a customer site including a background site representation with one (or many) object types overlaid. You can move around the map using your mouse or touch screen to pan and zoom and select objects to view or even edit their properties.

The objects displayed in the web map are those returned by some predefined search, as described in Searches and Web maps. You can select or change searches using a drop-down menu at the top left of the map screen. You only see searches which are part of the roles of which you are a member.

When you select and run a search, the objects that match the search are listed in a results view on the left-hand side of the screen. The results view includes columns for properties relevant to the search (these are configurable: see Configuring web searches). Click on any object in the results view and the map view pans and zooms to the location of the object and a circular green halo highlights it. (The green halo is the default way to highlight a selected object. This can be modified by choosing a different representation in the search definition. See Customizing how selected objects are highlighted on the web map).

Clicking on the object’s representation, or double clicking in the result list, pops up a properties window at the top right of the web map. This window displays more details about the selected object. The properties shown are configurable (see Configuring web searches) and additionally can be made editable to support user input.

Background Object Locations

If a background object location is moved using OBJECT PLACEMENT, the new position may not be reflected on the web map. This is because background objects are not expected to move dynamically, and their positions are cached in the most recent search results displayed in the web map, rather than being updated regularly.

If you move a background object and want to ensure it is immediately updated on the web map, you can either change any property that is included in the Summary results, for any object, or restart the Visibility/web map client interface service.

Dates and Times

When inputting or amending dates, click the date to display the date and time dropdown:

Here you can:

• Select the date from the calendar, and set the time using the sliders

• Type a date and time directly (not available in mobile device mode):

  • Use / to separate parts of the date and : to separate hours and minutes
  • Time is in 24-hour format

  • Seconds are permitted if the details format (in WEB SEARCHES in SmartSpace Config) has seconds precision.

• Click Now to select the current date and time

Click Done to save the changes.

Selectable Parameters

Searches can be configured to group all the values returned for the subject property and present them as selectable parameters. You select these from a dropdown and depending on the configuration of the search you will either be allowed to choose one parameter only, or multiple parameters. For example, here the “Assets (categories)” search groups objects of the Product type by a two-letter category code. At runtime, you can select more than one category from the dropdown.

Note: At runtime, if an object does not have a value for the property specified in the choice parameter, it will never be returned by the search, even if no values are selected by the user.

When the Business rules engine is licensed, it is also possible to generate notification events. These are automatically pushed to the web map and appear in a list below the object properties window. You can click on individual notifications which (if configured to do so) will cause the map view to jump to the location of the object that generated the event. You can acknowledge and clear notifications individually, or all together using a Clear All button.

Passing parameters to Web maps

You can display a web map using a given configured search so that it immediately searches for an object, or multiple objects, for immediate display without the need for further interaction. This can be achieved by specifying the object and search in an extended URL. You can use a search in this way even if it was not set to be Visible in its definition in the Web searches workspace.

From version 3.7, you can additionally specify the default view to display in the extended URL.

You can only use a search which is authorized by your role(s), and the web map will warn you if a requested search is not available.

Parameter Specification

Parameters are specified by adding an "anchor" part to the normal web map URL. This is the part of the URL after a '#'.

The anchor text must contain a JSON structure, encoded using the standard URL encoding specified in RFC 3986. The structure has the following form:

{"Search":"search name","Role":"role name","View":"view name", "Values":["param1",...]}

• The search name is the untranslated name of the search (i.e. the name in the default language).

• The role is an optional argument. When a user has a given search assigned for more than one role, this can be used to run the search as one of those roles.

• View is an optional argument that can be given as an object ID or the name of the view.

  This is the default view to display. If other parameters of the search mean that the only results are in other views visible to the role, then one of the other views will still be shown. This is to avoid confusion when the search parameters are used to look for objects not currently located in the default view.

• The values are entered into each search parameter in the order given.

• If a parameter is a selection, the value given should be the text of the selection required.
• If a parameter is a date, the value should be given in the format for the locale of the browser.

For example, a search called Vehicles is executed with the parameter VIN20132372 as follows:

{"Search":"Vehicles","Values":["VIN20132372"]}

This is encoded to produce the following string:

%7B%22Search%22%3A%22Vehicles%22%2C%22Values%22%3A%5B%22VIN20132372%22%5D%7D

So if the SmartSpace web site is http://smartspace.internal/SmartSpace, then the URL to execute this search is:

http://smartspace.internal/SmartSpace/IF#%7B%22Search%22%3A%22Vehicles%22%2C%22Values%22%3A%5B%22VIN20132372%22%5D%7D

Search Execution

When a search returns only a single row as a result, that row is selected and the resulting object zoomed if it has a location.

If the parameter is incorrectly formed, a warning is generated.

Alternative URL Encoding

Some online tools generate URI encoded strings that use "+" as the encoded form of a space. These formats may not be correctly decoded by the web map, so if your search or role has a space in its name, and it doesn't seem to be working, check that the encoded string doesn't have "+" in place of each space. The correct form uses "%20" to encode a space.

For example: if the search name was "Vehicles with faults" and the string looks like this, then it is wrong:

%7B%22Search%22%3A%22Vehicles+with+faults%22%2C%22Values%22%3A%5B%22VIN20132372%22%5D%7D

The correct form would be:

%7B%22Search%22%3A%22Vehicles%20with%20faults%22%2C%22Values%22%3A%5B%22VIN20132372%22%5D%7D

Displaying tag locations on the web map

First released in version: 3.5 Last updated in version: 3.10

Use the "Tags" search to display the locations of tags on the web map.

This search is built into SmartSpace and cannot be modified in SmartSpace Config other than to be added to roles and to have its priority set. Additionally the search does not run automatically: in the web map you must click Search after specifying the required parameters. Thereafter, the search refreshes every 60 seconds and the details window refreshes every second.

You can refine the search by specifying a tag ID, tag type, location age, and ownership.

To display tag locations:

1. In the Map screen in SmartSpace Web, choose Tags from the list of searches.

   If you cannot see the Tags search in the list, it may not have been assigned to your role.

2. Choose the Location age.

   This can be:

   • Any location age to display tags located at any time
   • Under one minute to display tags located within the last minute
   • Under one hour to display tags located within the last hour (the default)
   • Under one day to display tags located within the last day
   • Under one week to display tags located within the last week

3. You can further refine the search by specifying:

   • Tag Id

     Type a complete or partial ID of the tag(s) to be displayed.

   • Ownership

     

     From the dropdown, choose:

     • for assigned tags only
     • for unassigned tags

     Leave unset for all tags.

   • Tag type

     This can be one of the tag types defined for your system, or No tag type to display tags for which a tag type has not been defined. Leave unset for all tags.

4. Click Search and the web map displays. Located tags are listed on the left-hand side of the screen and you can display the following details for a selected tag: tag ID, last located date/time, the assigned owner of the tag (if there is one), and tag type (if set).

   

Customizing how selected objects are highlighted on the web map

First released in version: 3.8.1

Dynamic color in object representations on the web map

First released in version: 3.2

By using suitably configured reps, and types with a color property, you can display objects on the web map with different colors associated with different object instances. The key to achieving this is to create a "fillable" graphic that can be associated with a type and custom representation mode in a search. To change colors of the reps, the map sets the 'fill' style at the top level of the SVG to a different color for each object rendered. This fill style is then inherited by elements within the SVG that do not have their own fill style set. So to make this work you need an SVG for which the key elements, and their parents, have no fill specified.

You can also make objects' colors editable directly on the web map. However, this configuration is most powerful when it is possible to make changes to objects' colors based on their status: this can be done using the Business rules engine, if licensed, or by external integration.

The following section gives an example of how to assign dynamic color properties to objects.

1. To display objects with configurable colors, you need appropriately formatted vector graphics (.SVG) created using software such as Inkscape or Illustrator. The example below uses Inkscape. If you use a different editor, such as Illustrator, the process will be different: refer to the relevant user documentation for the software you are using. For an example of creating a fillable SVG in Illustrator, see .

   To make the image fillable:

   • Select it and in the Fill and Stroke dialog, ensure the graphic has its fill set to undefined (click the button).
   • Choose Resize Page to Selection from the Edit menu to crop the page.
   • Save the image in Plain SVG format.

   The example below shows workbench.svg prepared for use as a fillable graphic.

   

2. You can check the settings by opening the SVG in an editor such as PSPad. For example:

   

   The style on the rect element does not specify a fill color, and neither do any of its parent elements.

3. In SmartSpace Config, import the graphic using the MODEL IMPORT task, scale it and set the origin. For example:

   

4. In SmartSpace Config, use the TYPES / OBJECTS task to add a color property to a type. Select the type and then double-click <Create new property>. In the dialog, enter color for the property's name and make its type String. Add some objects of this type and give them colors using one of the following formats:

   • A named color supported by all browsers. There are many web references for this list of colors, for example: https://www.w3schools.com/colors/colors_names.asp.
   • A hex color, such as “#FF0000”, where the bytes are red, green, blue.
   • A transparent color using the form “rgba(128,0,233,0.5)”. Here the first three parts are red, green and blue components in the range 0-255, and the last part is a floating point transparency (alpha) in the range 0-1, where 1 is a solid color, and 0 is completely transparent.

   In the example below, the Workbench type has a color property, and several instances of the type with their individual colors have been added:

   

5. In SmartSpace Config, use the MODEL ASSIGNMENT task to assign the fillable rep to the type and give it a representation mode. Double-click <Add new type rep>, choose the type and rep and enter a name for the custom rep mode. In the example below, the Workbench type is chosen and the workbench model is assigned to it along with the colored rep mode:

   

6. In SmartSpace Config, use the WEB SEARCHES task to add the rep mode and the color field to a search:

   • In the Representation modes section of the workspace, double-click <Add mode>, choose the rep mode you created in the MODEL ASSIGNMENT task and click Add.
   • Drag the color property you want to display into the Representations section of the workspace.

   In the example below, a search has been created based on the color of the workbench, the custom rep mode colored has been added to the list of modes and the property color of <Workbench> has been added to the representations.

   

7. In SmartSpace Web, when the search is run, each located object is filled with the color defined for it. For example:

   

Adding a label to the representation of an object

By using suitably configured reps and types, you can display objects on the web map with a label associated with each object instance that contains a value taken from a simple property of the object type. The key to achieving this is to ensure the Title field for the object's representation in the search configuration matches the ID of the field in the .SVG file used to provide the "fillable" label. For example, here the Label.svg file has an ID name which has been associated with a rep in the WEB SEARCHES task:

Some care should be taken when adding labels to SVGs due to how SmartSpace handles their display on the web map.

When SVGs with labels are used as representations, SmartSpace attempts to keep the text the right way up when it displays objects using this rep on the web map. This may mean that the rep is rotated differently to the associated object. For example when an object with an SVG with a label is rotated by 180 degrees, the rep gets rotated by 360 degrees to prevent label text displaying upside down. This flipping of the rep's orientation may cause unexpected results with asymmetric reps.

If reps of this type are used as background maps, this behavior may be especially confusing for users as part of their frame of reference may suddenly rotate. Because of this, it is recommended not to add text labels in SVGs of background maps. Instead, if labels are required, create them as separate background objects relative to the background map.

The following example shows how to add labels to identify objects on the web map.

1. To add a label with configurable text, you need to create an appropriately formatted vector graphic (.SVG) with a field to fill in, using software such as Inkscape or Illustrator. The example below uses Inkscape. If you use a different editor, such as Illustrator, the process will be different: refer to the relevant user documentation for the software you are using. For an example of creating a fillable SVG in Illustrator, see .

   In the example below, the graphic has the following properties:

   • a 'text' element to fill in whose ID is name.
   • the filename Label.svg

   

    

2. In SmartSpace Config, import the graphic using the MODEL IMPORT task, and scale it. Set the origin of the rep to give you the offset you want from the object it will be labeling.

3. In SmartSpace Config, use the MODEL ASSIGNMENT task to assign the rep to a type and enter a custom rep mode. Double-click <Add new type rep> and in the Representations assigned to types dialog, select a type and a mode, and type the name of the custom rep mode.

   In the example below, the rep Label.svg has been assigned to the Production Order type and has been given the custom rep mode label.

   

4. In SmartSpace Config, use the WEB SEARCHES task to add the rep mode and the fillable field to your search:

   • In the Representation modes section of the workspace, double-click <Add mode>, choose the rep mode you created in the MODEL ASSIGNMENT task and click Add.
   • Drag the simple property you want to display into the Representations section of the workspace. Set the Title to the ID of the SVG field you want to fill by slowly double-clicking in the Title column beside the property and typing the name of the field.

   In the example below, the custom rep mode label has been added to the list of modes and the property name of <ProductionOrder> has been added to the representations and its title has been set to name.

   

5.  In SmartSpace Web, when the search is run, the label by each object is filled with the value of the simple property. Here each Production Order object on the map is identified by its name:

   

Controlling the Display of Small Label Representations

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
				<!-- Created with Inkscape (http://www.inkscape.org/) -->
				<svg
				xmlns="http://www.w3.org/2000/svg"
				version="1.2"
				width="1675.3929"
				height="909.06171"
				id="svg2"
				minSize="60">
				...
		</svg>

Making objects unclickable on the web map

First released in version: 3.3

By using a rep mode whose name begins with unselectable, you can display objects on the web map which cannot be selected by clicking on them. One case where this is valuable is where a search returns both foreground and background objects, but the background objects are close to the foreground objects. Making the background objects unclickable makes it easier for users to select the foreground objects they are interested in so they can view their details.

The following section gives an example of how to go about this.

1. In SmartSpace Config, use the MODEL ASSIGNMENT task to assign the rep to a type and give it a representation mode. Double-click <Add new type rep> and choose the type and rep and enter a name for the custom rep mode that begins with unselectable.

   In the example below, the table type has the representation mode unselectable assigned and selected under Show in 2D.

   

2. In SmartSpace Config, use the WEB SEARCHES task to add the rep mode to a search. In the Representation modes section of the workspace, double-click <Add mode>, choose the rep mode you created in the MODEL ASSIGNMENT task and click Add. For example, the search below is based on the asset id property of the table type which has been associated with the unselectable rep mode:

   

Automatically recording who made a change to a property on the web map

First released in version: 3.6

If you want to keep track of who made a change to a settable property on the web map, or in a web form, you can create a pair of properties so that when a change is made to one, the identity of the user is automatically recorded in the other. This is achieved by creating a property called user changed tracked_property_name where tracked_property_name is the one for which the user making changes will be recorded. Only changes made in SmartSpace Web are recorded: updating properties in SmartSpace Config does not record the ID of the user making the change. The changes are made in the same transaction allowing you to robustly track who most recently updated a property. This information can then be used by business rules, or the "user changed" property can be logged to the database and used in reports.

In the following example, we will create the capability to record who last made a comment on tool objects. In TYPES / OBJECTS, we create the tool type, a string property called comment and, in order to record who has added a comment, a string property called user changed comment:

After the type and properties have been defined, the tool type is given a 2D representation for the web map and the comment property is made settable for those roles permitted to edit it. Note that we do not need to make the "user changed" property settable.

Next, in the Web searches workspace, we create a search based on the name of <tool> : string with the "comment" and "user changed" properties added to the details view:

After we have added the search to the roles that will use it, we can view it in SmartSpace Web and add a comment to a tool: