Synerise objects

Synerise object fields are powerful tools which let you access data from other Synerise modules.

Common field properties

These properties exist in multiple field types:

• Display name (required): A human-readable name for the field, shown in the record editor.
• API name (required): A system name for the field.
  • In the {{ record.APIname }} insert, this name is the APIname
  • When retrieving/creating/updating a record with the API, this name is the identifier of the field.
  • When generating an object from a record, this is the name of the key that stores the field's value.
• Description: A human-readable description of the field's purpose, shown in the record editor.
• Block record-level overwriting: Disables changing any values in this field in individual records. You must provide a default value, which will be applied to all records in the schema.
• Return null when object is missing: If the requested object (such as an expression result or external source) doesn't exist, the field returns null instead of causing an error in content generation.
• Conditional visibility: Enforces adding a value to a field when another field meets a condition.
  See explanation below.
• Use as record title: If the record doesn't have a set name, the value of the field is used as the name.
• Required field: A record can only be saved if a value for this field is provided.
• Default value: The provided value will be used for object generation in records where a value is not set.
  This is only used when a value isn't defined in a record. It is not a fallback. For example, if an expression referenced in a record returns null or an error, the system doesn't use the default value. Default values are optional.
• Unique values only: No other record in the schema may have the same value for this field.
  You can use this to store your own unique record identifiers.
  The number of fields with this setting is limited.
• Enable search & filtering: The value can be used when searching and filtering records.
  The number of fields with this setting is limited.

Conditional visibility

You can enforce entering a value into a field when another field meets a condition. If the condition isn't met, the field with this setting isn't visible in the schema editor/viewer.

The field that appears when the condition is met must have a default value (because it's required).

Example:

Operators:
The available operators depend on the type of the field that is checked:

Synerise object field summary

When creating schemas and defining records, you can leverage existing data within Synerise by adding Synerise objects as fields. These objects enable advanced personalization and dynamic content, such as:

• personalizing messages using expression or aggregate results
• implementing social proof through metric insights
• delivering AI-driven item recommendations
• distributing discount codes
• displaying detailed information stored in catalogs

^1,2The number of fields with this setting is limited.

Single and multiple values

These field types can store one object or a list of objects: Expression, Metric, Aggregate, Voucher, AI recommendation, and Catalog.

Configuring the field in a schema

When you add one of these fields to a schema, in Value type, select one of the following options:

• Single value: The field references one object, for example, one expression or one recommendation campaign.
• Multiple values: The field references a list of objects, for example, several expressions or several recommendation campaigns. The number of objects in the list and the number of multiple-value fields in a schema are limited.

The value type doesn't limit the number of results. For example, a single-value AI recommendation field generates recommendations from one campaign, and that campaign can return many items.

You can't change this setting after the field is created.

If you select Multiple values, you can define how the field handles objects that can't be loaded (for example, because they were deleted or return an error):

Adding objects in a record

To add an object to a multiple-value field in a record, click the button for the object type, for example, Add metric. To change the order of the objects, drag them by the handle on the left.

Some field types work differently:

• Catalog: You select one catalog and add items from it by clicking Add item.

  

• AI recommendation: You provide one context item ID for the whole list, in the Item context field above the list. It applies to all recommendations in the list.

  

Generated content

When a field stores multiple values, the generated content is a list of results, in the order set in the record. In Expression, Metric, Aggregate, Voucher, and Catalog fields, each element of the list has the same format as the result of a single-value field. For example, a Voucher field with two voucher pools returns:

[
    {
        "barcode": "5281235506"
    },
    {
        "barcode": "ThisIsTheCode68"
    }
]

In an AI recommendation field, each element of the list is a separate recommendation frame with its own data and extras objects.

Dynamic keys

Expression, Metric, and Aggregate fields can use objects with dynamic keys. To provide the values of dynamic keys in records, select an object with dynamic keys as the default value of the field:

1. In the field configuration in the schema, select Default value.
2. Select an object that uses dynamic keys.
   The Dynamic keys section appears, with a field for each dynamic key of the selected object.
3. For each dynamic key:
   1. Click the icon on the left side of the field and select the format of the value: String or Jinjava.
      The format can't be changed per record.
   2. Enter the default value of the key.

In a record, the Dynamic keys section shows the keys of the default object, regardless of the object selected in the record. You can change their values.

If the field has no default value, or the default value doesn't use dynamic keys, the section isn't available in records. Objects with dynamic keys are then calculated with the key values defined in the object itself.

Dynamic keys in single-value fields

In a record, you can select any object, with or without dynamic keys. You can only provide values for the keys of the default object.

Example: The default metric uses the shopId dynamic key. In a record:

• If you select another metric that uses shopId, you can change the value of shopId for that metric.
• If you select a metric that uses shopId and region, the Dynamic keys section shows only shopId. You can't provide a value for region.
• If you select a metric without dynamic keys, the Dynamic keys section still shows shopId.

Dynamic keys in multiple-value fields

In a multiple-value field, the default value is a list of objects. In the schema, you can add objects to it by clicking the button for the object type, for example, Add metric.

All objects in the field must use the same set of dynamic keys:

• In the schema, the first object on the default list determines the set of dynamic keys. You can only add objects with the same set of dynamic keys to the default list.
• In a record:
  • If the default value uses dynamic keys, you can only add objects that use exactly the same set of dynamic keys.
  • If the default value doesn't use dynamic keys or isn't set, you can only add objects without dynamic keys.

Objects that don't meet this condition are grayed out in the selection list.

The values of dynamic keys apply to all objects in the field. You provide them once for the whole list, not for each object separately.

Example: The default metric uses the shopId dynamic key. You can add other metrics that use only shopId. A metric that uses shopId and another dynamic key is grayed out.

Synerise object field reference

Profile attribute

This field lets you insert the value of an attribute from the profile for which content is generated from a record.

Field configuration in a schema

In Default value, you can select the default attribute to be inserted.

Expression

This field type lets you select an expression. The result of the expression is calculated in the context of a profile when generating an object from a record.

You can only use attribute expressions (Expressions for: Attribute) in this field.

Field configuration in a schema

1. In Value type, select Single value or Multiple values.
   For details, see Single and multiple values.
2. In Default value, you can select the default expression.
   The default expression also defines which dynamic keys can be set in records. For details, see Dynamic keys.
3. If you want to return the full scope of information about the expression, select the Include details in results checkbox.

Object generation example

Expressions don't require extra parameters in the object generation request.
In the following example, an expression calculates the age of the customer.

{
    "name": "Demo calculate age",
    "clientId": 11804828266,
    "result": 26,
    "expressionId": "b2c5cc0b-2830-435f-82a6-a2f0ebadd6d9",
    "variables": [],
    "title": "Demo calculate age "
}

26

Metric

This field type lets you select a metric. The result of the metric is calculated in the context of a profile when generating an object from a record.

Field configuration in a schema

1. In Value type, select Single value or Multiple values.
   For details, see Single and multiple values.
2. In Default value, you can select the default metric to calculate.
   The default metric also defines which dynamic keys can be set in records. For details, see Dynamic keys.
3. If you want to return the full scope of information about the metric, select the Include details in results checkbox.

Object generation example

Metrics don't require extra parameters in the object generation request.

{
    "result": 10770077,
    "numberMetrics": [],
    "clientMetrics": [],
    "eventMetrics": []
}

10770077

Aggregate

This field type lets you select an aggregate. The result of the aggregate is calculated in the context of a profile when generating an object from a record.

Field configuration in a schema

1. In Value type, select Single value or Multiple values.
   For details, see Single and multiple values.
2. In Default value, you can select the default aggregate.
   The default aggregate also defines which dynamic keys can be set in records. For details, see Dynamic keys.
3. If you want to return the full scope of information about the aggregate, select the Include details in results checkbox.

Object generation example

Aggregates don't require extra parameters in the object generation request.
In the following example, the aggregate returns an item ID.

{
    "dateFilter": {
        "type": "RELATIVE",
        "duration": {
            "type": "DAYS",
            "value": 30
        },
        "offset": {
            "type": "DAYS",
            "value": 0
        },
        "timeZone": "Europe/Warsaw"
    },
    "clientId": 11804828266,
    "result": "WINDBREAKER ZEPHYR",
    "variables": [],
    "analyticVersion": null,
    "title": "Last seen item from jacket category",
    "aggregateUuid": "8c950378-82fd-320d-abec-b90cec5208d5",
    "aggregateId": "8c950378-82fd-320d-abec-b90cec5208d5"
}

"WINDBREAKER ZEPHYR"

Voucher

This field type lets you return a code from a voucher pool.

Field configuration in a schema

1. In Value type, select Single value or Multiple values.
   For details, see Single and multiple values.
2. In Default value, you can select a default pool to get codes from.
3. If you want to assign a voucher and always return the same voucher in subsequent requests for this profile, select the Assign to user checkbox.
   This setting can be changed per record.

Object generation example

The voucher code is returned in the barcode key.
Vouchers don't require extra parameters in the object generation request.

{
    "barcode": "23123321321"
},

AI recommendation

This field type lets you include AI recommendations.

For each record, you can select a recommendation and display its results while generating an object with the record result. If a selected recommendation model requires an item context, you must provide it. The system checks for the context item in the following order:

1. ID provided in the object generation request.
2. ID from the record.
3. Default ID from the schema.

In the "Recommendation model summary" section, you can find a table in which you can check which recommendation models require an item context.

Field configuration in a schema

1. In Value type, select Single value or Multiple values.
   For details, see Single and multiple values.
2. From the Item context format dropdown list, select how the context item ID is inserted:
   • String to provide a static string.
   • Jinjava to provide an insert from which the ID will be extracted.
     The value can be changed per record or when generating an object from the record, but the type (static string or Jinjava) is enforced by the schema.
     See the Recommendation model summary to learn when a context item ID is required.
     If the field stores multiple recommendations, the context item ID applies to all of them.
3. In Default value, you can set the default:
   • Recommendation campaign
   • Context item ID

Object generation example

"fieldContext": {
    "exampleRecommendation": {
        "itemId": "dd9f0a0e6ca8f385776c14de9dd277",
        "additionalFilters": "brand == exampleBrand"
    }
}

{
    "data": [
        {
            "name": "Infurniture - Jazmin Wine Glass",
            "price": 59,
            "brand": {
                "id": "86",
                "label": "Infurniture"
            },
            "product_subtype": {
                "id": "113",
                "label": "Wine Glass"
            },
            "itemId": "dd9f0a0e6ca8f385776c14de9dd277",
            "category": "Root Catalog > Default Category > Home > Glasses",
            "productUrl": "https://demoshop.synerise.com/infurniture-jazmin-wine-glass.html?snrai_campaign=yYjFMYPeofN5&snrai_id=9bbaee0d-b2d1-4a0f-9af2-1f2d49ae28d4",
            "image": "https://demoshop.synerise.com/media/catalog/product/d/d/dd9f0a0e6ca8f385776c14de9dd277.png"
        },
        {
            "name": "Lahome - Arcangel Chef's Knife",
            "price": 139,
            "brand": {
                "id": "87",
                "label": "Lahome"
            },
            "product_subtype": {
                "id": "123",
                "label": "Chef's Knife"
            },
            "itemId": "a84fe2f02fc18986600f956bb22864",
            "category": "Root Catalog > Default Category > Home > Knives",
            "productUrl": "https://demoshop.synerise.com/lahome-arcangel-chef-s-knife.html?snrai_campaign=yYjFMYPeofN5&snrai_id=9bbaee0d-b2d1-4a0f-9af2-1f2d49ae28d4",
            "image": "https://demoshop.synerise.com/media/catalog/product/a/8/a84fe2f02fc18986600f956bb22864.png"
        },
        {
            "name": "Homeset - Montell Bread Knife",
            "price": 389,
            "brand": {
                "id": "85",
                "label": "Homeset"
            },
            "product_subtype": {
                "id": "124",
                "label": "Bread Knife"
            },
            "itemId": "3640594393744b17d72aa3996c25f7",
            "category": "Root Catalog > Default Category > Home > Knives",
            "productUrl": "https://demoshop.synerise.com/homeset-montell-bread-knife.html?snrai_campaign=yYjFMYPeofN5&snrai_id=9bbaee0d-b2d1-4a0f-9af2-1f2d49ae28d4",
            "image": "https://demoshop.synerise.com/media/catalog/product/3/6/3640594393744b17d72aa3996c25f7.png"
        }
    ],
    "extras": {
        "campaignId": "yYjFMYPeofN5",
        "contextItems": null,
        "correlationId": "9bbaee0d-b2d1-4a0f-9af2-1f2d49ae28d4",
        "slots": [
            {
                "id": 0,
                "itemIds": [
                    "dd9f0a0e6ca8f385776c14de9dd277",
                    "a84fe2f02fc18986600f956bb22864",
                    "3640594393744b17d72aa3996c25f7"
                ],
                "name": "Unnamed slot",
                "rows": null
            }
        ]
    }
}

AI Search

This field lets you show the results of an AI search query.

Field configuration in a schema

1. From the Query format dropdown list, select how the query can be entered:
   • String to provide a static string.
   • Jinjava to provide an insert from which the query will be extracted.
     The value can be changed per record or when generating an object from the record, but the type (static string or Jinjava) is enforced by the schema.
2. In Default value, you can select the default:
   • Search index
   • Query text

Object generation example

The result in a generated object is a response from the /search/v2/indices/{indexId}/query endpoint.

{
    "data": [
        {
            "itemId": "example1"
        }
    ],
    "extras": {
        "facetsOrdering": [],
        "appliedRules": [],
        "suggestions": [],
        "searchId": "fb4f34dec80bcf2be335b6bd0602e7b9",
        "correlationId": "fb4f34dec80bcf2be335b6bd0602e7b9"
    }
}

AI Search listing

This field lets you show the results of an AI search listing query.

Field configuration in a schema

In Default value, you can select the default search index.

Object generation example

The result in a generated object is a response from the /search/v2/indices/{indexId}/list endpoint.

{
    "data": [
        {
            "itemId": "example1"
        },
        {
            "itemId": "example2"
        },
        {
            "itemId": "example3"
        }
    ],
    "extras": {
        "facetsOrdering": [],
        "appliedRules": [],
        "searchId": "fb4f34dec80bcf2be335b6bd0602e7b9",
        "correlationId": "fb4f34dec80bcf2be335b6bd0602e7b9"
    }
}

Catalog

This field type lets you select a Synerise catalog and an item from that catalog. The item's data, including the primary key, is included in the response when an object is generated from a record.

Field configuration in a schema

1. In Value type, select Single value or Multiple values.
   For details, see Single and multiple values.
2. From the Primary key format dropdown list, define how you will provide the context:
   • String to provide a default static ID of the product which will serve as the context.
   • Jinjava to provide a default insert from which the ID will be extracted.
     The values can be changed per record, but the type (static string or Jinjava) is enforced by the schema.
3. In Default value, you can set the default:
   • Catalog ID
   • Primary key value (unique identifier of an item in the catalog)

Object generation example

"context": {
    "keyName": "sku1234"
}

{
    "itemId": "sku1234",
    "name": "WINDBREAKER ZEPHYR",
    "color": "blue"
}