Sync Markers

Make sure you familiarize yourself with the other important concepts of our API:
Prices and Quantities, Products and Articles
After taking the time to understand these concepts, you will much better understand the basics of our API.

Contents

Introduction

A syncMarker will help you to create an efficient and fast synchronization process.
They are available for the following items:

  • Products & Articles
  • Relations
  • employees
  • Orders
  • Invoices
  • Receipts

Let’s imagine that you want to build an application that synchronizes all invoices from Mplus to another system.
You could simply retrieve all invoices everytime you do a synchronization, but that will severely impact performance as more and more invoices are added to the system.
A smarter idea would be filtering invoices by date using the fromFinancialDate and throughFinancialDate parameters.
But what if an invoice is changed in Mplus after you have already processed the date of that invoice?
The best way to solve that problem and properly implement synchronization is using the syncMarker parameter.

How the syncMarker works

The syncMarker is a continuous sequence of integers that is raised by one everytime an item is changed, regardless of the initial creation date of the item. The syncMarker is passed along as an additional parameter when the item is retrieved through the API. Each type of item listed above has their own sequence of integers.

You should save an internal value of the syncMarker to use in your synchronization.
When you perform synchronization for the first time, your internal syncMarker should typically be set to a value of 1. That way you start from the beginning.

PHP
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
<?php
 
require_once('Mplusqapiclient.php');
 
$mplusqapiclient = new Mplusqapiclient();
// Initialize the client with your details.
 
$syncMarker = get_internal_invoices_syncmarker(); // this should be 0 the first time you synchronize
 
$syncMarker++; // Add 1 because you're only interested in the new items, and not the last one.
 
// Then we call the getInvoices() function wrapped in a try/catch block to intercept any exceptions.
try {
  if (false !== ($invoices= $mplusqapiclient->getInvoices($syncMarker))) {
    // Success, we show the amount of found invoices and store the highest syncMarker we encountered.
    echo sprintf('Found %d invoices.', count($invoices));
    // First we do whatever processing we want to do with the invoices:
    process_invoices($invoices);
    // Then we determine the next max_syncMarker:
    $max_syncMarker = $syncMarker;
    foreach ($invoices as $invoice) {
      if ($invoice['syncMarker'] > $max_syncMarker) {
        $max_syncMarker = $invoice['syncMarker'];
      }
    }
    save_internal_invoices_syncmarker($max_syncMarker);
    exit;
  } else {
    exit('Failure while getting invoices.');
  }
} catch (MplusQAPIException $e) {
  exit($e->getMessage());
}

Let’s assume this call retrieved the following invoices:

PHP
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
$invoices = array(
  array(
    'invoiceId' => '09e2d578-b101-11e4-af90-12e3f512a338',
    'syncMarker' => 1,
    ...
  ),
  array(
    'invoiceId' => '1ce362aa-b101-11e4-af90-12e3f512a338',
    'syncMarker' => 4,
    ...
  ),
  array(
    'invoiceId' => '200f09b6-b101-11e4-af90-12e3f512a338',
    'syncMarker' => 3,
    ...
  ),
);

Because the highest value of syncMarker in these results is 4, you save that value of 4 as your internal syncMarker.

When the next invoice is added or changed in Mplus, that invoice will get a syncMarker value of 5. The next time you perform the synchronization, you use your own internal syncMarker value of 4, you add 1 to that before you do the request, and you will only receive this next invoice in the results, because it has a syncMarker value of 5.

This time around you save the value of 5 to your internal syncMarker. Everytime you synchronize you repeat this process.

getCurrentSyncMarkers Retrieves list of all syncMarkers

This function shows the highest syncMarker of each type.

PHP
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
<?php
 
require_once('Mplusqapiclient.php');
 
$mplusqapiclient = new Mplusqapiclient();
 
// Then we call the getCurrentSyncMarkers() function wrapped in a try/catch block to intercept any exceptions.
try {
  if (false !== ($syncmarkers= $mplusqapiclient->getCurrentSyncMarkers())) {
    // Success
    exit('Syncmarker list retrieved');
  } else {
    exit('Unable to retrieve syncmarkers.');
  }
} catch (MplusQAPIException $e) {
  exit($e->getMessage());
}

If successful, the variable $syncmarkers which we set in the example can have the following contents:

PHP
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
Array
(
  [articleSyncMarker] => 1012
  [articleGroupSyncMarker] => 0
  [relationSyncMarker] => 102
  [employeeSyncMarker] => 3
  [invoiceSyncMarker] => 169
  [receiptSyncMarker] => 105
  [orderSyncMarker] => 0
  [proposalSyncMarker] => 0
  [stockId] => 2012
  [purchaseOrderSyncMarker] => 0
  [purchaseDeliverySyncMarker] => 0
  [relationPointsSyncMarker] => 0
  [cashDrawerBalancingSyncMarker] => 0
  [activitySyncMarker] => 0
  [packingSlipSyncMarker] => 0
)

Syncmarker change overview

Here you find a functional overview of which actions trigger a change in syncmaker.

articleSyncMarker

  • Creating a new article
  • Changing a article
  • Deleting a article
  • New since V22: When a preparation method is added/changed

articleGroupSyncMarker

  • Creating a new webshoparticlegroup
  • Changing a webshoparticlegroup
  • Deleting a webshoparticlegroup
  • Changing the position of a webshoparticlegroup
  • Linking a article to a webshoparticlegroup

relationSyncMarker

  • Creating a new relation
  • Changing a relation
  • Deleting a relation

employeeSyncMarker

  • Creating a new employee
  • Changing a employee
  • Deleting a employee

invoiceSyncMarker

  • Creating a new invoice
  • Paying a invoice
  • Changing a invoice

receiptSyncMarker

  • Creating a receipt
  • Voiding a receipt
  • Printing a receipt for the first time

orderSyncMarker

  • Creating a new order
  • Changing a order
  • Adding a payment to the order

proposalSyncMarker

  • Creating a new proposal
  • Changing a proposal
  • Proccesing the proposal to order or invoice

stockId

  • Article sales
  • Creating or changing a order
  • Creating or changing a invoice
  • Creating or changing a purchase order
  • Creating or changing a purchase delivery

purchaseOrderSyncMarker

  • Creating a purchase order
  • Changing a purchase order

purchaseDeliverySyncMarker

  • Creating a purchase delivery
  • Changing a purchase delivery

relationPointsSyncMarker

  • Increasing or decreasing points on a relation

activitySyncMarker

  • Creating a new activity
  • Changing a activity
  • Deleting a activity
  • Linking an activity

packingSlipSyncMarker

  • Creating a new packingslip
  • Changing a packingslip
  • Processing the packingslip

SyncMarkerLimit

The default syncMarkerLimit is 1000.
When you you want to change the syncMarkerLimit keep the following in mind:

  • The syncMarkerLimit is capped at 10000 records
  • It will return all articles with a syncmarker below the given limit