Custom Fields Configuration Document

CompoundJson

All of our flexible fields that allow custom fields, eg. client_custom_attributes and inspection_client_custom_attributes have the typed attribute type of CompoundJson

The CompoundJson typed attribute acts as a container for sub attribute types defined a compoundElementTypeSpecs.

Under the hood, the database is only aware of the CompoundJson field(eg. client_custom_attributes) and store the sub attribute types as JSON in the db.

Example Setting up a custom freetext field called example_custom_freetext

compoundElementTypeSpecs: [
    {
        name: "example_custom_freetext",
        display: "Example Custom Freetext",
        baseClassName: "FreeText"
    },

The database value would be a JSON object representing the value of the sub attribute types, and any others you might add to compoundElementTypeSpecs

Eg.

{ "example_custom_freetext":"Custom Freetext Value","example_custom_enumeration":"Custom Enumeration Value"}

[Option] Adding a custom field at a asset type level

Example Adding custom fields for the region asset type

IMPORTANT

This will affect all clients using that asset type.

Click to expand code example

packages/@kt-asset/asset-type-definitions/src/definitions/region/assetAttributeTypeDefinitions.ts

/*
* Overrides of the top-level asset attribute type
*/
const overrideAssetAttributeTypeDefinitions = [
    {
        name: "client_custom_attrs",
        display: "Client Custom Attributes",
        baseClassName: "CompoundJSON",
        compoundElementTypeSpecs: [
            {
                name: "example_custom_freetext",
                display: "Example Custom Freetext",
                baseClassName: "FreeText"
            },
            {
                name: "example_custom_enumeration",
                display: "Example Custom Enumeration",
                baseClassName: "Enumerated",
                valuesForEnumeration: [
                    {
                        name: "no",
                        display: "No"
                    },
                    {
                        name: "yes",
                        display: "Yes"
                    }
                ]
            }
        ]
    }
] as const satisfies AssetLevelAttributeOverride[];

[Option] Adding a custom field for a client only

Here you can make use of the attributesPatch in the wsConfig for the install you want to setup with a new custom field for an asset.

Config code example using `attributesPatch`

IMPORTANT

attributesPatch configuration is changing soon to be able set a patch at the assetBase level, for now you will need to apply the same patch to each asset type you want to add the custom field to. Note you can store the shared compoundElementSpecs in an variable and reuse for each asset type.

Example config packages/@kt-config/workspaces/ws/N/N-config.ts

export const wsConfig = {
	assetTypeConfig: {
		channel: {
			attributesPatch: {
				client_custom_attrs: {
					compoundElementTypeSpecs: [
						{
							name: "example_custom_enumeration",
							display: "Example Custom Enumeration",
							baseClassName: "Enumerated",
							valuesForEnumeration: [
								{
									name: "no",
									display: "No"
								},
								{
									name: "yes",
									display: "Yes"
								}
							]
						}
					]
				}
}

[Finally] Making custom field container visible

For example custom_client_attrs and inspection_client_attrs, by default as most clients don't need custom attributes, we have them marked as ignorable: true on the assetBase by default. They are also not included in the Structured Drawers definition.

1. Add custom field container to the drawer definition for the asset types you've added custom fields to.

packages/@kt-asset/asset-type-definitions/src/definitions/site/assetStructuredDrawersDefinitions.ts

const assetTypeDrawer: DrawerDefinition<"asset", SiteAttributes> = {
    drawerName: "AssetType",
    attributesInOrder: [
        "type",
        "client_custom_attrs", // << adding `client_custom_attrs` to the asset drawer for site
        ...getAttributesInOrderFromAttributeTypeDefinitions(orderedAssetTypeAttributeTypeDefinitions)
    ]
};

1. Use overrideEnumeration to set ignorable to false for the custom field containing field in the workspace entry point file.

NOTE

When the attributesPatch work is completed, you will be able to override the ignorable flag in the config patch. Use overrideEnumeration for now.

    Drains.Configuration.overrideEnumeration(
        "client_custom_attrs",
        null,
        ["Site"],
        {
            ignorable: false
        }
    );