Backend Structure

This page will go a little deeper into exactly what domain classes and endpoints mod-service-interaction sets up, and how they work.

Domain Structure

The domain classes described here are pretty similar to the components described in the vocabulary section.

External User

When a user interacts with mod-service-interaction, by fetching their dashboard or otherwise, the first thing the module will do is resolve their FOLIO user UUID to a domain class called ExternalUser. This means that every user who interacts with the backend will have an ExternalUser domain object which we then can hang dashboards from. This domain class stores no personal information besides the user UUID and the dashboard configuration.

Right now the ExternalUser domain object consists only of 

String id
hasMany = [
	dashboards: Dashboard
]

The id ins included only to note that we set this on binding to be the same as the FOLIO User UUID, so that we can then rely on those being the same. The hasMany here is future proofing. Currently there is only support for a single dashboard per user, called "DEFAULT, which is automatically created the first time they access mod-service-interaction. In future support multiple dashboards per user maybe introduced.

WidgetType

WidgetType consists of three fields:

String name
String typeVersion
String schema

The name and typeVersion need to together form a unique couplet, ensuring that it is possible to know exactly which schema is being used at any given point, and also to allow updates to schemas throughout the lifecycle of a widgetType.

The schema field is simply a TEXT field, allowing the widgetType to store a standard JSON schema. This will dictate the shape of any widgetDefinition using this type.

WidgetDefinition

WidgetDefinition consists of four fields:

String name
String definition
String definitionVersion
WidgetType type

Similarly to before, there is name and definitionVersion, allowing these to be updated over time. Additional there is a type field, of class WidgetType. This ties the WidgetDefinition to an existing WidgetType. Finally we have a TEXT field definition, which is used to store the JSON responsible for this widgetDefinition.

WidgetInstance

WidgetInstance consists of four main fields:

String name
Integer weight
WidgetDefinition definition
String configuration

static belongsTo = [ owner: Dashboard ]

The name, which will display at the top of the widget on a dashboard; a configuration string which is used to store a JSON blob, containing all the information needed for whatever the definition is; and a definition, of type WidgetDefinition, which ties the WidgetInstance to a WidgetDefinition.

The final field weight relates directly to the Dashboard this WidgetInstance sits on, determining the order in which the WidgetInstances are displayed when the user views the dashboard.

As you can see from the belongsTo section, a WidgetInstance is just that, an instance of a widget, unique to a single user's dashboard.

Validation

In the future WidgetDefinitions will be validated against the type schema automatically, and resolved to the correct version etc. Similarly, it is planned to have code per WidgetType which can take in a WidgetDefinition and create a specific schema for a WidgetInstance based on that, which it could then be validated against.

That means the validation flow for a new widgetDefinition and then widgetInstance based on that is as follows:

Endpoints

This module as things stand has a few endpoints available to it. These are in the KIWT style, similar to Agreements/Licenses.

Dashboard fetch

A user can fetch their dashboards with the endpoint /servint/dashboard/my-dashboards. The first time a new user UUID is encountered, an ExternalUser will be created, and a dashboard named "DEFAULT" will be attached to that user. For administrative purposes, there is an endpoint /servint/dashboard which can fetch all dashboards in the system, protected by permissions.

Widget fetch

In order to facilitate the fetch and display of widgets, two more endpoints are also exposed: /servint/widgets/definitions will return a list of all the definitions in the sytem, and /servint/widgets/instances will be accessible to administrators to fetch ALL widget instances in the system, with specific access available to single users through /servint/widgets/instances/<id of my widget>.