Introduction

Maptainer does not adapt to each ERP’s structure, nor the ERP to Maptainer’s. Each one publishes how it talks, and in between there is an integration layer that translates: it is built by the consultant or IT person who maintains the ERP, with a tool such as SAP Integration Suite, Power Automate or their own program.

The integration layer translates both waysClient ERPSAP PM, Business Central…Integration layerSAP CPI, Power Automate, n8n…MaptainerAPI key and webhooksNew notificationno., priority, equipmentTranslates the codeswith no duplicatesPending issuesource Integration (API)Closes notificationby its numberChecks the signatureand finds the referenceSigned notificationWO closed, issue…Books costshours and materialReads in batchesand groups by WOData to readhours, material, replica
One outbound flow (ERP notifications) and two return flows (changes and costs).

The integration has three pieces. All of them are set up in the administration area → API and data backups.

Piece Direction What for
Create issues ERP → Maptainer A breakdown notification in the ERP comes into Maptainer as an issue
Webhooks Maptainer → ERP Maptainer notifies straight away when a work order or an issue changes
Reading data Maptainer → ERP The ERP reads hours, materials and catalogues to book costs or keep a copy

Prerequisites

  • The maintenance module subscribed: issues and work orders depend on it.
  • Being the organisation’s administrator. Keys and webhooks are not delegated by role.
  • Someone to set up the ERP side: the client’s consultant or IT person. They need an https:// address to receive notifications.
  • A test environment for the ERP. Avantgeo can prepare a test organisation in Maptainer; ask support.

Which system owns each piece of data

Before you start, decide which system owns each piece of data. If both can change the same thing, the last one to write wins and the other never finds out. This is the usual proposal:

Data Owner The other system…
That a breakdown or notification exists ERP Maptainer receives it as an issue and stores the notification number
Planning, worker assignment and routes Maptainer The ERP does not touch it
Execution: statuses, hours, photos, forms and signature Maptainer The ERP receives it by webhook and reads it
Closing the notification Maptainer notifies, the ERP closes The ERP closes the notification when the closure arrives
Costs and invoicing ERP Reads from Maptainer the hours and material used
Accounting data of the asset (inventory no., cost centre) ERP In Maptainer it goes in an asset field, if needed
Location and geometry of the assets Maptainer The ERP does not touch it

Preparing the integration

  1. Meet whoever maintains the ERP and fill in the mapping sheet together.
  2. Create an API key for the ERP with the Create issues permission (see below). If the ERP belongs to a client, limit the key to that client.
  3. Create a webhook with the address the integrator gives you and the events the ERP needs.
  4. Give the integrator the key and the webhook secret. Both are shown only once: copy them when you create them.
  5. Test in the test environment: a normal creation, the same notification sent twice, an unknown code and the closure of a work order.
  6. To go live, create a new key and a new webhook. The test ones are not reused.
  7. During the first week, check the webhook’s Deliveries every day.

The ERP key

  1. In API and data backups, click New key.
  2. Enter the Name, for example “SAP PM”.
  3. Tick Create issues. Tick Work orders too if the ERP has to read hours and materials.
  4. If the ERP belongs to a client, choose it in Only one client. That key can only have Create issues.
  5. Click Create key, click Copy and give it to the integrator.
The new key form with the “Create issues” permission ticked and a client chosen in “Only one client”.
The new key form with the “Create issues” permission ticked and a client chosen in “Only one client”.

A single-client key always creates issues for that client and only with that client’s assets. It does not see other clients’ issues either. The other key options are in Create an API key.

The webhook

  1. In the Webhooks card, click New webhook.
  2. Enter the Name and paste the Destination URL (https) the integrator gives you.
  3. If you only want one client’s changes, choose it in Client.
  4. Tick the Events. To close the ERP’s notifications, Work order closed, Issue closed and Issue rejected are usually enough.
  5. Click Create webhook, copy the secret and give it to the integrator.
  6. Click Test: Maptainer sends a test notification and shows what the ERP answered.
The Webhooks card of the API and data backups screen, still without webhooks.
The Webhooks card of the API and data backups screen, still without webhooks.
The new webhook form with the destination URL and three events ticked.
The new webhook form with the destination URL and three events ticked.

Deliveries, retries, rotating the secret and what happens if the ERP stops answering are in Webhooks and Deliveries, retries and deactivation.

How notifications come in from the ERP

A notification from the ERP comes in as a pending issue, with Integration (API) in Source/Channel. From there it follows the same path as any other: it is reviewed, turned into a work order and closed. The client’s SLA, the sector’s branch and the usual alerts apply to it.

  • Type, criticality and assets arrive by their code. That is why the code of each asset in Maptainer should be the same as in the ERP.
  • The ERP’s notification number is stored with the issue. Maptainer does not allow two issues with the same number.
  • No duplicates: if the connection fails and the ERP repeats the request, no second issue is created.
  • No asset: the ERP can send an address or coordinates.

Current limitation

The ERP’s notification number is not shown on the issue record: Maptainer stores it and it travels in the webhooks. Workaround: have the ERP also put it at the start of the title.

How changes go back to the ERP

Every time something the webhook has ticked happens, Maptainer sends a notification to the ERP within seconds. A work order’s notification carries the issues it resolves, with their ERP notification number: that way the ERP knows which notification to close.

Event Usual use in the ERP
Work order closed Close the notification and book hours and material
Work order completed or validated Mark the notification as finished, if the client closes later
Issue closed or resolved directly Close the notification when no work order was needed
Issue rejected Close the notification as “not applicable”
Issue approved (with WO) Set the notification “in process”
Measurement confirmed or voided Record the measured quantity (kilos, litres, hours) or withdraw it. See Measurements
Third-party handover recorded Record the dispatch to the waste manager or plant, with its delivery note

If the ERP does not answer, Maptainer keeps trying for almost two days. If it accepts no notification for 3 days, the webhook is disabled automatically and the administrators receive an email.

Equivalences with SAP PM and Business Central

Each ERP’s tables are different, but the concepts match. Technical names are a guide: the integrator confirms them in the client’s installation.

Maptainer SAP PM Business Central
Issue Maintenance notification (types M1 and M2) Not standard. With the Service module, a service order line
Work order Maintenance order Service order, with the Service module; otherwise a job
Asset Equipment or functional location Fixed asset or service item
Issue type Notification type or damage code —
Criticality Priority: 1 Critical, 2 High, 3 Medium, 4 Low Service order priority
Maintenance type Order type and activity type Service order type or job task
Client Customer Customer
Branch Maintenance planning plant Dimension or location
Item and warehouse Material and storage location Item and location
Hours of an order Time confirmation Job journal or service line
Material used Goods issue to the order Item journal or service line

Statuses translate like this (a proposal, adjusted in the mapping sheet):

Maptainer SAP PM
Issue pending Notification outstanding
Issue approved Notification in process
Issue resolved or closed Notification completed
Issue rejected Notification completed with a rejection reason
Order pending Order created
Order in progress or paused Order released
Order completed Order released with final confirmation
Order validated or closed Technically completed (and closed after settlement)
Order cancelled Deletion flag or closure without cost

Mapping sheet

It is filled in with the client at the first meeting. Each answer is a decision the integrator needs to build the integration.

# Decision Proposal
1 Which flows: notifications to issues, closures to the ERP, costs to the ERP, data copy
2 Which ERP notification types are sent to Maptainer
3 Equivalence of each notification type or damage code with an issue type One row per value
4 Equivalence of priorities and criticalities 1 Critical, 2 High, 3 Medium, 4 Low
5 Whether asset codes are the same in both systems They should be
6 Equivalence of clients
7 One key for the whole company or one per client One per client if each has its own ERP
8 Which event closes the notification Work order closed
9 Whether hours and material are booked, and to what: the order, the notification or a job
10 Rate or cost centre for the hours
11 Webhook address and who keeps the secret
12 Who receives the email if the webhook is disabled Maptainer administrators
13 Test environments of both systems

For whoever programs the integration

Everything technical is in API reference, at the top right of API and data backups: each call, the body of each webhook and how its signature is checked.

The API reference with the calls to create and look up issues.
The API reference with the calls to create and look up issues.

The essentials, for the first conversation with the integrator:

Topic How it works
Creating a notification POST /issues with the key in the X-API-Key header. Type, criticality and assets by code; the codes come from GET /issues/catalog
Notification number The external_ref field. A second creation with the same number is rejected and says which issue exists
Retries without duplicates The Idempotency-Key header, one per notification: repeating the call within 24 hours returns the same response
Webhooks Signed according to the Standard Webhooks standard. Answer 2xx in under 10 seconds; each notification carries an identifier to discard repeats
Hours and material In the closure notification itself (total active time, actual start and end) and by reading the order’s data
Avoiding loops Each notification says whether the change was made by an API key, so the ERP does not resend the echo of its own creations
Quotas 120 reads and 60 creations per minute and key

Current limitations

  • Only issues can be created through the API: the ERP cannot create work orders or change or cancel issues already created.
  • Webhooks notify about work orders and issues; not about assets, stock or readings.
  • The hours and material of one order cannot be requested on their own: they are read in batches.
  • The API gives hours and quantities, not amounts: the ERP values them with its rates.
  • The ERP’s notification number is not shown on the issue record.

Common problems

Symptom Likely cause Solution
The webhook shows as Inactive The ERP accepted no notification in 3 days When the ERP works again, click Activate and resend what is pending from Deliveries
Test says the certificate is not valid The integrator’s server has an expired or self-signed certificate The integrator has to install a valid certificate
The webhook URL cannot be saved It does not start with https:// or points to an internal address Ask the integrator for a public https address
The ERP says the notification already exists There is already an issue with that notification number That is correct: the issue was already there. The integrator should treat it as created
The ERP says an asset code is ambiguous Several Maptainer assets share that code Fix the repeated codes or ask the integrator to use the asset’s identifier
The ERP cannot read hours with its key The key only has Create issues Create another key with Work orders: a key’s permissions cannot be changed. A single-client key cannot read

Last updated: