Quick start

This article contains guidelines on schemas and records.

Prerequisites

To be able to create schemas and records on the user interface, you must be assigned a role with the Brickworks user permissions.

Schema setup workflow

1. Connect to external sources (optional)
   Establish connections to external services or APIs to fetch data that will be integrated into your schema. This step is optional but often required before creating a schema.
   Instructions for creating external sources is available in Creating an external source.
2. Create a schema
   Define the structure and fields of your data using a schema tailored to your needs and optionally define the schema audience.
   Instructions for creating schemas is available in Creating a schema.
3. Fill the schema with data
   Populate the schema with data. Each data submission creates a single record based on that schema.
   Instructions for creating records is available in Creating a record.
4. Generate an object with a record result using Jinjava, REST API, mobile SDK
   Instructions for generating an object is available in Generating objects.

Schema types

While creating a schema, you can select a schema type.

• Simple schema - A lightweight schema without versioning. Records created on the basis of this schema can only get published state. This schema type can be used with asynchronous APIs.
• Versioned schema - This schema type lets you add records that are versioned. You can retrieve versioned records through the API or preview them on the interface.

Versioned schema

• When a schema is first created, the API response includes the version parameter set to 1.
• Each time you modify and save the schema, the API response includes a schemaVersion parameter that indicates the current schema version.
• In the Synerise platform interface, the latest schema version is always displayed.
• It is not possible to retrieve schemas by their version through the API and preview schema versions on the interface of the Synerise platform.

Schema and record audience

In the settings of the schema, you can define its recipients. Records created based on the schema inherit audience settings from that schema and the object generated with record results will be only visible to the profiles who meet the audience conditions.

Here are a few reasons why you would want to define an audience for a schema:

• personalization - it allows for more personalized content, recommendations, or offers by applying the schema only to relevant users.
• data organization - helps organize and segment data efficiently by associating it with specific user groups or segments.
• targeted analytics - enables more precise analysis and reporting focused on defined audiences, improving insights and decision-making.
• access control - facilitates managing access rights, ensuring that only the relevant users or teams interact with certain data schemas.
• performance optimization - reduces unnecessary data processing by limiting schema usage to specific audiences, improving system performance.
• compliance - helps ensure compliance with data privacy regulations by limiting data usage to appropriate user groups.

Record lifecycle

For detailed information on record versions for the versioned schemas, record states, record publishing workflows, see Record lifecycle

Record usage guidelines

• Audience inheritance
  Records inherit audience settings from their schema. If you attempt to generate an object based on a record for a profile that does not belong to the intended audience, an error will occur.

• Populate a record with values expected in the fields
  Fill each field with a value matching its data type—use strings for string fields, booleans (true or false) for boolean fields, and avoid using Jinja templating in fields that require static values. You can learn more about fields in Field types

• Using Jinjava field type

  • Full Jinja templating is allowed only in Jinjava code field type,
  • When using the Jinjava field type, consider inserting attributes conditionally. This approach helps handle cases where the requested attribute might be missing from the profile’s data. You can learn more about this in Inserting attributes conditionally.

• Brickworks inserts are allowed in:

  • the Primary key field in the settings of catalog field,
  • the Item context field in the settings of AI recommendation field,
  • in Jinjava code field type.

• Generating objects with record results
  To use the record result in your desired distribution channel, you can invoke it through the Jinjava and API/SDK methods. For more information, see Generating objects

• Changes to schema don’t impact on the published and drafts records
  Editing a schema does not automatically update or modify existing records. In the record editor, you will see changes reflected (for example, new fields will appear), but you must manually fill in any new fields and save the record for the changes to take effect.

Contents

Below you can find instructions how to create a schema and a record on the user’s interface in the Synerise platform. To see how to create schemas and records through API, see Generating objects.