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.

Name Type Required Description
kind "EntityDataStore" Yes A constant, EntityDataStore.
properties Dictionary<string, EntityDataStorePropertyConfig> Yes Define the schema of the entities. For every entry key there must be a matching property
persistToStore string No 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 EntityDataStorecreated in another project. TheEntityDataStoreshould already exist in the other project. The user that uses the solution should have at leastCan 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.
entities List<Dictionary<string, any>> | ImportedEntities No Define entities as static records or load entities from a csv file. Entities should match the schema defined by properties. This option is ignored when persistToStore is defined.
entityTypes Dictionary<string, EntityType> No A dictionary of objects for configuring additional entity type schemas.
subscribe List<EntityDataStoreSubscribe> No A list of objects for subscribing the EntityDataStore block to other blocks.

ImportedEntities

Name Type Required Description
fromCsvFile string Yes

EntityType

An object for configuring an entity type. Entity types always represent objects. Use a Reference property to place an entity type into another entity.

Name Type Required Description
properties Dictionary<string, EntityDataStorePropertyConfig> Yes A dictionary of objects for configuring the properties of the entity type.
filters Dictionary<string, EntityDataStoreFilterConfig> No A dictionary of objects for configuring filters of entitytypes. The filters are used to generate a filtered list of entitytype data (nested entities). Valid types are search, contain, andequal. 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.

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.

ReferenceSchema

An object for configuring a property of type Reference in an entity. This property is always represented as a list of the objects matching the schema of the referenced entityType. Reference objects can be selected and edited independently from the rest of the entity.

Name Type Required Description
type "Reference" Yes A constant, Reference.
entityType string Yes A reference to the entityType specified in the entityTypes
default List<Dictionary<string, 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.

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.

AutoIdSchema

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

Name Type Required Description
type "AutoId" Yes A constant, AutoId.
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 integer | 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.

ImageSchema

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

Name Type Required Description
type "Image" Yes A constant, Image.
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 Image | 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.
Image

An object representing an asset that stores the image. You can load image paths from a CSV file.

Name Type Required Description
path string Yes A path to the asset on the platform, this must be of an existing asset
project string Yes The name of the project that the asset belongs to
isPrivate boolean Yes A boolean specifying whether the image is a public or private asset.

ObjectSchema

An object for configuring a property of type Object in an entity data store. Objects are simple data structures to hold data and cannot be used to select and filter.

Name Type Required Description
type "Object" Yes A constant, Object.
properties Dictionary<string, EntityDataStorePropertyConfig> Yes A dictionary of objects for configuring the properties of this object.
default null | Dictionary<string, 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.
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.

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.

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" | InsertAtAction 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.
useFiltersFromEntityType string No A string specifying the EntityType from which the filters should be applied. The filters are configured in the EntityDataStore EntityTypes.
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.
select boolean No A boolean, allows selecting the entity after performing the action.

InsertAtAction

Allows inserting a new nested entity into an existing data entity.

Name Type Required Description
type "InsertAt" Yes A constant, InsertAt.
at List<string> Yes A list of strings specifying a relative path from the current selected document.

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.
useFiltersFromEntityType string No A string specifying the EntityType from which the filters should be applied. The filters are configured in the EntityDataStore EntityTypes.
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.