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 what was laid out already 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
]

Here I've included the id 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. Right now we only support a single dashboard per user, called "DEFAULT, which is automatically created the first time they access mod-service-interaction. In future we may look to support multiple dashboards per user.

WidgetType

WidgetType consists of three fields:

String name
String typeVersion
String schema

The name and typeVersion need to together form a unique couplet, allowing us to know exactly which schema we're using at any given point, but also to update them as we go through 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, we have name and definitionVersion, allowing us to update these as we go, but we also have a type field, of class WidgetType. This ties the definition to an existing WidgetType. Finally we have a TEXT field definition, which will house 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 houses a JSON blob, containing all the information needed for whatever the definition is, and a definition, of type WidgetDefinition.

The final field weight relates directly to the Dashboard this WidgetInstance sits on, determining its order.

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 we will have WidgetDefinitions validated against the type schema automatically, and resolved to the correct version etc. Similarly, we plan to have a chunk of code per WidgetType which can take in a WidgetDefinition and create a specific schema for a WidgetInstance based on that, which we would then validate it 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, we also have the 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>.