PlanningPME API - Custom integration

PlanningPME provides a custom integration API, for synchronizing PlanningPME data with tier-applications.

This document answers the following questions:

Why a "custom" integration API?
How custom integration API works?
What kind of integration can be made out-of-the-box?
How can we help with very specific integration?
How to make an integration request?

Why a "custom" integration API?

Synchronizing data between services is a common matter these days. Different services may require the same piece of data, but nobody wants to manage this data twice.
PlanningPME provides the tools to exchange data with the rest of you information system.

In practice, it is not always possible to adapt a data export to the constraints of the system that will use them. And you may not want to adapt your data to a new model to share with another application.
PlanningPME provides you with this flexibility towards data acquisition and presentation with the custom integration API.

This flexibility applies to your proprietary applications as well as the most widespread applications, such as CRM (SalesForce, Microsoft Dynamics ...) or ERP (SAP, Oracle ...).
PlanningPME works on the continuous implementation of exchange models specific to the most used applications on the market.

In summary, the custom integration API has two major advantages over the traditional API:
  • it works with templates that are fully adapted to your own data model,
  • it allows mass synchronization in a single query, thus avoiding quota restrictions.

How custom integration API works?

Model definition allows all the flexibility needed for data acquisition and presentation.
There are two types of templates: import templates for importing data to PlanningPME, and export templates for exporting PlanningPME data.
An import template defines the matching between the fields received and the PlanningPME fields, while an export template defines the correspondence between the exported fields of PlanningPME and those of the target application.
A template also defines the formatting or coupling of data, as well as default values and processing.

Sample import template

<In>
	<Type Name="Customer" ShouldInsert="true" ShouldUpdate="true">
		<Default Field="Type" Value="1026" />
	</Type>
	<Property Name="Nom usage" Type="Customer" Field="LastName" />
	<Property Name="Téléphone mobile" Type="Customer" Field="Mobile" />
	<Property Name="Email" Type="Customer" Field="Email" />
	<Property Name="ID_DOSSIER" Type="Customer" Field="_IDDOSSIER" />
</In>

In this template, we define a customer import that can insert or update data.
A default value is defined for the type of customer (all clients are individuals).
Finally, we define the correspondence between the fields received and the PlanningPME fields (whether custom fields or generic fields).

As soon as it is implemented on your API, this model allows you to import data without worrying about the PlanningPME schema.

Ready-to-use integration templates

Those ready-to-use templates are available by default in each API installation:

This list is expected to grow as and when requests for known third-party applications, or for generic needs.

Specific case implementation

Expose your specific request to our support so that it studies it and generates a new template entirely adapted to your case (development costs can be established according to the complexity of the integration).

Customized templates are frequently implemented for customers who want to do mass synchronization without the risk of reaching the usage quota limitations of their APIs.

Most of the time customers also simply want to use their own data model to interact with PlanningPME. This is what the custom integration API allows, regardless of the level of complexity of the original model.
It happens, for example, that the same entity of the original model corresponds to different entities in the PlanningPME model. The custom integration makes it possible to split the same line on several entities, which greatly facilitates this kind of synchronizations.

Whatever the integration to expect, our response will be custom to your needs and your environment.
We will be happy to work with you on its development.

Do not hesitate to contact us for more information or to specify your integration.

Examples of API custom integration requests

The custom integration API is part of the PlanningPME API, please refer to the developer documentation for the basics of interaction with the API.

Integration templates

The custom integration templates installed on your API can be retrieved using the following call.

GET /your_brand/api/integration/templates HTTP/1.1
Host: api.planningpme.com
X-APPKEY: your_key
Authorization: your_token

This method returns the installed data import and export templates and their detailed description.

Export based on a specific template

Export templates return the data found in the PlanningPME database.

GET /votre_marque/api/integration/your_template?since=20181231045803 HTTP/1.1
Host: api.planningpme.com
X-APPKEY: your_key
Authorization: your_token

The parameter "since" (optional) allows to indicate to the template that only the elements created and modified after this date (format yyyyMMddHHmmss) must be exported.
In the absence of the parameter all the elements corresponding to the requested model are returned.

Import based on a specific model

Import templates (marked "in") expect data to be inserted or modified in the PlanningPME database.

POST /your_brand/api/integration/your_template HTTP/1.1
Host: api.planningpme.com
X-APPKEY: your_key
Authorization: your_token

{
	simulate: false,
	verbose: false,
	stopOnError: false,
	model: {
		...
	}
}

Execution parameters of an import (in addition to the mapping predefined in the model) are the following:

  • simulate (boolean, defaults to false): allows simulation of an import, if true the response will be a report of all the insertions and modifications that would have been applied in base otherwise, allowing you to validate an import model before executing it on your production data,
  • verbose (boolean, defaults to false): indicates whether the method should return a report of processed operations,
  • stopOnError (boolean, defaults to false): if true the import will stop as soon as an error is encountered, if false the import will continue with following elements,
  • model: imported data as a JSON object, structured according to the specific model defined.

Customer import

POST /your_brand/api/integration/client-import HTTP/1.1
Host: api.planningpme.com
X-APPKEY: your_key
Authorization: your_token

{
	simulate: false,
	verbose: false,
	stopOnError: false,
	model: {
		...
	}
}

Project import

POST /your_brand/api/integration/project-import HTTP/1.1
Host: api.planningpme.com
X-APPKEY: your_key
Authorization: your_token

{
	simulate: false,
	verbose: false,
	stopOnError: false,
	model: {
		...
	}
}