Block: EntityDataStore

A EntityDataStore block for configuring a store in which a list of data entities can be saved.
Tags:

Overview

An EntityDataStore block is used for configuring a data store that can contain a list of data entities that share the same properties. The properties property defines the entity properties. This set of properties is typically referred to as the “schema” for the data store.

This block is not visible in the user interface and should therefore not be included in the areas of the frame layout. A data entity store is often linked to an EntityTable block that displays a table of entities. In the entity data store, entities can be marked as being “selected”. This allows certain actions to be performed on a selected entity in the data store. For example, clicking an “Edit” button may allow the selected entity to be displayed for editing.

The entity data store also supports searching and filtering operations. The filters property contains a dictionary of filter objects. Filters of type search are used for configuring text-based search functionality. Filters of type equal and contains are used for configuring other types of filtering functionality. Entities that satisfy the filter conditions of all filters are maintained in a separate filtered list.

An entity data store can be made persistent by setting the persistToStore property. Doing so saves the data to a database in the cloud. Any data in the data store is then be saved, even when user logs out or the browser window is closed. This allows data to be persisted across different sessions over time. For example, a solution can be configured that allows a user login and save their project settings and setup.

When persisting data, care must be taken when changing the data schema:

  • If additional properties are added, then the existing entities receive a null value for those properties.
  • If existing properties are removed, then the existing entities have properties that are not part of the schema.

Example

Below is an example configuration. Example of a non-persistent entity data store.

kind: Solution
version: v0
router:
  kind: Router
  routes:
    - frame: home-frame
frames:
  home-frame:
    kind: Frame
    contents:
      my-entity-data-store:
        kind: EntityDataStore
        properties:
          my-prop-a:
            type: Number
          my-prop-b:
            type: String
        entities:
          - my-prop-a: 123
            my-prop-b: Hello
          - my-prop-a: 456
            my-prop-b: World

Example of a persistent entity data store.

kind: Solution
version: v0
router:
  kind: Router
  routes:
    - frame: home-frame
frames:
  home-frame:
    kind: Frame
    contents:
      my-persistent-entity-data-store:
        kind: EntityDataStore
        persistToStore: my-store-name
        properties:
          my-prop-a:
            type: Number
          my-prop-b:
            type: String

EntityDataStoreConfig

An object for configuring a data store for storing a list of entities. The data store can be a local data store or a persistent data store. With a local data store, entities are discarded when the browser session is ended. With a persistent data store, entities are saved in the cloud so that they can be retrieved next time the user logs in.

PersistedEntityDataStoreConfig

Name Type Required Description
kind "EntityDataStore" Yes A constant, EntityDataStore.
persistToStore string Yes A string specifying the name of the cloud data store to be used for persisting the EntityDataStore. If persistToProject` is not set and a data store with this name does not exist, then a new store will be created in this project. Otherwise, the existing store will be used.
persistToProject string No A string specifying the name of the project to be used for persisting the EntityDataStore. This allows this solution to read and write entities to an EntityDataStore created in another project. The EntityDataStore should already exist in the other project. The user that uses the solution should have at least Can use permission for both projects.
filters Dictionary<string, EntityDataStoreFilterConfig> No A dictionary of objects for configuring filters. The filters are used to generate a filtered list of entities. Valid types of filters are search, contains, and equal. If multiple filters are defined, then the filters are combined with an ‘and’ condition. To be included in the filtered list, entities therefore need to satisfy all filter conditions.
properties Dictionary<string, EntityDataStorePropertyConfig> Yes A dictionary of objects for configuring the properties that entities can have. The dictionary keys are strings specifying the property names. The dictionary values are objects for configuring property data types.
subscribe List<EntityDataStoreSubscribe> No A list of objects for subscribing the EntityDataStore block to other blocks.

EntityDataStoreFilterConfig

An object for configuring a filter for an entity data store. Valid types of filters are search, contains, and equal.

EqualFilter

An object for configuring an equal filter for an entity data store. Filtering values will be retrieved from other blocks and used to generate a filtered list of entities. For filters of type equal, both the control value and the property value must be primitive types such as numbers and strings. An entity will be added to the filtered list if the control value and property value are equal.

Name Type Required Description
type "equal" Yes A constant, equal.
property string Yes A string specifying the name of a property in the entity data store.

ContainsFilter

An object for configuring an contains filter for an entity data store. Filtering values will be retrieved from other blocks and used to generate a filtered list of entities. For filters of type contains, the control value must be a list of values.’ This means that the control must be a checkbox. The property value must be a primitive type such as a number or a string. An entity will be added to the filtered list if the property value is found in the control value list.

Name Type Required Description
type "contains" Yes A constant, contains.
property string Yes A string specifying the name of a property in the entity data store.

SearchFilter

An object for configuring a search filter for an entity data store. Filtering values will be retrieved from other blocks and used to generate a filtered list of entities. For filters of type search, the control value and property value must both be strings. For the control, a TextInput element is typically used. An entity will be added to the filtered list if a text search of the control value in any of the property values gives a positive result. The text search is case insensitive.

Name Type Required Description
type "search" Yes A constant, search.
properties List<string> Yes A list of strings specifying the names of properties in the entity data store.

EntityDataStorePropertyConfig

Entities values must have a predefined type.

NumberSchema

An object for configuring a property of type Number in an entity data store.

Name Type Required Description
type "Number" Yes A constant, Number.
nullable boolean No A boolean specifying whether the property can have a value of null. If true, then the default value can also be set to null.
default number | null No A default value for the property. If a new entity is inserted into the data store, and no value is given for this property, then the default value is used. Changing the default value does not affect existing entities in the data store.

BooleanSchema

An object for configuring a property of type Boolean in an entity data store.

Name Type Required Description
type "Boolean" Yes A constant, Boolean.
nullable boolean No A boolean specifying whether the property can have a value of null. If true, then the default value can also be set to null.
default boolean | null No A default value for the property. If a new entity is inserted into the data store, and no value is given for this property, then the default value is used. Changing the default value does not affect existing entities in the data store.

StringSchema

An object for configuring a property of type String in an entity data store.

Name Type Required Description
type "String" Yes A constant, String.
nullable boolean No A boolean specifying whether the property can have a value of null. If true, then the default value can also be set to null.
default string | null No A default value for the property. If a new entity is inserted into the data store, and no value is given for this property, then the default value is used. Changing the default value does not affect existing entities in the data store.

MapMarkerSchema

An object for configuring a property of type MapMarker in an entity data store.

Name Type Required Description
type "MapMarker" Yes A constant, MapMarker.
nullable boolean No A boolean specifying whether the property can have a value of null. If true, then the default value can also be set to null.
default null | MapMarker No A default value for the property. If a new entity is inserted into the data store, and no value is given for this property, then the default value is used. Changing the default value does not affect existing entities in the data store.
MapMarker

An object representing a MapMarker, defining a single geospatial location on a map. When the user selects locations in the Map block, MapMarker objects can be retrieved. Map markers can also be stored in an EntityDataStore.

Name Type Required Description
id number Yes The ID of the map marker
longitude number Yes The longitude of the geospatial location, in degrees.
latitude number Yes The latitude of the geospatial location, in degrees.

ArraySchema

An object for configuring a property of type Array in an entity data store. An array is a list of values that all have the same type.

Name Type Required Description
type "Array" Yes A constant, Array.
items EntityDataStorePropertyConfig Yes An object for the type of values that can be stored in the array. Valid types are Number, String, MapMarker and Array.
nullable boolean No A boolean specifying whether the property can have a value of null. If true, then the default value can also be set to null.
default null | List<any> No A default value for the property. If a new entity is inserted into the data store, and no value is given for this property, then the default value is used. Changing the default value does not affect existing entities in the data store.

GeometryObjectSchema

An object for configuring a property of type GeometryObject in an entity data store.

Name Type Required Description
type "GeometryObject" Yes A constant, GeometryObject.
nullable boolean No A boolean specifying whether the property can have a value of null. If true, then the default value can also be set to null.
default null | GeometryObject No A default value for the property. If a new entity is inserted into the data store, and no value is given for this property, then the default value is used. Changing the default value does not affect existing entities in the data store.
GeometryObject

An object representing a geometric object that can be visualized in the viewer.

Name Type Required Description
type "Arrow" | "Asset" | "Box" | "Brep" | "Line" | "Mesh" | "NURBSCurve" | "NURBSSurface" | "Point3D" | "Polyline" | "Rectangle" | "Sphere" | "Sprite" | "Text3D" | "DimensionLine" | "Tag" | "Arrow2" | "DimensionAngular" Yes A constant specifying the type of object.
value Dictionary<string, any> Yes The data representing the object.

UuidSchema

An object for configuring a property of type Uuid in an entity data store.

Name Type Required Description
type "Uuid" Yes A constant, Uuid.
nullable boolean No A boolean specifying whether the property can have a value of null. If true, then the default value can also be set to null.
default string | null No A default value for the property. If a new entity is inserted into the data store, and no value is given for this property, then the default value is used. Changing the default value does not affect existing entities in the data store.
auto "onCreate" No A boolean specifying whether to generate a new value automatically before inserting when the property is not defined.

LocalEntityDataStoreConfig

Name Type Required Description
kind "EntityDataStore" Yes
properties Dictionary<string, EntityProperty> Yes Define the schema of the entities. For every entry key there must be a matching property
entities List<Dictionary<string, any>> | ImportedEntities Yes Define entities as static records or load entities from a csv file. Entities should match the schema defined by properties
subscribe List<EntityDataStoreSubscribe> No A list of objects for subscribing the EntityDataStore block to other blocks.

EntityProperty

Name Type Required Description
type "String" | "Number" | "Image" | "AutoId" Yes Entities values must have a predefined type. If type is set to AutoId the value will be autogenerated

ImportedEntities

Name Type Required Description
fromCsvFile string Yes

EntityDataStoreSubscribe

EntityDataStoreControlPanelSubscribe

An object for configuring a subscription from a EntityDataStore block to a ControlPanel block. The subscription allows the entities in the entity data store to be selected and filtered based on the data in the control panel.

Name Type Required Description
kind "ControlPanel" Yes A constant, ControlPanel.
frame string Yes A string specifying the name of the frame in which the ControlPanel is located.
source string Yes A string specifying the name of the ControlPanel.
action "Insert" | "Update" No A constant specifying the action to be performed when the control panel is submitted. Valid options are Insert and Update. - Insert: A new entity is created in the entity data store. - Update: The selected entity in the entity data store is updated.
filterByControls List<string> No A list of strings specifying names. Each name must match a name of control in the control panel and a name of a filter in the entity data store. The filter and the value of the control are used to generate a filtered list of entities. For filters of type equal, an entity is added to the filtered list if the control value and property value are equal. For filters of type contains, an entity is added to the filtered list if the property value is found in the control value list. For filters of type search, an entity is added to the filtered list if a text search of the control value in any of the property values gives a positive result.

EntityDataStoreEntityTableSubscribe

An object for configuring a subscription from a EntityDataStore block to a EntityTable block. The subscription allows entities in the entity data store to be selected or deleted by clicking buttons in the entity table. The columns in the entity table can also include filter controls that allow the user to filter the entities that are displayed in the table.

Name Type Required Description
kind "EntityTable" Yes A constant, EntityTable.
frame string Yes A string specifying the name of the frame in which the EntityTable is located.
source string Yes A string specifying the name of the EntityTable.
selectOn List<string> No A list of strings specifying the names of TableButton columns in the entity table. Clicking a button in a table row results in the corresponding entity in the entity data store becoming selected. Selecting an entity results in previously selected entities becoming unselected.
filterByColumns List<string> No A list of strings specifying names. Each name must match a name of a column in the entity table and a name of a filter in the entity data store. In the entity table, the column filter should be MultipleChoice. In the entity data store, the filter should be of type contains. The MultipleChoice column and the contains filter are used to generate a filtered list of entities.

EntityDataStoreMapSubscribe

An object for configuring a subscription from an EntityDataStore block to a Map block. The subscription allows the entity data store to retrieve a MapMarker object containing the longitude and latitude of the selected point in the map.

Name Type Required Description
kind "Map" Yes A constant, Map.
frame string Yes A string specifying the name of the frame in which the Map is located.
source string Yes A string specifying the name of the Map.
property string Yes A string specifying the name of the property in which to store the map markers.
action "updateSelected" Yes A constant specifying the type of action to perform. The only valid option is updateSelected. This stores the retrieved MapMarkers in the selected entity in the entity data store.

EntityDataStoreViewerSubscribe

An object for configuring a subscription from an EntityDataStore block to a Viewer block. The subscription allows the entity data store to retrieve geometry from the viewer and store it.

Name Type Required Description
kind "Viewer" Yes A constant, Viewer.
frame string Yes A string specifying the name of the frame in which the Viewer is located.
source string Yes A string specifying the name of the Viewer.
fromGroups List<string> Yes A list of strings specifying the names of ‘groups’ in the viewer. These groups are generated when geometry is drawn in the viewer or imported from a Grasshopper model. The geometry in the specified groups will be retrieved.
action "updateSelected" Yes A constant specifying the type of action to perform. The only valid option is updateSelected. This stores the retrieved geometry in the selected entity in the entity data store. The entity should have properties with names that match group names specified in fromGroups.

EntityDataStoreRouteSubscribe

An object for configuring a subscription from the Route

EntityDataStoreRouteFilterAndSelectSubscribe

An object for configuring a subscription that may filter or select entities using the Route

Name Type Required Description
kind "Route" Yes A constant, Route.
urlParameters List<string> Yes A list of strings specifying the query parameters to retrieve from the route.
action "filter" | "selectMatching" Yes A constant specifying the action to be performed when the route query parameters are retrieved
- filter: Filters the entities using the values selected by the route.
- selectMatching: Selects all entities that match all route query parameters. Note that the values must equal exactly.
EntityDataStoreRouteInsertSubscribe

An object for configuring a subscription that may insert a new entity using the Route

Name Type Required Description
kind "Route" Yes A constant, Route.
urlParameters List<string> Yes A list of strings specifying the query parameters to retrieve from the route.
action "Insert" Yes A constant specifying the action to be performed when the route query parameters are retrieved.
Valid options are Insert.
select true | false No A boolean, allows selecting the entity after performing the action.