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

List Mappings

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

Returns a list of Mapping records within the authorized scope

Headers

Name

Type

Description

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

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

Creates a Mapping from the included parameters

Headers

Name

Type

Description

authorizaton*

string

bearer <JWT> scoped to an organization

Request Body

Name

Type

Description

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"
}

Update Mapping

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

Updates a Mapping using the included parameters

Path Parameters

Name

Type

Description

id*

uuid

id of target Mapping

Headers

Name

Type

Description

authorizaton*

string

bearer <JWT> scoped to an organization

Request Body

Name

Type

Description

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 https://baseline.provide.services/api/v1/mappings/:id

Deletes a specified Mapping.

Headers

Name

Type

Description

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"
}

PreviousOverview NextMiddleware

Last updated 2 years ago

Overview

Application

Fundamentals

Schema

Mapping Schema

MappingModel Schema

MappingField Schema

Using Mappings

Prerequisites

API Requests

List Mappings

List Mappings

Headers

Create Mapping

Create Mapping

Headers

Request Body

Update Mapping

Update Mapping

Path Parameters

Headers

Request Body

Delete Mapping

Delete Mapping

Headers

`Mapping` Schema

`MappingModel` Schema

`MappingField` Schema