Entity Configuration

General Entity Configuration and Entity Parameters

An Entity has some general configuration properties the describe the Connector from which to retrieve it and how to map data to Entity Instances.

Based on the Connector used, additional Entity Parameters are required the configure in more detail how to retrieve and map data from the Connector to Entity Instances.

Operations allowed on Entity Instances can be globally activated or deactivated.

SBCS Master Data Hub Entity Configuration

  • Frontend Entity Name: The name of the Entity. This will be part of all REST API URLs for Entity Instances.
  • Connector: The Connector to use for the Entity. You can chosse from all configured Connectors.
  • Backend Entity Name: The name in the backend that 'contains' data for Entity Instances. This can be a table name, the name of an EspoCRM item, ... The Connector will use this value to build requests to the backend.
  • Property of Backend Entity used as Frontend ID: The property of the backend entity (column name, JSON field, ...) that contains the value to be used as the ID of the Entity Instance. This value will be part of the REST API URL of an Entity Instance.
  • Property of Backend Entity containing Backend ID: The property of the backend entity (column name, JSON field, ...) that contains the backend ID.

Entity Parameters

When you select a Connector, the system will fill the Entity Parameters table with some parameters that are required by the Connector to further specify how to retrieve Entity Instances. See the documentation of the Connector for the parameters required.

Operations

You can globally activate or deactive operations allowed for the Entity.

  • LIST: allow access to GET /<entityName>, includes filtered or paged requests
  • GET: allow access to GET /<entityName>/<entityID> to get a single Entity Instance
  • UPDATE: allow access to PATCH /<entityName>/<entityID> to change an existing Entity Instance
  • DELETE: allow access to DELETE /<entityName>/<entityID> to delete an existing Entity Instance
  • ADD: allow access to POST /<entityName> to add a new Entity Instance

Entity Properties

To make any data of Entity Properties visible on the REST API, Entity Properties must be configured. This is done on the Properties tab. Any number of properties can be configured but it is advisable to include at least two:

  • id: The value that uniquely identifies an Entity Instance on the REST API.
  • displayName: The name of the Entity Instance that is used as its visible name.

All other properties are optional.

Every property has three required parameters:

  • Frontent Name: The name of the property to be used in the REST API JSON representation of the Entity Instance.
  • Type: The type of the property. Can be BOOLEAN, DATE, DATETIME, INTEGER, FLOAT, STRING.
  • Backend Property: The property on the backend (database table column, JSON element, ...) that contains the data of the property.

Four checkboxes control what operations are allowed on the property:

  • Mandatory: If set, this property is required for an Entity Instance. This is important when creating a new Entity Instance using a HTTP POST request.
  • Settable: If set, this property can be set or changed by a REST API client.
  • Visible: If set, this property is included in the JSON representation as returned by a request to GET /<entityName>/<entityID>.
  • Visible in List: If set, this property is included in the JSON representation as returned by a request to GET /<entityName>.

The Method column is optional. It can be used to define a Method to execute on the raw value to convert it to the actual value (see below).

SBCS Master Data Hub Entity Properties

Methods

The following methods are supported to convert the raw value of a property to the value used for the property.

The string of a method can contain placeholders that are expanded before the method is executed. The syntax for placeholders is ${<placeholder>}. Supported forms of placeholder are:

  • The frontend name of a different property. Example: ep:${scopeName}.id is expanded using the value of the property scopeName, scopeName=Tenant will expand this placeholder to ep:Tenant.id.
  • A reference to the backend property used as frontend property of a different entiy. Example: In ep:${parentType}.id:${backendPropertyUsedAsFrontendId:parentType} the first placeholder will be expanded using the previous rule. The second placeholder ${backendPropertyUserAsFrontendId:parentType} will be expanded to the name of the backend property used as frontend property of the entity identified by the own property parentType.

Entity Relations

An Entity can be have relation to other Entities. These relations are configured on the Relations tab.

Every relations has three properties:

  • From Backend Property: The backend name of the Entity Instance property to use as key to build the relation.
  • Relation To: The name of the the Entity to build the relation to.
  • To Backend Property: The backend name of the Entity Instance property to use as key to build the relation to.

Four checkboxes control what operations are allowed on the property:

  • List: Shall these relation Entity Instances be listable? GET /<entity-from>/<id-from>/<entity-to>.
  • Get: Shall a single related Entity Instances be reachable? GET /<entity-from>/<id-from>/<entity-to>/<id-to>.
  • Delete: Shall a single related Entity Instances be deletabe? DELETE /<entity-from>/<id-from>/<entity-to>/<id-to>.
  • Delete: Shall a new related Entity Instances be addable? POST /<entity-from>/<id-from>/<entity-to>.

SBCS Master Data Hub Entity Relations