Standard Klasses

Learn how to define an app to add custom properties, or custom attributes, to standard Klasses. This page includes descriptions and examples for defining custom attributes on standard Klasses in a Kustomer app.

The Kustomer platform features a set of standard Klasses with standard attributes.

Standard Klasses define the schemas for the following standard data objects in Kustomer:

• Company object
• Conversation object
• Customer object
• Message object
• User object

Organizations can create their own custom properties, known as custom attributes in Kustomer, for standard Klasses and custom Klasses.

Apps can also define custom attributes to add to the standard Klasses available for an organization on installation. You can create apps to add custom attributes to the standard Company, Conversation, Customer, Message, and User klasses.

Standard Klasses format in the app definition

To define a custom property for a standard Klass, add a "standard": true flag to the metadata field for the standard Klass in the klasses object definition in addition to the custom attribute properties in the metadata.properties field.

If the "standard": true flag is missing in the attributes metadata field, the app definition will configure a custom object, or KObject, of the same name instead.

After an app configures a custom attribute for a Kustomer organization, anyone with Administrator permissions can access and modify the attribute activation and attribute display names in Kustomer.

Custom attributes for standard Klasses example

The following sample JSON app definition includes a klasses property definition that creates custom attributes for the standard Company klass ("name": "company") and the standard Customer klass ("name": "customer"). The app definition would add the following three standard Klass properties, or custom attributes for standard Klasses:

• Sector custom attribute to the standard Company klass
• Instagram Username custom attribute to the standard Customer klass
• Influencer custom attribute to the standard Customer klass

Sample app definition with defined custom attributes for standard Klasses

{
	"app": "ecomm",
	"version": "0.0.1",
	"title": "E-comm",
  "klasses": [{
    "name": "company",
    "metadata": {
      "standard": true,
      "properties": {
        "sectorStr": {
          "displayName": "Sector",
          "example": "Information Technology"
        }
      }
    }
  }, {
  	"name": "customer",
    "metadata": {
      "standard": true,
      "properties": {
        "instagramUsernameStr": {
          "displayName": "Instagram Username",
          "example": "@johndoe"
        },
        "influencerBool": {
          "displayName": "Influencer",
          "example": "true"
        }
      }
    }
  }]
}

Property descriptions

Property descriptions of custom standard Klass attributes

The basic definition properties and their descriptions for custom standard Klass attributes are listed below:

name

Required. The system name for the standard Klass.

Validation: Must be one of the following standard Klass options: company, customer, conversation, message or user.

Example: "name: company" for a custom attribute on the standard Company klass

metadata.standard

Required. Defines a custom property or attribute for a standard Klass.

Validation: Must be set to true.

Example: "standard": true.

Note: If this flag is missing in the attributes metadata field, the app definition will configure a custom object, or KObject, of the same name instead.

metadata.properties

Defines the various custom attributes and attribute properties of the custom Klass including attribute name, attribute data type, and attribute display name. Use camelCase.

The final characters of each property name describes the data type of the attribute. Each property takes a displayName property that defines how the attribute name appears in the platform. Both attribute property names and the displayName property appear in the platform, but only the display name can be modified by the user in the platform.

📘

Namespacing for custom attributes on standard Klasses

When you register an app that configures custom attributes on standard Klasses, the apps platform automatically namespaces attribute names with a unique app identifier to help avoid name collisions and duplicate attribute names. To learn more see Namespacing.

• Num for numbers
  • Example: "orderIdNum": {"displayName": "Order Id"}
• Str for short strings
  • Example: "orderStatusStr": {"displayName": "Order Status"}
• At for dates
  • Example: "orderCreatedAt": {"displayName": "Order Created"}
• Txt for longer text
  • Example: "orderDescriptionTxt": {"displayName": "Description"}
• Bool for booleans
  • Example: "isCanceledBool": {"displayName": "Is Canceled"}
• Url for urls
  • Example: "permalinkUrl": {"displayName": "Permalink"}

For additional attribute data types, see Define Attributes in Kustomer in the Kustomer Help Center.

Namespacing

Namespacing for custom attributes on standard Klasses

To avoid name collisions for custom attributes, the Kustomer apps platform automatically namespaces custom attribute names for app definitions. This prevents multiple apps from configuring custom attributes of the same name on standard Klasses.

Namespaced custom attributes names for standard Klasses are appended with an @ symbol followed by a 2-8 character length custom app identifier you can include in your app definition. If you do not include a custom app identifier in your app definition, the Kustomer apps platform generates one for you.

Example of namespaced custom attribute name

Let's say you have a definition for an app called "Survey Lemur" that configures a custom attribute with the property name instagramUsernameStr on the standard User klass. If you do not specify a custom app identifier in your app definition, then Kustomer apps platform would auto-generate the following namespaced version for the attribute name: @survlemuInstagramUsernameStr.

Note: All app-configured custom attributes are prefixed with an @ symbol to distinguish them from standard attributes for standard Klasses.

App Identifier

You can provide a unique custom app identifier in the app definition under the top-level identifier property. The apps platform uses your app identifier to automatically namespace app-configured custom properties for standard Klasses.

If the app definition does not specify an app identifier, a unique identifier is auto-generated during app registration.

Validation: The app identifier must be a string between 2 and 8 characters long and should be a meaningful abbreviation of the app name.

Note: Once you register the app definition to the apps platform, you will need to use the same app identifier when you update the app version.

Custom attributes registry

View a registry of app-configurable custom attributes for standard Klasses

To ensure the uniqueness of your custom attribute name, you can check the registry of existing custom attributes for standard Klasses on the platform before you register your app definition. The registry allows you to view a list of all custom attributes for standard Klasses that are configurable through an app available on the Kustomer apps platform.

To view a registry of all custom attribute names, you can:

• Make a GET request to /v1/apps/metadata to view all available custom attribute names for standard Klasses
• Make a GET request to /v1/apps/metadata/{klass} to view available custom attribute names for a specific standard Klass: customer, company, conversation, user, and message.

Example Response Body for GET /v1/apps/metadata)
In the example JSON body below we can see the available app-configurable custom attributes for two standard Klasses: company and customer.

For each standard Klass, we can see the metadata properties for each app-configurable custom attributes listed as objects in appInstalledProperties.

These custom attributes are made available through the installation of two apps, "Survey Lemur" and "Form Platypus." We can see the unique app identifier prefixed with the @ symbol for these two apps appended to the custom attribute names: @survlemu and @formplat.

There are three custom attributes listed for the standard company class:

• @survlemuFortune500Bool
• @survlemuSectorStr
• @formplatSectorStr

There are two custom attributes listed for the standard customer klass:

• @formplatInfluencerBool
• @formplatInstagramUsernameStr

You'll notice that while both the Survey Lemur and Form Platypus apps configure custom attributes named SectorStr for the standard company klass, the automatic namespacing helps to prevent a name conflict.

In addition to the full namespaced name of the custom attribute, we can see the following properties: the display name, an example value for the attribute, and a list of the app versions that use the custom attribute configured by the app.

Example JSON response body for `GET /v1/apps/metadata)`

[
    {
        "klass": "company",
        "appInstalledProperties": {
            "@survlemuFortune500Bool": {
                "displayName": "Fortune 500",
                "example": "true",
                "usedBy": {
                    "surveylemur": "0.0.2"
                }
            },
            "@survlemuSectorStr": {
                "displayName": "Sector",
                "example": "Information Technology",
                "usedBy": {
                    "surveylemur": "0.0.2, 0.0.3"
                }
            },
            "@formplatSectorStr": {
                "displayName": "Sector",
                "example": "Information Technology",
                "usedBy": {
                    "formplaytpus": "1.0.0, 1.0.1"
                }
            }
        }
    },
    {
        "klass": "customer",
        "appInstalledProperties": {
            "@formplatInfluencerBool": {
                "displayName": "Influencer",
                "example": "true",
                "usedBy": {
                    "formplatypus": "1.0.1"
                }
            },
            "@formplatInstagramUsernameStr": {
                "displayName": "Instagram Username",
                "example": "@johndoe",
                "usedBy": {
                    "formplatypus": "1.0.0, 1.0.1"
                }
            }
        }
    }
]