Introduction to Custom Fields

The Community Plugin, along with Feature plugins, lets you create custom fields for specific GraphQL types that use the CustomFieldsEntity Khoros GraphQL interface. It's set up so your custom fields won't clash with any new core fields or other custom fields added in the future.

Once you've properly set up these custom fields, you can use them on various Entities (those that use the CustomFieldsEntity Khoros GraphQL interface) in your community. You can do this through the Aurora UI or the GraphQL API.

Currently, you can add custom fields to several types of Entities, including Message types, Core Node types, and the User type. If you're working with the Salesforce connector, you'll also be able to add custom fields to the Case type.

To define custom fields and decide which entities they should be added to, you can work within your community plugin repository. You can either directly commit and push changes from a developer's machine to the Git Repo or use a GraphQL mutation to create or update them.

Custom Field and Custom Field Container configuration files

Defining a custom field, and making it available to be set on an Entity in the community, requires updating at least 2 files:

File	Description
Custom Field Descriptor File	These are located in the res/entities/fields directory and have file names that end with .field.json.
Custom Field Entity Descriptor File	Also known as an Entity Descriptor, these are located in the res/entities directory and have file names that end with .entity.json.

Custom Field Descriptor Files

Custom Field Descriptor files all have file names that end in .field.json and are added to the res/entities/fields directory:

The file name should start with the name of the custom field and then end with .field.json. For example, you might add a custom field named streamingService:

streamingService.field.json	This is the file you would define a custom field named streamingService in.

Best practices around field naming

We recommend the part of the file name before the .field.json match the value of the "id" property in the Custom Field Descriptor File. Also, the field name should always start with a lowercase letter.

The "id" field in the Custom Field Descriptor file will be used as the actual name of the field, but if it starts with an upper-case letter, that will be lower-cased, so to avoid any confusion always start your field ids with a lowercase letter and first part of the file name match the "id".

Custom Field Entity Descriptor Files

Custom Field Entity Descriptor files all have file names that end in .entity.json and are added in the res/entities directory.
These are the Descriptor files we currently support:

Descriptor File	Description
user.entity.json	Adding valid custom field names in this file will allow them to be added to an entity of the User type.
community.entity.json	Adding valid custom field names in this file will allow them to be added to an entity of the Community type.
category.entity.json	Adding valid custom field names in this file will allow them to be added to an entity of the Category type.
group_hub.entity.json	Adding valid custom field names in this file will allow them to be added to an entity of the GroupHub type.
forum.entity.json	Adding valid custom field names in this file will allow them to be added to an entity of the Forum type.
blog.entity.json	Adding valid custom field names in this file will allow them to be added to an entity of the Blog type.
tkb.entity.json	Adding valid custom field names in this file will allow them to be added to an entity of the Tkb type.
idea.entity.json	Adding valid custom field names in this file will allow them to be added to an entity of the Idea type.
event.entity.json	Adding valid custom field names in this file will allow them to be added to an entity of the Event type.
forum_topic.entity.json	Adding valid custom field names in this file will allow them to be added to an entity of the ForumTopicMessage type.
forum_reply.entity.json	Adding valid custom field names in this file will allow them to be added to an entity of the ForumReplyMessage type.
blog_article.entity.json	Adding valid custom field names in this file will allow them to be added to an entity of the BlogTopicMessage type.
blog_reply.entity.json	Adding valid custom field names in this file will allow them to be added to an entity of the BlogReplyMessage type.
tkb_article.entity.json	Adding valid custom field names in this file will allow them to be added to an entity of the TkbTopicMessage type.
tkb_reply.entity.json	Adding valid custom field names in this file will allow them to be added to an entity of the TkbReplyMessage type.
idea_post.entity.json	Adding valid custom field names in this file will allow them to be added to an entity of the IdeaTopicMessage type.
idea_reply.entity.json	Adding valid custom field names in this file will allow them to be added to an entity of the IdeaReplyMessage type.
event_topic.entity.json	Adding valid custom field names in this file will allow them to be added to an entity of the OccasionTopicMessage type.
event_reply.entity.json	Adding valid custom field names in this file will allow them to be added to an entity of the OccasionReplyMessage type.
salesforce_case.entity.json	Adding valid custom field names in this file will allow them to be added to an entity of the Case type.

Custom Metadata Text Keys

Custom metadata form labels will appear as "Value of field_name" where field_name is the name of the custom field. These can be updated via text keys, as noted below.

Text keys must be updated via the SDK, and placed in the appropriate text.*.json file. For US English, the file would be res/texts/text.en-us.json

Replace all instances of field_name with the name of the custom field.

Registration Form

"authentication.block.registrationForm": {
  "RegistrationForm.custom.field_name.label" : "Lorem Ipsum",
}

User Settings

"users.block.personalSettingsTab" : {
  "PersonalSettingForm.custom.field_name.label" : "Lorem Ipsum",
}

Node Settings

"node.block.customSettingsForm" : {
  "CustomSettingsForm.custom.field_name.label": "Lorem Ipsum",
}

Message Metadata

"messages.block.messageEditorForm" : {
  "MessageEditorForm.custom.field_name.label": "Lorem Ipsum",
}