Use custom properties

The process of adding custom properties to an existing entity is covered in Create a custom property in the application dictionary.. This article focuses on technical details for some use cases.

• Any Spire customizations should live in the blueprints directory underneath your particular blueprint.
• Any relevant guidelines for adding custom handlers/pipes apply to this process.
• No overrides should be needed to Mappers or Entities to set up custom properties.

Any entity in Spire that extends BaseModel (found in ApiModels.ts) or any object in the API that extends the BaseModel class (found in BaseModel.cs) can be extended with the Properties object. The Properties object is a dictionary comprised of string key:value pairs and is intended to act as easily customizable properties so the application can be extended to fit a variety of business needs. The entities available for extension this way can also be found in the Admin Console on the Application Dictionary page.

The Properties dictionary can be used in a variety of ways (detailed below) and is set up so that no code changes to existing models or mappers are needed. If you look at any of the existing mapper classes in the API, you will not find any reference to these properties. This is because they are copied over in our base handler class after the mapping occurs. You must ensure the custom properties are handled accordingly in any Spire component or handler chain, but do not need to worry about mapping them yourself.

You have two main options for setting the value on your custom properties. The first option to find the relevant entity in the Admin Console (a specific order, product, category, etc.) and set the value on the Custom tab:

The second option is to add custom code to set these custom property values. This can make more sense if you need to apply some specific or niche business logic.

Handle custom properties in the API

In the API, you must insert a custom handler/pipe to apply business logic to custom properties. These new handlers and/or pipes must follow all other rules and logic around custom code. You grab the relevant value by accessing the Properties dictionary with the key you assigned to the property. If it is a complex object, you may need to de-serialize the value.

If you want to set a value for a custom property, you can do so using the standard Dictionary.Add() method if the value is a string:
result.Properties.Add(“Key”, “Value”);

Or by serializing the object to be added as a value:
result.Properties.Add(“Key”, JsonConvert.SerializeObject(complexValueObject));

In both examples above, you must set the value of these custom properties before the entity is saved to the database for the value to persist.

Handle custom properties in Spire

In general, you should expect the custom properties to behave like any other value on a given entity. This means you will not need to do anything special to access these values as long as they are saved correctly on the entity and are stored in Redux. From there, you can access them in any component or widget that you have overridden.

Be aware that if you serialized the value in the API (as shown above) you must parse the relevant JSON:
var customProperty = JSON.parse(data.properties["string to be used as key"]);

You can also set these properties on POST and PATCH requests within Spire before the request goes out to the API. This ensures that the relevant values are saved to the database and can serve as a useful point to insert your custom business logic. In this case, it would make sense to insert a handler to the relevant Spire handler chain. You would set the values for your custom properties like this:

data.properties = <any>{};
data.properties["extradata"] = "test";
data.properties["extradata2"] = "test2";

The properties object is still a dictionary of string keys and string values, so if your value is a complex object you may need to serialize it here.

Pass arbitrary data back from the APIs

Another use case for the Properties dictionary can be to return extra arbitrary data on API Response objects. This may be useful if you need to propagate a specific data point back to Spire.

📘

Note

Arbitrary properties that have not been configured in the Application Dictionary will not be saved to the database and will be rejected if they are found in the body of a Request object.

Custom properties can be useful for extending existing entities and can ensure that the application fits your use case as long as the following are applied:

• Custom properties should be created via the Admin Console, and from there can either be populated manually via the Admin Console or programmatically.
• If you are manipulating the custom properties via code, ensure that you are setting the value before the entity is saved to the database.
• You can set the value either in the API code or in Spire—whichever makes more sense for your business needs.
• You may also return arbitrary data in the Property field of a Response object, but these values must be handled via custom code and are not saved to the database.