Entity Definition

One of the main features Stryke provides for your apps is data persistence. Data is stored securely without you having to worry about the database or storage layers.

You define the structure of your data through entities. Entities are just like objects in traditional development or tables in a classic database: they allow us to relate data to real world concepts.

An entity represents a self contained structure that defines how data of a specific type is stored in an app.

For example, an entity can be a bicycle in a bike rental management app, or a receipt in a receipt tracking app.

You define an entity by specifying its fields, hence defining the template according to which your data will be stored.

As an example, the fields of a receipt entity could be: the amount of that receipt, the business that issued that receipt, the date on which it was issued, etc.

Defining entities

Entities are defined using a JSON document called "entity metadata". Entity metadata can be created and modified using the Entity Metadata Editor under the Stryke user interface or through the metadata API.

Entity Metadata Editor

Edit entity

The editor with which you create and edit your entity metadata has two modes:

Tree mode

Shows the JSON in a tree format. This view provides a structured way to look at the JSON representing your entity metadata as well as shortcuts to automate useful tasks.

You can use the buttons on the left hand sid of each line of the JOSN to:

reorder fields reorder fields

call up a menu with several editing utilities

  • inserting a new field
  • inserting a field of a specific type
  • duplicating an existing one
  • deleting a field

fields menu

Code mode

Alternatively the "code" mode offers a "raw-text" editor where you can type as you would normally do on any code editor. The code mode provides JSON syntax highlighting and autocomplete to guide you through the process of editing as well as to ability to copy/paste sections of the JSON or the entire definition.

fields code

Entity Metadata Properties

Below are the properties that need to be set on the entity metadata to define your entities.

entityName

The unique name of the entity. This name serves as a unique identifier of the entity in API calls.

title

A human friendly name for the entity. The value set on title to be shown in the app's UI.

description

A text description for the entity. The description will be used in the UI and Graphql docs to describe the entity.

alias

The definition of the naming pattern used when generating the alias of any record of this entity. If not specified the default value "[$]-{00000}" will be used. The alias pattern can be composed with any sequence of the following:

  • {sequence number} - with 0s as padding - eg: {000}
  • plain text - text to use directly in the alias - eg: TEST
  • [$] - the full entity name (limited to 15 chars) without spaces and all uppercase - eg: INSURANCEGROUP+

Example:

{
    "alias": {
    "format" : "TEST-{000}"
    }
}

output: TEST-001, TEST-012, TEST-934

{
    "alias": {
        "format" : "[$]__{00000)"
    }
}

output: MYENTITYNAME__00001, MYENTITYNAME__00012, MYENTITYNAME__00934

entityIcon

An icon representing this entity. This icon will be used in the app's UI and should be representative of the entity's concept.

Stryke uses Font Awesome's icons to represent entity. To set the icon value, the entityIcon property must be set to the name of a valid Font Awesome icon.

A full list of icons can be found here

Example:

{
    "entityIcon" : "calendar"
}

entityColor

The color to be used when representing this entity in the UI. Badges and in general identifiers for this entity will have this color.

The entityColor value is expected to be specified in hex format.

Example:

{
    "entityColor" : "#BD7CB4"
}

canHaveFiles

A boolean that defines if the entity will allow for files to be attached onto records of this type. Defaults to false if not set. More info about files on Stryke can be found here: Files

isPublic

A boolean that defines if the entity is public within the application. This controls whether access control rules should apply to an entity or not.

Entities are public by default, which means that all users logged in to the app can view all records of that entity. When an entity is private, records of that entity can only be seen by users that have been given visibility to the entity. See the access control section for more details on this.

canImportRecords

A boolean that defines whether records for an entity can be imported from CSV files. When set to true, the "import" button will appear on the records list under the app. Records can also be imported using the API.

fields

The fields property allows specifying the fields of the entity.

fields edit

Each field is defined by a set of properties that describe concepts such as its name, type, validations, etc.

Fields Properties

name

Mandatory. Defines the name of this field, as it will be used in the API and scripts to refer to that specific field.

label

Optional. Defines a human friendly name for this field which will be show in the UI. If not specified, the name property will be used instead.

description

Optional. A description for this field.

required

Optional. Defines a human friendly name for this field which will be show in the UI. Default value: false.

type

Mandatory. Defines the data type of this field. Each field type has some properties which are specific to it. Most of these properties, such as minLength, maximum, pattern, etc. are used to validate the value of the field, when creating or updating a record.

Below is a list of all available field types and their properties.

string

A string field to hold text data.

  • minLength - the minimum length in characters for all values of this field
  • maxLength - the maximum length in characters for all values of this field
  • pattern - a regex pattern that all values of this field must follow

Example:

[
    {
        "name": "basicStringField",
        "label": "Basic string field",
        "type": "string",
        "description": "just a basic string field"
    },
    {
        "name": "stringFieldWithMinAndMax",
        "label": "Min Max string field",
        "type": "string",
        "minLength": 5,
        "maxLength": 10
    },
    {
        "name": "stringFieldWithRegEx",
        "label": "RegEx validated string field",
        "type": "string",
        "pattern": "^[0-9]+$"
    }
]

number

A numeric field that can hold numbers in decimal form.

  • minimum - the minimum numeric value that can be stored in this field
  • maximum - the maximum numeric value that can be stored in this field

Example:

{
    "name": "numberWithRange",
    "label": "Number with range",
    "type": "number",
    "minimum": 5,
    "maximum": 10,
    "required": true
}

integer

A numeric field that can hold whole numbers in integer form.

  • minimum - the minimum numeric value that can be stored in this field
  • maximum - the maximum numeric value that can be stored in this field

Example:

{
    "name": "integerWithRange",
    "label": "Integer with range",
    "type": "integer",
    "minimum": 5,
    "maximum": 10,
    "required": true
}

boolean

A boolean field to store true/false values.

Example:

{
    "name": "boolField",
    "label": "Boolean",
    "type": "boolean"
}

lookup

A field representing a relationship to another record of a specified type. This field's value will hold the ID of a related record.

  • relatedTo: the name of the entity of the related record pointed to by this field.

Example:

{
    "name": "lookupToPatient",
    "label": "Patient",
    "type": "lookup",
    "relatedTo": "patient"
}

date-time

A date and time field whose value must to be specified in ISO 8601 format. The format of the value entered will be validated.

Example:

{
    "name": "dateField",
    "label": "Date",
    "type": "date-time"
}

email

A string field to store emails. The format of the value entered will be validated to be a valid email.

Example:

{
    "name": "emailField",
    "label": "Email",
    "type": "email"
}

Restrictions editing fields

It is possible to edit the definition of an entity even after data records of that entity have been created. However some restrictions apply to the changes that can be made to the fields of an entity once data has been created.

  • fields can be added
  • fields can be deleted (data for that field will be deleted under existing records)
  • fields can be renamed (see important note below)

IMPORTANT: when changing the name of an existing field, the old field will be deleted (along with its values in all existing data records) and a new one, with the new name, will be created. Data from the old field is not copied across to the new field.

  • the type of the field cannot be changed
  • a field's minimum or minLength values can only be decreased
  • a field's maximum or maxLength values can only be increased
  • a field's pattern cannot be changed
  • required cannot be changed
  • relatedTo cannot be changed

Fields Order

The order in which fields are shown in the app's UI (and also in the API) is the same in which they are saved in the entity metadata JSON.

If you wish to re-order fields of a specific entity, simply move them around in the entity metadata definition.

Entity Metadata definition example

{
    "entityName": "testEntity",
    "title": "Test Entity",
    "description": "An entity holding fields of all types",
    "entityIcon": "archive",
    "entityColor": "#BD7CB4",
    "alias": {
        "pattern": "[$]-{0}"
    },
    "canHaveFiles": false,
    "canImportRecords": true,
    "isPublic": true,
    "fields": [
        {
            "name": "basicStringField",
            "label": "Basic string field",
            "type": "string",
            "description": "just a basic string field"
        },
        {
            "name": "stringFieldWithMinAndMax",
            "label": "Min Max string field",
            "type": "string",
            "minLength": 5,
            "maxLength": 10
        },
        {
            "name": "stringFieldWithRegEx",
            "label": "RegEx validated string field",
            "type": "string",
            "pattern": "^[0-9]+$"
        },
        {
            "name": "numberWithRange",
            "label": "Number with range",
            "type": "number",
            "minimum": 5,
            "maximum": 10,
            "required": true
        },
        {
            "name": "integerWithRange",
            "label": "Integer with range",
            "type": "integer",
            "minimum": 5,
            "maximum": 10,
            "required": true
        },
        {
            "name": "boolField",
            "label": "Boolean",
            "type": "boolean"
        },
        {
            "name": "lookupToPatient",
            "label": "Patient",
            "type": "lookup",
            "relatedTo": "patient"
        },
        {
            "name": "dateField",
            "label": "Date",
            "type": "date-time"
        },
        {
            "name": "emailField",
            "label": "Email",
            "type": "email"
        }
    ]
}
← Create a new AppActions Definition →