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

200: OK

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

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

201: Created

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

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

200: OK

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

Name	Type	Description
authorization*	string	bearer <JWT> scoped to an organization

200: OK

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