Models (Bridge Models)

Overview

Use Models to create an abstraction for your data. You ask "what good is an abstraction for my data?" Imagine that you're a Kinetic Platform developer and you just got done building 34 Kinetic Forms. Each form uses a Bridge to get a list of locations from your Acme service. As soon as you're done, your manager runs to you and says "We are shutting down the Acme service and need to get the locations from the database instead!" You don't panic. You know there is an abstraction layer between your new 34 forms and the Bridge that is getting the locations. All that needs to be done is an update the Bridge and Model; then you are good to go.

Kinetic Platform developers take predefined Bridge Plugins and define an abstraction that Form and Bundle developers can leverage to fetch data. As an example: using a Bridge and Model a Kinetic Form developer can build a dropdown.

Build a new Model

Models have two major components. There are Attributes and Qualification Mappings.

Attributes

The Model's attributes are an interface mapping between the source system's field names and the Model's field names. The advantage of the interface is that a Model can be pointed to a new source system without the need to update the usages of the Model.

Qualification Mappings

A qualification mapping is a mechanism for passing parameters to the source system. Here is an example of the serviceNow article search: query="How to build". A qualification mapping for that search would look like query=${parameters("Query Value")}. Where Query Value is the name of the parameter that would map to the query value.

The qualification is passed to the Bridge adapter where in most cases the qualification is added as a url query parameter that a HTTP request passes to the source system.

Attributes in detail

Model attributes are an abstraction that allows for Bridge return data to be mapped to a custom name. The forms reference the custom named attributes of the Model and not the source data. This means that a Model can "swap out" the source system. Since the Forms reference the Model attribute name the mapping to the source system's name can be updated without affecting the Forms that use the Model.

🚧

Access source system data

It is important to know the structure of the data that is returned from your source system. The bridge adapter will take the value in fields and attempt to map to the data. For example this mapping ${fields("First Name")} will pass First Name to the bridge adapter. The bridge adapter will use First Name to access a value from the return data after the call to the source system.
You will need to know what the return data is from the source system in order to do the mapping.

Qualification Mapping in detail

Qualifications have three parts. There is the Name, Result Type and Query parts. Each Model can have several qualifications defined.

Name

The Qualification Name is used by Kinetic Forms to identify which qualification should be used for the Model.

Result Type

If the qualification will returns multiple results then the Result Type must be Multiple. There is an option for a Single Result Type if only one record is returned.

Query

The query and parameters are passed to the Bridge adapter using the qualification Query. Normally, the query and parameters are passed along to the source system

❗️

Result Type errors

If the Qualification is configured with a Result Type of Single and the results of the Bridge call returns multiple records an error will occur.

What the Form Builders Need

Once the models and mappings are set up, all the form builders need is what is set up in the models portion of the bridge set up. They will be able to see these details in the form builder. This is why it is important these are useful and readable: such as Last Name rather than sn. Even if you are really familiar with the bridged system (such as Active Directory), the beauty of bridges is that your form builders don't even need to know what system they are talking to. You may decide to have a SQL DB for users in dev and your AD in prod, and as long as the bridge model attributes and qualifications are all the same, it doesn't matter what they map to.