Schemas

A schema defines both the data contained and the behavior (in the form of a state machine) of the documents it holds. A Schema object is identified within the Data Service by a unique identifier (id) and contains a name (3-50 characters) and description (max 100 characters). A schema is based on:

Permissions that determine who can access what documents,
Statuses which define the state of the document,
Properties which define the structure of the document,
Transitions which can trigger actions

Create a new schema

const mySchema = await exh.data.schemas.create({
    name: 'myNewSchema',
    description: 'This is my new schema',
});

Data Access Management

In this section we discuss how you can configure access to documents. A schema contains specific attributes that define the conditions which must be met to create, view, update or delete documents.

Access Modes

createMode

createMode defines the permissions needed to create a document in a schema collection.

Mode

Description

readMode

readMode defines the permissions needed to read a document in a schema collection

Users that have the VIEW_DOCUMENTS or VIEW_DOCUMENTS:{schemaName} permission attached to a global role will be able to read any document regardless of the setting above.

updateMode

updateMode defines the permissions needed to update a document in a schema collection

Users that have the UPDATE_DOCUMENTS or UPDATE_DOCUMENTS:{schemaName} permission attached to a global role will be able to update any document regardless of the setting above.

deleteMode

deleteMode defines the permissions needed to remove a document permanently from a schema collection.

Users that have the DELETE_DOCUMENTS or DELETE_DOCUMENTS:{schemaName}permission attached to a global role will be able to delete any document regardless of the setting above.

Access to documents through role permissions

Every permission has a global and a schema-specific variant. This allows you to define access to documents in a very granular way.

The following table lists the relevant permissions for the data service:

The above mentioned permissions can be granted to users through global roles or group roles.

For more information how to add permissions to roles and roles to users, take a look at the user service documentation

Creating a schema with permissions

You can provide the permissions parameters upon creation of you new schema:

const mySchema = await exh.data.schemas.create({
    name: 'mySchema',
    description: 'This is my new schema',
    createMode: 'default',
    readMode: 'allUsers',
    updateMode: 'disabled',
    deleteMode: 'permissionRequired'
});

Properties

A Schema defines the structure of a document through properties. The Properties object contains type configurations, which represent the fields that should be accepted while creating or updating a document. The structure of the type configurations themselves is inspired by JSON Schema.

The Data Service supports five kinds of configurations (type attribute):

{
  type: 'object',
  properties: {
    my_custom_field: { type: 'string' },
  },
  additionalProperties: { type: 'string' },
  required: ['my_custom_field'],
}

References:

{
  type: 'array',
  items: { type: 'string' },
  minItems: 1,
  maxItems: 10,
  contains: { type: 'string' },
}

Note that the items- property is required.

References:

{
  type: 'string',
  minLength: 1,
  maxLength: 10,
  pattern: '^[a-z]+$',
  format: 'date-time', // The only supported format is `date-time`
  enum: ['a', 'b', 'c'],
  const: 'b' // Can only be one fixed string
}

When the format is set to date-time, input is expected to be valid ISO 8601 string (e.g.2012 or 2012‐08‐22T14:16:05.677+02:00).

This value is stored as an UTC Date Time String (e.g. 2012‐08‐22T12:16:05.677Z).

Input conditions will operate on the input (e.g.2012 or 2012‐08‐22T14:16:05.677+02:00). Document conditions will operate on the stored date, thus the UTC Date Time String (e.g. 2012‐08‐22T12:16:05.677Z).

References:

{
  type: 'number',
  minimum: 1,
  maximum: 5,
  enum: [1, 2, 3, 4, 5],
  const: 3 // Can only be 1 number
}

References:

{
  type: 'boolean',
  enum: [true, false],
  const: true, // Can only be either true or false
}

References:

JSON Schema Validation: Validation Keywords for Any Instance Type

Adding properties to your schema

await exh.data.properties.create(mySchema.id, {
  name: 'myFirstProperty',
  configuration: {
    type: 'string',
    enum: ['firstValue', 'secondValue'],
  }
});

Updating properties

You can update a specific property of a schema by providing the schema Id, the property path and the the json schema field configuration. The Property path makes use of the dot notation in case you are working with nested fields.

await exh.data.properties.update(
  mySchema.id,
  'myObjectField.myStringField',
  { type: 'string' }
);

Removing properties

You can remove a specific property of a schema by providing the schema Id, the property path and the the json schema field configuration. The Property path makes use of the dot notation in case you are working with nested fields.

await exh.data.properties.remove(
  mySchema.id,
  'myObjectField.myStringField',
  { type: 'string' }
);

Some examples

you can also make more complex objects and array's of objects.

await exh.data.properties.create(mySchema.id, {
  name: 'address',
  configuration: {
    type: 'object',
    properties: {
      street: {
        type: 'string',
        minLength: 1,
        pattern: '^[a-z]+$'
      },
      number: {
        type: 'number',
        minimum: 1,
        maximum: 300
      },
      inhabited: {
        type: 'boolean',
        enum: [true, false]
      },
      residents: {
        type: 'array',
        items: { type: 'string' },
        minItems: 1,
        maxItems: 10
      }
    }
  }
});

await exh.data.properties.create(mySchema.id, {
  name: 'address.residents',
  configuration: {
    type: 'array',
    items: {
      type: 'array',
      items: { type: 'string' },
      minItems: 1,
      maxItems: 10
    }
  }
});

await exh.data.properties.create(mySchema.id, {
  name: 'birthdate',
  configuration: {
    type: 'string',
    format: 'date-time'
  }
});

this allows you to create a ISO formatted date-time field which accepts RQL to query on using gt,gte, lt and lte ,...

All attributes required to compose the type configurations, can be found in the API reference documentation and on the JSON Schema webpage.

Statuses

A document can be perceived as a finite-state machine, which remains in a state/status until a transition occurs. You can define a set of statuses for your document based on the expected workflow you want to build.

await exh.data.statuses.create(mySchema.id, {
    name: 'initialStatus',
});

CreationTransition

The creation transition is the transition that is executed when you create a document. It is the only type of transition that doesn't have a fromStatus as there is no status to start from.

When you create new schema, by default the data service will include a NEW status and a creation transition towards that status. This is the reason why you wont find a create creationTransition or delete creationTransition function and only an updateCreationTransition function.

exh.data.transitions.updateCreation(mySchema.id, {
  type: 'manual',
  toStatus: 'initialStatus',
  conditions: {...},
  actions: {...},
  afterActions: {...}
});

Currently the only supported transition type is manual. Other types may be added in the future.

Transitions

When you want to add more statuses to your document you will need to define transitions that allow you to move your document from one status to another. Normal transitions look the same as a creationTransition but these do include two additional parameters fromStatusesand name.

A Transition occurs from one Status to another. The Statuses a Transition starts from are determined in the fromStatuses object, and the Status the Transition leads to is determined in the toStatus attribute.

exh.data.transitions.updateCreation(mySchema.id, {
  name: 'firsTransition'
  type: 'manual',
  fromStatuses: ['initialStatus'],
  toStatus: 'secondStatus',
  conditions: {...},
  actions: {...},
  afterActions: {...}
});

A Transition object is identified by its name (name) and has a specific type assigned:

Types

Transition conditions

Conditions need to be met before a transition can occur. There are three types of conditions which apply to the creationTransition and Transitions with the type manual:

There is an additional condition which applies to all Transitions:

Input Condition

The transition data must match a desired form, as specified by the type configurations in the configuration attribute.

This Condition only applies to the creationTransition and Transitions with type manual.

Example

The following code creates a manual transition requiring:

The name in the input to be a string
The name in the input to exist

await exh.data.transitions.create(mySchema.id, {
  ...,
  conditions: [
    {
      type: 'input',
      configuration: {
        type: 'object',
        properties: {
          name: {
            type: 'string',
          },
        },
        required: ['name'],
      },
    },
  ],
  ...
});

initiatorHasRelationToUserInData Condition

The initiator of the Transition has a specified relation (as determined in relation) to a user (as determined in userIdField) mentioned in the transition data.

The only valid value of the relation field is isStaffOfTargetPatient. The initiator must have at least one staff enlistment for the same group the targeted user has a patient enlistment.

This Condition only applies to the creationTransition and Transitions with type manual.

Example

The following code creates a manual transition for which:

The targeted user is determined by the myPatientId data field.
The initiator of the transition must be a staff member from the same group to which the targeted user is a patient.

await exh.data.transitions.create(mySchema.id, {
  ...,
  conditions: [
    {
      type: 'initiatorHasRelationToUserInData',
      userIdField: 'myPatientId',
      relation: 'isStaffOfTargetPatient',
    },
  ],
  ...
});

initiatorHasRelationToGroupInData Condition

The initiator of the Transition has a specified relation (as determined in relation) to a group (as determined in groupIdField) mentioned in the transition data.

The value for the relation field can either be:

staff: The initiator must have a staff enlistment for the target group
patient: The initiator must have a patient enlistment for the target group

The optional field requiredPermission is only used when the relation is set to staff. When supplied the initiator must not only have a staff enlistment with the targeted group, but also a role assigned within that group with the specified permission.

This Condition only applies to the creationTransition and Transitions with type manual.

Example

The following code creates a manual transition for which:

The targeted group is determined by the myGroupId data field.
The initiator of the transition must be a staff member of the targeted group.
The initiator of the transition must have the MY_OWN_PERMISSION group permission.

await exh.data.transitions.create(mySchema.id, {
  ...,
  conditions: [
    {
      type: 'initiatorHasRelationToGroupInData',
      groupIdField: 'myGroupId',
      relation: 'staff',
      requiredPermission: 'MY_OWN_PERMISSION',
    },
  ],
  ...
});

Document Condition

The content of the existing document must match a desired form, as specified by the type configurations in the configuration attribute.

This Condition applies to all transitions.

Example

The following code creates a manual transition requiring:

The name in the document data to be a string
The name in the document data to exist

await exh.data.transitions.create(mySchema.id, {
    ...,
    conditions: [
      {
        type: 'document',
        configuration: {
          type: 'object',
          properties: {
            data: {
              type: 'object',
              properties: {
                name: {
                  type: 'string',
                },
              },
              required: ['name'],
            },
          },
          required: ['data'],
        },
      },
    ],
  });

Transition actions

You can attach actions to transitions. This way when a transition is executed and its conditions are met it will also trigger the action. In case of a Creation Transition, the action will be executed during the creation of the document.

Modifying the document

To access an element in an array or embedded documents, use the dot notation.

code examples

await exh.data.transitions.create(mySchema.id, {
  ...,
  actions: [
    {
      type: 'set',
      field: 'data.myField',
      value: 'myValue'
    }
  ],
  ...
});

await exh.data.transitions.create(mySchema.id, {
  ...,
  actions: [
    {
      type: 'unset',
      fields: ['data.myField', 'otherField']
    }
  ],
  ...
});

await exh.data.transitions.create(mySchema.id, {
  ...,
  actions: [
    {
      type: 'addItems',
      field: 'data.myField',
      values: ['item1', 'item2']
    }
  ],
  ...
});

await exh.data.transitions.create(mySchema.id, {
  ...,
  actions: [
    {
      type: 'removeItems',
      field: 'data.myField',
      values: ['item1', 'item2']
    }
  ],
  ...
});

Modifying document access

Each document has a userIds and groupIds field. These field are part of determining the access policy towards that specific document depending on the general collection schema configuration.

Using actions you can modify these fields and therefore the access of the document.

If you like to modify the access to documents from outside the data service you can perform access modification functions on the documents itself. Read the documentation here: Data Access Management

code examples

await exh.data.transitions.create(mySchema.id, {
  ...,
  actions: [
    {
      type: 'linkCreator',
    }
  ],
  ...
});

await sdk.data.transitions.create(mySchema.id, {
  ...,
  actions: [
    {
      type: 'linkUserFromData',
      userIdField: '{UserIdField}', // Field in dot notation. The root is data
    }
  ],
  ...
});

await sdk.data.transitions.create(mySchema.id, {
  ...,
  actions: [
    {
      type: 'linkEnlistedGroups',
      onlyActive: true, // Optional, defaults to false
    }
  ],
  ...
});

await sdk.data.transitions.create(mySchema.id, {
  ...,
  actions: [
    {
      type: 'linkGroupFromData',
      groupIdField: 'my_group_id', // Field in dot notation. The root is data
    }
  ],
  ...
});

Other actions

code examples

await exh.data.transitions.create(mySchema.id, {
  ...,
  actions: [
    {
      type: 'task',
      functionName: 'myTaskServiceFunctionName',
    }
  ],
  ...
});

Indexes

The Index object is identified by an id and a name. An index is set on a specific property in a Schema. This property is defined in the Fields object by the name and type attribute. The index is tailored with the following attributes:

Other settings

groupSyncMode

The groupIds field allows to define which groups should get access to the document. The users that have a staff enlistment in a group that is in the groupIds field will get access to the document. The level of access depends on the readMode, writeMode, updateMode and deleteMode values.

When a groupSyncMode is configured, the data service will automatically update the groupIds field of documents in the schema depending on changes in the user service. The table below lists the different options.

The synchronization is applied retroactively. It will be applied to all documents in a schema. That includes the documents that were created before configuring this setting and the documents that were created before the user was added to a group.

Example 1 • Allow doctors to access measurements created by patients

When you define a measurements schema, the patients will be the users creating the measurement documents. The creatorId of a measurement will be set to the patient userId.

To automatically give the appropriate doctors access to the measurements of their patients, you can set the groupSyncMode to creatorPatientEnlistments.

Example 2 • Allow doctors to read lab results of patients

Consider the use case where patients can have their saliva tested at kiosks that are deployed in pharmacies. When patients provide a specimen in the kiosk, the kiosk will process the specimen and upload the results. The corresponding document is created by the kiosk, thus creatorId of the document will not correspond to the userId of the patient.

To give doctors access to the results, set the groupSyncMode to linkedUsersPatientEnlistments and configure the kiosk to add the userId of the patient in the userIds field of the document.

Code Example

await exh.data.schemas.update(mySchema.id, {
    groupSyncMode: 'creatorPatientEnlistments',
});

defaultLimit & maximumLimit

The defaultLimit and maximumLimit refer to the number of documents that are returned to you when you execute a query. Pagination is crucial in keeping you API fast and responsive. By default the defaultLimit is set to 20 documents and the maximumLimit is set to 100 documents. We recommend to keep these settings. Only in very specific use cases would it be reasonable to change these settings.

await exh.data.schemas.update(mySchema.id, {
  defaultLimit: 20,
  maximumLimit: 200,
});

Removing a schema

You can only remove disabled schema's. Removing a schema removes all documents in that schema collection. Removed documents are non retrievable.

await exh.data.schemas.remove(mySchema.id);

Enabling/disabling a schema

As the removal of a schema is something that you want to handle with great care the service first requires you to disable a schema. When a schema is disabled creation of new documents is disabled and no changes are allowed to existing documents.

await exh.data.schemas.disable(mySchema.id);

You can enable a disabled schema the same way:

await exh.data.schemas.enable(mySchema.id);

PreviousData Service NextDocuments

Last updated 4 months ago