Skip to main content

Labels & Extended Properties

To help both users and developers to organize, slice and dice entities in the system, Onslip 360 provides two powerful annotation features that works on all resource entities, be it products, customers, tabs, orders or any other resource the user has write access to: labels1 and extended properties.

Labels​

Labels are small user-visible badges that can be freely attached to any stored entity in the system. Each label belongs to a label category, and labels that are part of the same category are usually presented near each other.

The user can optionally configure for which resources a label category is applicable to. This is mostly just a hint to the user interface; the system does not enforce this configuration and all labels can thus be attached anywhere by using the API.

Labels and label categories are very useful for filtering. Some example label categories include customer loyalty levels, ingredients or allergens, genres, and employee categories, but really, a label can be anything that can be represented by a string.

Labels are attached to entities by including the label ID in the labels list property.

Extended Properties​

Primarily aimed at developers/integrators, extended properties are key-value pairs a developer can attach to any entity or nested object therein (unlike labels, which may only be attached to the entity as a whole). They are not visible to users and always ignored by the backend system.

An extended property begins with an underscore followed by a namespace identifier, which is assigned by Onslip. Please contact us at api@onslip.com to reserve your namespace.

Except for this, these properties looks and functions just like any other kebab-case string property2. Their purpose is to make integrations with external systems easier. For instance, if a product or customer catalog is synchronized between multiple multiple services, external object identifiers or timestamps could be stored in an extended property.

For properties of which should be visible to the user, we recommend labels. However, for properties used only by machines, extended properties might be a good fit. Extended properties are attached to entities and subobjects just like any other property. The only difference is that they begin with an underscore.

Footnotes​

  1. A second, older type of entity annotation is tags, which is just one or more string values attached to the entity. Tags were previously used to categorize customers, but this feature has been superseded by labels. Tags are not visible to users anywhere and cannot be easily renamed, categorized or disabled. We do not recommend using tags and they may even be removed entirely from the system in the future. Use labels instead. ↩

  2. In rare cases, we even use these extended properties ourselves. For instance, to store the report period in Your Reports, the Onslip 360 Backoffice site uses an extended property named _onslip-report-period. However, the actual configuration the system uses to schedule and generate the report comes from the cron schedule and the from-expression and to-expression properties on the trigger. ↩