Makini's unified model gives you the same entities and fields across every platform, out of the box. Custom mappings let you extend it for each connection, without code and without waiting for a release: publish any vendor field, change how a standard field is filled, build a whole entity, or bring in an extra endpoint of the platform's API.What you can do#
Add custom fields
Publish any column from the connected system on a Makini entity, under customFields.
Override standard fields
Fill a standard field from a different column, or compute it with a SQL expression.
Build an entity
Serve an entity for this connection straight from one of the platform's tables.
Add an API endpoint
Sync an extra endpoint of the platform's API and map its records like any other table.expand, and Makini Query Language.Open the editor#
In the dashboard, go to Connections, open a connection's row menu and choose Edit mappings. The editor has three panels:Source: the tables and columns Makini has from the connected system. Expand a JSON column to see the keys inside it.
Makini: the entity you're editing, with three tabs: Data sources, Standard fields and Custom fields.
Output: the document the API will return for this entity, as a JSON skeleton or as an OpenAPI schema. It updates as you edit.
Add a custom field#
1
Choose the entity
Pick the entity in the Makini panel, such as WorkOrder.
2
Add the field
On the Custom fields tab, click Add field and name it, for example costCenter. Names start with a letter and use letters, digits and underscores.
3
Give it a source
Drag a column onto it, or choose one. For a JSON column, choose the key inside it, such as billing.costCenter. Or switch the source to Expression and write SQL (see below).
{
"id": "0192f4b7-1d2e-7c3f-8a4b-5c6d7e8f9a0b",
"code": "WO-10482",
"title": "Replace conveyor belt",
"customFields": {
"costCenter": "CC-4410"
}
}
customFields, so the standard schema stays identical across platforms and your additions never collide with it. Every key you map is present on every record, null where a record has no value. Query them like any other field:{ "query": "select code, title, customFields.costCenter from work-orders where customFields.costCenter = 'CC-4410'" }
Groups: several columns in one field#
Click Add group to publish several columns of a joined table as one object. Drop the first column onto the group to set its table, then add members with + and name each one.When the source is a joined table, choose how many values the field takes:First match: one object, from the first matching row. The pick is deterministic, so it doesn't change between reads.
All matches: a list with one object per matching row.
"customFields": {
"contacts": [
{ "name": "Dana Ruiz", "phone": "+1 555 0142" },
{ "name": "Lee Park", "phone": "+1 555 0178" }
]
}
Data sources and joins#
The Data sources tab lists the tables an entity reads, and how each lines up with the main table. To bring in another table, click Add source, pick the table and choose the matching column on each side. Tables that arrive with the next sync are listed too, marked not synced yet.A source that still needs its join rule is flagged on the tab, so nothing is saved half-wired.Override a standard field#
On the Standard fields tab, each field shows where its value comes from. Its source control has three options:Default: Makini's own mapping, shown read-only so you can see what you'd replace.
Field: a column you choose.
Expression: a SQL expression.
Expressions#
An expression is one PostgreSQL scalar expression, evaluated for each record. Refer to the main table's columns as b."column":Casts use the mapping types: text, int, bigint, numeric, boolean, date, timestamptz and jsonb. Every expression is parsed and checked when you save. Each expression works on one record at a time and only reads: to bring in another table, add it under Data sources.Build an entity#
Pick an entity that isn't part of this connection's model, and the editor offers to build it:1
Choose the driving table
One row of this table becomes one record of the entity.
2
Choose the display value
The column the API returns as _displayValue.
3
Build it
Click the Build button, which names the entity and the table, then give every field marked required a source.
GET /v4/contracts, with the full envelope, filters and MQL. Stop building it removes it again.Add an API endpoint as a source#
When you need data from an endpoint outside the standard model, add it yourself. In the Source panel click Add source, then Add an endpoint:1
Endpoint
Choose GET or POST and enter the path. It's appended to the platform's API URL, and Makini calls it with this connection's credentials. Add query parameters, or a JSON body for search endpoints that take their filter in the body. Click Fetch sample.
2
Sample
Makini reads the response and lists the arrays it found, best match first. Pick the list that holds the records.
3
Identity
Choose what makes a record unique, preselected from what looks unique, and confirm the name. The name is also the table name you'll map from.
Custom endpoints take GET, or POST for search-style reads, with the connection's own credentials. That keeps every custom source a read, and a custom endpoint never replaces one Makini already syncs.
Save and go live#
Click Save mappings. Makini validates the whole configuration (this can take up to a minute), then saves it as a new revision, shown beside the save button. If anything is refused, the editor lists each field with the reason: click one to jump to it.Saving sets a sync in motion that applies the change. The connection's status badge in the header shows its progress, and your new fields appear on /v4 as soon as it completes.If someone else saved mappings for this connection while you were editing, the editor tells you and offers to reload, so nobody's work is overwritten silently.Mappings belong to one connection. Two connections to the same platform can publish different custom fields, which suits customers who each run their system their own way.
Manage mappings from your backend#
The editor works through the Management API, and your backend can use the same routes: to apply one mapping to every customer's connection, or to keep mappings in your own repository. Use a client_credentials token (see Management API authentication); reads need connections:read and changes need connections:write.1
Read what the connection publishes
The answer holds servedEntities (every entity and field the connection serves), overlay (your current mapping document), its revision and a digest. To see the vendor tables and columns you can map from, read GET /connections/{id}/source-schema. 2
Save your mappings
Send the whole mapping document, with the
digest you read:
Makini validates the document, saves it as a new revision and starts the sync that applies it. Validation can take up to a minute, so allow a long timeout. A 409 means the mappings changed since you read them: read again and reapply your change. A refused document answers 400 and lists each mapping with the reason.3
Roll back when you need to
GET /connections/{id}/pipeline/revisions lists every revision, newest first. To return to one:
Custom endpoints#
Try an endpoint before you save it. Makini calls it with the connection's credentials and answers with the arrays it found and their fields:The answer is always 200. When the platform refuses the call, ok is false and the platform's own status and message are in the body.Then save the connection's custom endpoints as one list:The list replaces the connection's custom endpoints, so include the ones you want to keep.Attach your own identifiers to Makini records: see Data mappings.
Read what you've mapped: see Reading data and Makini Query Language.
