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

FieldTypeDescription

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

FieldTypeDescription

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

FieldTypeDescription

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

List Mappings

GET https://baseline.provide.services/api/v1/mappings

Returns a list of Mapping records within the authorized scope

Headers

NameTypeDescription

authorization*

string

bearer <JWT> scoped to an Organization

{
    "id": "f3dadc5d-76d0-4ea0-be44-c9ca2d354924",
    "created_at": "2021-12-10T20:59:50.648482934Z",
    "name": "Mapping name",
    "description": "Mapping intended for demonstration purposes",
    "type": "mapping_type",
    "models": [
        {
            "id": "5a6d0da5-c923-417d-8beb-3bb59e22dd7d",
            "created_at": "2021-12-10T20:59:50.649965564Z",
            "description": "Mapping model name",
            "primary_key": "id",
            "type": "uuid",
            "mapping_id": "f3dadc5d-76d0-4ea0-be44-c9ca2d354924",
            "fields": [
                {
                    "id": "d71825ec-0b2e-4aae-a419-07603aaedfda",
                    "created_at": "2021-12-10T20:59:50.650813981Z",
                    "is_primary_key": true,
                    "name": "id",
                    "description": null,
                    "type": "string",
                    "mapping_model_id": "5a6d0da5-c923-417d-8beb-3bb59e22dd7d"
                }
            ]
        }
    ],
    "organization_id": "5a37cf55-5169-46fe-a7c5-070d79d4569d",
    "workgroup_id": "a746d83d-6d5e-4d41-9588-300e7e7ff0bc"
}

Create Mapping

Create Mapping

POST https://baseline.provide.services/api/v1/mappings

Creates a Mapping from the included parameters

Headers

NameTypeDescription

authorizaton*

string

bearer <JWT> scoped to an organization

Request Body

NameTypeDescription

name*

string

name of Mapping

desciption

string

description of Mapping

workgroup_id*

uuid

id of Workgroup in which a Mapping is to be used

type*

string

type of Mapping

models*

array

array of MappingModel objects

ref_mapping_id

uuid

reference identifier that associates a Mapping to an upstream Mapping

{
    "id": "f3dadc5d-76d0-4ea0-be44-c9ca2d354924",
    "created_at": "2021-12-10T20:59:50.648482934Z",
    "name": "Mapping name",
    "description": "Mapping intended for demonstration purposes",
    "type": "mapping_type",
    "models": [
        {
            "id": "5a6d0da5-c923-417d-8beb-3bb59e22dd7d",
            "created_at": "2021-12-10T20:59:50.649965564Z",
            "description": "Mapping model name",
            "primary_key": "id",
            "type": "uuid",
            "mapping_id": "f3dadc5d-76d0-4ea0-be44-c9ca2d354924",
            "fields": [
                {
                    "id": "d71825ec-0b2e-4aae-a419-07603aaedfda",
                    "created_at": "2021-12-10T20:59:50.650813981Z",
                    "is_primary_key": true,
                    "name": "id",
                    "description": null,
                    "type": "string",
                    "mapping_model_id": "5a6d0da5-c923-417d-8beb-3bb59e22dd7d"
                }
            ]
        }
    ],
    "organization_id": "5a37cf55-5169-46fe-a7c5-070d79d4569d",
    "workgroup_id": "a746d83d-6d5e-4d41-9588-300e7e7ff0bc"
}

Update Mapping

Update Mapping

PUT https://baseline.provide.services/api/v1/mappings/:id

Updates a Mapping using the included parameters

Path Parameters

NameTypeDescription

id*

uuid

id of target Mapping

Headers

NameTypeDescription

authorizaton*

string

bearer <JWT> scoped to an organization

Request Body

NameTypeDescription

name

string

name of Mapping

desciption

string

description of Mapping

workgroup_id

uuid

id of Workgroup in which a Mapping is to be used

type

string

type of Mapping

models

array

Array of MappingModel objects

{
    "id": "f3dadc5d-76d0-4ea0-be44-c9ca2d354924",
    "created_at": "2021-12-10T20:59:50.648482934Z",
    "name": "Mapping name",
    "description": "Mapping intended for demonstration purposes",
    "type": "mapping_type",
    "models": [
        {
            "id": "5a6d0da5-c923-417d-8beb-3bb59e22dd7d",
            "created_at": "2021-12-10T20:59:50.649965564Z",
            "description": "Mapping model name",
            "primary_key": "id",
            "type": "uuid",
            "mapping_id": "f3dadc5d-76d0-4ea0-be44-c9ca2d354924",
            "fields": [
                {
                    "id": "d71825ec-0b2e-4aae-a419-07603aaedfda",
                    "created_at": "2021-12-10T20:59:50.650813981Z",
                    "is_primary_key": true,
                    "name": "id",
                    "description": null,
                    "type": "string",
                    "mapping_model_id": "5a6d0da5-c923-417d-8beb-3bb59e22dd7d"
                }
            ]
        }
    ],
    "organization_id": "5a37cf55-5169-46fe-a7c5-070d79d4569d",
    "workgroup_id": "a746d83d-6d5e-4d41-9588-300e7e7ff0bc"
}

Delete Mapping

Delete Mapping

DELETE https://baseline.provide.services/api/v1/mappings/:id

Deletes a specified Mapping.

Headers

NameTypeDescription

authorization*

string

bearer <JWT> scoped to an organization

{
    "id": "f3dadc5d-76d0-4ea0-be44-c9ca2d354924",
    "created_at": "2021-12-10T20:59:50.648482934Z",
    "name": "Mapping name",
    "description": "Mapping intended for demonstration purposes",
    "type": "mapping_type",
    "models": [
        {
            "id": "5a6d0da5-c923-417d-8beb-3bb59e22dd7d",
            "created_at": "2021-12-10T20:59:50.649965564Z",
            "description": "Mapping model name",
            "primary_key": "id",
            "type": "uuid",
            "mapping_id": "f3dadc5d-76d0-4ea0-be44-c9ca2d354924",
            "fields": [
                {
                    "id": "d71825ec-0b2e-4aae-a419-07603aaedfda",
                    "created_at": "2021-12-10T20:59:50.650813981Z",
                    "is_primary_key": true,
                    "name": "id",
                    "description": null,
                    "type": "string",
                    "mapping_model_id": "5a6d0da5-c923-417d-8beb-3bb59e22dd7d"
                }
            ]
        }
    ],
    "organization_id": "5a37cf55-5169-46fe-a7c5-070d79d4569d",
    "workgroup_id": "a746d83d-6d5e-4d41-9588-300e7e7ff0bc"
}

PreviousAxiomNextMiddleware

Last updated