Data Extensibility

This is an overview of all the possible ways Erply's records can be extended with custom information.

1. Attributes

Ad-hoc key-value pairs, widely supported.

The simplest way to extend records is to attach attributes. Attributes are just arbitrary key-value pairs; you can make up an attribute name on the spot.

The value of an attribute can be a string, an integer or a floating-point value.

Interacting with attributes in Erply API generally looks as follows. You can attach or update attributes when saving a record:

clientCode:{{clientCode}}
sessionKey:{{sessionKey}}
request:saveCustomer
sendContentType:1
firstName:Abby
lastName:Cheesecake

attributeName1:membership_join_date
attributeType1:text
attributeValue1:2020-05-23

attributeName2:online_default_store_id
attributeType2:int
attributeValue2:16

The attributes are returned from a "get" call:

{
    "status": {
        "request": "getCustomers",
        ...
    },
    "records": [
        {
            "customerID": 29,
            "fullName": "Cheesecake, Abby",
            ...
            "attributes": [
                {
                    "attributeName": "membership_join_date",
                    "attributeType": "text",
                    "attributeValue": "2020-05-23"
                },
                {
                    "attributeName": "online_default_store_id",
                    "attributeType": "int",
                    "attributeValue": "16"
                }
            ]
        }
    ]
}

Lookup by attribute, or by a combination of multiple attributes, is supported:

sessionKey:{{sessionKey}}
clientCode:{{clientCode}}
request:getCustomers
sendContentType:1
searchAttributeName1:membership_join_date
searchAttributeValue1:2020-05-23

See, for example, the documentation of API calls getCustomers and saveCustomer. If an API call supports attributes, it is mentioned in its input/output documentation.

Attribute support in PIM API will be implemented soon. If attribute support is needed in other APIs, please submit us a feature request.

Caveats:

• Text attributes are limited to 255 characters in length.
• Heavy use (storing hundreds of thousands of attributes) might degrade account performance.

2. Long Attributes

Text attributes with a higher maximum length, but not supported for every type of object.

Work the same way as text attributes, but support storing 65,000 characters, instead of 255.

Long attributes are only supported in the following API calls:

• saveCustomer
• saveProduct
• saveSalesDocument
• getCustomers
• getProducts
• getSalesDocuments

3. Integration IDs

For customer records only. Meant to store ID correspondences and do lookups.

When integrating Erply with another system, it is often necessary to store ID correspondences—for example, that Erply customer ID 93 corresponds to customer ID 252 in the company's reporting system (or in the web shop database).

This can be solved by using attributes, but lookups by attribute may not be particularly fast. A better approach would be to use the purpose-built API calls:

• saveCustomerExternalId
• getCustomerIdByExternalId
• getExternalIdsByCustomerId
• getAllCustomerExternalIds
• removeCustomerExternalId

API call getCustomers supports lookups by "externalID" + "integrationName".

As seen from here, one record can simultaneously have multiple "external IDs", one for each integration.

4. Product Parameters

Specifically for products. Highly structured data, with a possibility to enforce validation rules.

To be documented in more detail.

5. JSON API

Supports all kinds of records, but requires schema to be predefined.

JSON API lets you attach data to any record, similarly to attributes.

The difference is that the custom data is stored in the same database table and on the same database row as the record's standard properties. (Attributes, in contrast, are stored in a separate table.) This makes JSON fields more efficient to index, and faster to query than attributes.

There are two other advantages:

1. Sales document rows do not support attributes, but they do support JSON. This use case has been illustrated in detail on the JSON API page.
2. There are no field length restrictions, unlike with attributes.

However, JSON API does not support ad-hoc use: it only accepts fields that have been defined in a global schema, for all accounts. This makes JSON API best suited for standard applications that will be used by many Erply customers. To have a field added to the global schema, you need to submit a request.

6. CAFA

For storing configuration.

CAFA (Configuration API for Front-end Applications) is best suited for storing application settings and user preferences.

As a bonus, the configuration can be layered. For a property, there can be a company-wide default value, and it can be overridden at store level, register level or per-user. Alternatively it is possible to separate company-wide settings from users' personal preferences.

Caveats:

• Each application must define its own configuration namespace, to avoid collisions. CAFA will also require you to grant explicit permissions to users, to access that namespace. The process of defining and granting these permissions is not well-defined yet, and needs to be documented further.

7. Builder

Database-as-a-service: define a whole new relational data model.

In case you want to store whole objects which cannot be defined in standard Erply at all, you can use Builder.

Builder lets you define your own full-featured relational data model, complete with data types, foreign keys and referential integrity. When you deploy a data model, Builder will automatically generate a corresponding REST API interface for manipulating the records and for querying them; use this API to read and write data.

To be documented in more detail.