Using the Metadata manager

This article describes the Metadata manager prior to the changes made on November 5, 2024.
The Metadata manager with the changes made after November 5, 2024 is described in this article.

The Metadata manager allows you to add, remove, customize, or re-order the fields for most of the modules and functionalities in Backstage.

For example, the User module by default contains the First name, Last name, Company, Position, Email, Phone number, etc. fields. These are all metadata that can be managed via the Metadata manager, to better serve your workspace.

This can allow you to capture additional data in your workspace by adding or editing fields to modules, and to configure targeting for your workspace content in order to decide what your app users can see or access in the app.

This tool can make significant changes to the way data is structured in your workspace and in the app, so please only use this if you are confident about what you are doing.

Using the metadata manager

To access the Metadata manager in Backstage, from a workspace, go to Settings > Metadata.

Selecting a module

The first thing you need to do in the Metadata manager is to select the module or functionality for which you would like to manage the metadata.

Click on the dropdown list at the top of the screen, and type in the name of the module or functionality you are looking for to find it.

In this article, to explain how the Metadata manager works, we will select the Users. Below we will explain how each section of the metadata manager works, and the fields they contain.

Representation - or configuring the information contained in item headers in the app

The Representation section is used to determine in what order the items created in the selected module in Backstage will be displayed in the app.

Here, in the User's module, it determines how user information will be displayed in the user profile header in the app.

Take a look at the below configuration in the Representation section, for the User module.

Here we have selected what fields will appear in the first, second, and third lines in the profile header in the app, using the user's first name, last name, email address, position, and company metadata.

The above configuration will result in the user profile information looking like this in the app (look at the order of the information):

The metadata used here, between {{...}} brackets (fname, lname, etc.), is taken from the Fields section of the Metadata manager, explained below.

Configuring the fields in the module

After selecting your module, in the Fields section you will see all the fields (or metadata) that will be displayed and available for use in that module within your module interface in Backstage, for any item created there.

Below are the fields available in the Users module, as seen in the metadata manager.

This is how the above fields look in the User's module interface in Backstage:

The columns and fields displayed above are further explained below:

Field name
This is the unique identifier for the metadata. It can only be in lower case and no special characters,  spaces, or dots "." can be used. Instead of using spaces here you can use an underscore, e.g. "flight_departure".

This is also the text that needs to be placed in curly brackets {{___}} to be used in the Representation section, as shown above.

Here, by clicking on the Choose a new category or Add a category buttons, you can also select an existing category or create a new category for each metadata or field. The metadata will be added to that category when displayed in the module Backstage. More information on this is available below in the Adding metadata section.

Backstage label & tooltip
The label field will be the name of the field as seen in Backstage and the app (when applicable). The tooltip can be used to add additional information for that field and will only be visible in Backstage.

Field kind

Here you can select what type of metadata (or input data) the user will be using in the field.
There are many types for you to choose from in the dropdown list, that allow you to customize the fields in the module.

The different field kinds are explained below:

• Default
  Only regular text or numbers can be entered in this field. This can be used for: address, company, position or other fields that can be created and used for targeting purposes such as “Team” or “Group” for example.
• Text
  Similar to the default type, text and numbers can be used.
• Password
  Allows a password to be entered that is hidden from view, and displayed as  "•••••••••••••"
• Text multiline
  Allows a larger body of text to be entered in a field, and to use line breaks (using the Enter key) that will be visible only when seeing the field in Backstage. This field type should not be used for displaying content to app users.
• HTML
  Enables HMTL language to be used within the metadata field. With HTML you can easily format your fields with paragraphs of text for example.
• Number
  Only numbers can be entered in this type of field.
• Boolean
  This adds a checkbox to be used for the field.
• Choice
  This is used to create predefined selectable options to choose from for the field. Enter an option and then click on the + button to the right of the bock. The choices will be displayed and the user can user radio buttons to select their choice.
• Choice list
  This works the same as the Choice type, however the user will select their choice in a dropdown list.
  Note: You can edit the contents of the drop downs for the "Choice" and "Choice list" field types. Just click on the "pencil" button, and the drop down list content will become editable like a text box. This allows you to easily modify the order of items, and even copy and paste the full content from one field to another. Do not forget to click on the check mark to save the changes done when editing a checklist.
  
• List
  Can add multiple value fields with predefined kind.
• Timestamp
  This is used to add values to the field in date/time format.
• Color 
  This allows a hex color code to be added as a value to the field.
• Auto
  This is usually for data generated automatically by the system. Automatically generated data should not be changed by the user, and if a metadata has been populated using “Auto” then the value will not be modified when performing an import.
• External
  Allows content from the app to be linked to the field, such as banners, sessions, feeds, etc.
• Hidden
  Hides the metadata from both Backstage and the app but it remains visible in the metadata manager if the user wants to restore it later on.
• Email 
  Allows you to only enter a valid email address as a value. This field will require that the added data contains a "@", and will also by default be mandatory.
• Formatted-datetime
  Used only in registration pages, to add a date and time picker.

When a field’s "kind" or type is changed, the corresponding data in the workspace (users, speakers, sessions, etc.) will need to be exported and then reimported in order to save this field’s values with the new (modified) field kind.

Input is required
If this checkbox is ticked then the metadata field has to have a value added.

Fill when empty
This is used internally for engineering purposes, please disregard this.

Default value
You can set a specific default value that populates the metadata field when no data is added.

Private
This checkbox indicates if the field should be private, and therefore not visible to other app users unless certain requirements are met. for example, an email address in a User profile is not visible until the user has shared their business card via the app.

When a field’s privacy is changed from private to public or the other way around, the users list will need to be exported and then reimported in order for the new metadata to be correctly saved as private/public after the change.

Adding new metadata fields and categories

To create a new metadata for the selected module, simply click on the Add a new field button at the bottom of the screen:

 

Here you can add a Field name, Backstage label, etc. based on the indications provided above.

You can also create categories to add metadata too. Categories will create separate sections in the user interface layout, and when a metadata is associated with a category it will appear in that section of the layout.

Use the Add a category button to create a new category, and then use the Choose a new category dropdown list to assign a metadata to an existing category.

Moving metadata fields

The order of the metadata fields when displayed in the selected module can be modified using the ▲ or ▼ arrows. For example, moving a metadata field to the top of the list here will make the field display at the top of the user interface in Backstage.

Deleting metadata

You can delete metadata by clicking on the bin icon to the right of the metadata listed in the Fields section.