Custom entities

The Custom entities module allows platform users to extend factory entities and introduce new entities in the loyalty program management. This way, the range of data fields that Antavo can store and provide through APIs upon request can be widened.

Find the configuration page of the Custom entities module by clicking on the icon in the sidebar and typing 'Custom entities' into the search bar of the Modules menu. The page will open to the list of entities that are already set up.

• Label

• Name of the entity

• Type of the field (built-in/custom)

Open

Configuring custom entities

Create custom entities

• Click the ‘Create new custom entity’ button in the sidebar on the left

• Define the unique ID of the new entity – the machine-readable ID of the entity that can be used to refer to the entity in the Antavo APIs

• Add a label – the human-readable name of the entity that is the displayed name of the entity in the Antavo Backoffice and is accessible through the API as well

• Write the description of the entity

• Select the database collection where the new entity is stored

• Enable the 'Auto increment ID' option if you need Antavo to generate IDs for each entity item introduced later

• Click ‘Save’

Open

Activate an entity

After saving for the first time, the status of the custom entity is ‘inactive’, which means it is not usable in API calls and appears only in the list of custom entities on the module configuration page.
You can activate the custom entity right away using the ‘Set active’ button on the upper right-hand side of the setup page and confirm the activation in the dialog that subsequently appears.

Please note, that custom entities can be created, however, entity items cannot be added in the Antavo Backoffice yet.

Managing custom entities

Edit an entity

Follow these steps to modify the custom entity.

• Go to the Custom entities page

• Click the ‘Edit’ button of the entity that you would like to update

• Edit the entity

• Save the changes by clicking ‘Update’

Please note, that in the case of factory entities, only the label and the description can be edited.

Inactivate an entity

Follow these steps to deactivate the custom entity.

• Go to the Custom Entities page

• Click the ‘Edit’ button of the entity that you would like to update

• Click ‘Set inactive’

• Confirm in the dialog that subsequently appears

While inactive, the entity cannot be accessed through API.

Delete an entity

Entities cannot be deleted from the Backoffice. To stop using an entity, please deactivate it.

Adding custom entity attributes

When navigating to the ‘Attributes’ tab of the editor interface of any entity, you’ll first find the list of attributes that are already available with the following information:

• Label

• Unique ID

• Type of the attribute

• Tags associated

Create a new attribute

• Click the ‘Edit’ button of the entity that you’d like to add a new attribute to

• Click the ‘Create new attribute’ button in the sidebar on the left

• Add a label – the human-readable name of the entity that is the displayed name of the attribute in the Antavo Backoffice that is accessible through the API as well
  Tip: by defining the label of the attribute as ‘label’, you can store the name value of a specific entity in an attribute that is called ‘label’

• Define the unique ID of the attribute – this has to be a machine-readable ID of the attribute that can be used to refer to the attribute in the Antavo APIs

• Write the description of the attribute

• Select the field type
  Select the type of data that is stored in the field. When sending the data through API, make sure that it is sent in the format required by the selected type, otherwise the API request will fail.

  • String

  • Numeric

  • Boolean

  • Select - add the selectable options by defining possible values

  • Url

  • Date

  • Datetime

  • Multiple choice - add the selectable options by defining possible values

  • List

  • Image
    Choose this attribute type to upload images (png, jpeg, jpg type files) to any entity.
    Once saved, an image can be uploaded in the new field type (for example, a secondary image for a Reward).

  • Reference
    Use this type to tie the entity to an individual customer profile. When the reference type attribute is populated with a customer ID, the entity with all its attributes will appear on the corresponding entity tab of the profile of the referenced customer.
    This attribute type is not available for built-in entities and currently, only the customer reference is applicable.

  • Translatable
    Challenge entities can be expanded with translatable-type attributes to support multilingual sites. The configuration field of the attribute will appear in the challenge editor with a ‘Translate’ button. Use it to enter values for all languages added in the Multi-language module, so that you can query the translations through the Entities API to apply them on your website.

• Add a default value (only applicable for String, Numeric, Boolean and Url type attributes)
  You can enter a default value for entity fields.
  After the new entity attribute is activated, the default value will be automatically populated in all the entity items.

• Format (only applicable for String and List types of fields)
  The format of values can be further specified to Date, URL, Email, and Phone number formats, the API will validate the values accordingly.

• Add tags, if necessary
  Tags define the ways how attributes can be accessed and managed in the system.

  • API - the field is included in the response returned by the Entities API if it is included in the request (fields=<attribute>)
    In case you’d like to include the field without requesting it explicitly, please use the ‘Default API field’ checkbox described below.

  • searchable - any value of the field can be used as a search condition when requesting customer data through the Entities API

  • importable - the value of the field can be updated through the Imports module

  • groupable - the data values of the field can be grouped together when configuring charts to be displayed on the Dashboard

  • filterable - the field can be used as a filter condition when requesting customer data through the Entities API and filtering the list of entities on module configuration pages

  • unique - the same field value can only be registered once

• Set the access level
  Backoffice users from unselected access levels cannot access the attribute in the Backoffice.

• Fieldset
  Select/create a group where the attribute will appear on the editor interface.

• Default API field
  Tick the checkbox to enable the attribute to be added to API responses, without including the field in the request.

• Required
  If the attribute is ‘required’, make sure to add a default value to this attribute in the valid format. If the value of the required item is empty, you will not be able to make any further updates to the entity without adding a value to the item in the correct format.

• Click ‘Save’

Activate a custom entity attribute

After saved for the first time, the status of the custom entity attribute is ‘inactive’, which means it is not usable in API calls and appears only in the list of custom entity attributes on the module configuration page.
You can activate the attribute right away using the ‘Set active’ button on the upper right-hand side of the setup page and confirm the activation in the dialog that subsequently appears.

Manage custom entity attributes

Edit an attribute

Follow these steps to modify an entity attribute.

• Go to the Custom entities page

• Click the ‘Edit’ button of the entity that you would like to add the attribute to

• Navigate to the Attributes tab

• Click the ‘Edit’ button of the attribute you would like to update

• Edit the entity attribute

• Save the changes by clicking ‘Update’

Please note, that factory entities cannot be edited.

If you have set a default value or modified a previously added default value while editing the attribute, the value of the attribute will be populated on all entity items if the attribute was empty or populated with a previously configured default value.

Inactivate an attribute

Follow these steps to deactivate an entity attribute.

• Go to the Custom entities page

• Click the ‘Edit’ button of the entity that you would like to add the attribute to

• Navigate to the Attributes tab

• Click the ‘Edit’ button of the attribute you would like to update

• Click ‘Set inactive’

• Confirm in the dialog that subsequently appears

While inactive, the attribute won’t appear as configurable fields on the Backoffice or/and are not added to API responses.

Archive an entity attribute

Follow these steps to remove an inactive entity attribute.

• Go to the Custom entities page

• Click the ‘Edit’ button of the entity that you would like to add the attribute to

• Navigate to the Attributes tab

• Click the ‘Edit’ button of the inactive attribute you would like to update

• Click ‘Archive’

• Confirm in the dialog that subsequently appears

Please note, that only inactive entities can be archived.

Extending factory entities

Factory entities can also be extended with custom attributes within the Custom entities module.

Enable the extension of a factory entity

• Click the ‘Extend factory entity’ option in the sidebar on the left

• Select the factory entity that you’d like to extend
  The following entities may be available if the required module is enabled.

• Click ‘Extend’

• Click the ‘Save’ button on the entity editor interface
  You can choose to edit the label and the description of the entity here.

Manage factory entities

Once the factory entity has been enabled to be extended, it appears among the list of entities on the module configuration page and can be edited the same way as a custom entity.

Add an attribute to a factory entity

New attributes can be added and later managed as well, please follow the steps of creating and managing a custom attribute explained above.