Data mappings

Data mappings put your own identifiers on Makini records. Record your ERP's asset number or your product's location id once, and it comes back on every API response for that record, under _mappings. No lookup table on your side, no extra call.

When to use it

Link records to your product. Your app has its own id for a site, a vehicle or a customer. Keep it on the Makini record and match on it directly.

Bridge two systems. Your ERP numbers equipment one way and the CMMS another. Record the ERP number on each Makini asset.

Carry several ids at once. A record can hold identifiers under several names, such as erpId and billingRef.

Create a mapping

Open data mappings

In the dashboard, go to Connections, open a connection's row menu and choose Data mappings.

Map an entity

Click Map an entity and pick the Makini entity whose records you hold identifiers for, such as Asset.

Name it

Enter the name your identifiers are returned under, such as erpId. The API returns them as _mappings.erpId. Names start with a lowercase letter, then letters, digits or underscores, up to 63 characters.

Set the cardinality

Choose Identifiers per record and Records per identifier (see below), then click Start mapping.

An entity can have several mappings, one per name.

Cardinality

Two questions decide what a mapping accepts:

Setting	One	Several
Identifiers per record	The API returns a single value. A second identifier on the same record is refused.	The API returns a list, and a record may have more than one.
Records per identifier	The same identifier on two records is refused.	Records may share an identifier.

One and one is a strict one-to-one link, the usual choice for ERP ids. Use Several records per identifier for a code that groups records, such as a cost center shared by many assets.

Record your identifiers

Select a mapping to see the entity's records in a grid, with a column for your identifiers. Type an identifier beside each record and save.

Search by name, code or the connected system's own id. The search covers every record, not just the current page.

Filter to Mapped or Not mapped records to see what's left to do.

Choose fields to show up to four of the entity's own fields in the grid, so you can recognize each record.

Makini checks the cardinality rules as you type, marks any conflict on the rows involved, and only saves a consistent set. Saved identifiers appear on the API within about a minute.

On the API

Every record of a mapped entity carries _mappings, keyed by the names you chose:

{
  "id": "0192f4b7-2e3f-7d40-9b5c-6d7e8f9a0b1c",
  "code": "CNV-07",
  "_displayValue": "Conveyor 7",
  "name": "Conveyor 7",
  "_mappings": {
    "erpId": "EQ-10042",
    "billingRefs": ["BR-201", "BR-305"]
  }
}

Every key is present on every record, so the shape never depends on whether a record is mapped yet: a single-value mapping is null and a list mapping is [] until you add identifiers. _mappings is on list reads, single-record reads and write responses.

Find a record by your own id

Match on _mappings in Makini Query Language with any:

{ "query": "select id, name, _mappings from assets where 'EQ-10042' = any(_mappings.erpId)" }

The same form works for single-value and list mappings. It's the direct way to go from your system's id to the Makini record, and from there to any related record with join.

Per connection

Mappings belong to one connection, because each connection's records are its own. When a customer connects a second system, give it its own mappings.

To remove a mapping, choose Stop mapping on it. Its identifiers are discarded, and the API stops returning them within a minute.

Manage mappings from your backend

Everything on this page is also on the Management API, so your product can keep its own identifiers in step without anyone opening the dashboard. Use a client_credentials token (see Management API authentication); reads need connections:read and changes need connections:write.

Create a mapping for one entity of a connection:

{
  "dataMapping": {
    "id": "d6fa5763-7230-417c-827f-64a3e69076fd",
    "entity": "Asset",
    "key": "erpId",
    "identifierCardinality": "one",
    "recordCardinality": "one",
    "revision": 1,
    "entryCount": 0
  }
}

identifierCardinality is the identifiers a record may carry and recordCardinality is the records one identifier may point at. Both are one unless you send many.

Then send the pairs. Each pair is a Makini record id and your identifier for it:

The list you send replaces the mapping's pairs, so send the full set each time. The answer is the mapping with a new revision and entryCount, and the identifiers appear on /v4 within about a minute.

Route	Does
`GET /connections/{id}/data-mappings`	Lists the connection's mappings. Add `?entity=Asset` for one entity.
`POST /connections/{id}/data-mappings`	Creates a mapping.
`GET /connections/{id}/data-mappings/{mappingId}`	Reads one mapping.
`PUT /connections/{id}/data-mappings/{mappingId}`	Changes its key or cardinality.
`GET /connections/{id}/data-mappings/{mappingId}/entries`	Reads the pairs, a page at a time (`limit`, then `after` with the `nextAfter` from the page before).
`PUT /connections/{id}/data-mappings/{mappingId}/entries`	Replaces the pairs.
`DELETE /connections/{id}/data-mappings/{mappingId}`	Stops mapping the entity and discards its pairs.

Publish vendor fields and shape the model itself: see Custom mappings.

Query by mapping and relation: see Makini Query Language.

When to use it#

Create a mapping#

Cardinality#

Record your identifiers#

On the API#

Find a record by your own id#

Per connection#

Manage mappings from your backend#

Related#