Search…
Mappings

Overview

Successfully implementing a Baseline process relies heavily on arbitrary data models from disparate systems of record having similar data structures. Mappings enables persistent data alignment through a collection of RESTful API interfaces that allow a developer to define and maintain Mapping, MappingModel and MappingField objects as they relate to external data structures within a baseline workgroup.

Application

Mappings should be used by participants in a Workgroup taking part in a Workflow to align the data used in a Workstep. A Mapping is referenced as a domain model when defining a Workstep within a draft Workflow. They are utilized at run-time upon WorkstepInstance instantiation to align data models between a primary and secondary system of record. This alignment is paramount in the processes involved in a baseline process, such as zero-knowledge state synchronization.
Mappings created through the API are used to dynamically generate mapping tables that are stored in a postgres database within the provide stack (local, hybrid or cloud). Input and output that conforms to the MappingModel defined in a Mapping within a domain model is referenced in a Workstep.

Fundamentals

Schema

A mapping is a hierarchically structured object that contains the information necessary to process and align data elements (fields) between two disparate data models. Mappings are composed of three distinct components:
  • A Mapping object that provides context for a nested array of MappingModel objects
  • A MappingModelobject that provides context for a nested array of MappingField objects
  • A MappingField object that defines field attributes and relationships between the source and a target schema
All objects and related tables within a mapping are programmatically generated from the data included in the request. Mapping, MappingModel and MappingField objects do not have separate endpoints.

Mapping Schema

Field
Type
Description
description
string
brief descriptor of Mapping
models
array
array of MappingModel objects
name
string
name of Mapping
ref_mapping_id
uuid
reference identifier that associates a Mapping to an upstream Mapping
type
string
type of Mapping; i.e. domain object
workgroup_id
uuid
id of host Workgroup

MappingModel Schema

Field
Type
Description
description
string
brief descriptor of model
fields
array
array of MappingField objects
primary_key
string
field that serves as the primary key for the record type
ref_model_id
uuid
reference identifier that associates a Model to an upstream Model
standard
string
standard Model type
type
string
native data type within the reference system of record; i.e. Invoice

MappingField Schema

Field
Type
Description
default_value
string
default value for the field
description
string
brief descriptor of field
is_primary_key
boolean
when true, field is referenced as the primary key for the record type
name
string
name of field
ref_field_id
uuid
reference identifier that associates a Field to an upstream Field
type
string
native data type within the reference system of record; i.e. Total Qty

Using Mappings

Prerequisites

The Mappings API is intended to function within the context of an Organization acting as a Participant in a Workgroup.
Within this context, it is assumed that:
  • an Organization scoped JWT is available for use
  • Organization has connected a system of record (the SOR to be mapped)
  • Workgroup has more than 1 system of record connected
  • destination SOR data structure is known
  • origin SOR data structure is known

API Requests

List Mappings

Returns a list of mappings
get
https://baseline.provide.services
/api/v1/mappings
List Mappings

Create Mapping

post
https://baseline.provide.services
/api/v1/mappings
Create Mapping

Update Mapping

put
https://baseline.provide.services
/api/v1/mappings/:id
Update Mapping

Delete Mapping

delete
https://baseline.provide.services
/api/v1/mappings/:id
Delete Mapping