Using the Metadata manager (updated user interface)

This article is updated to reflect the changes to the Metadata manager that will be available automatically starting November 5, 2024. To note, after this date you can still use the previous version of the Metadata manager, simply by selecting the Switch to the old editor button in the top right corner of the screen in Backstage. The article that describes how to use the previous version of the Metadata manager is available here for reference.

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, for the purpose of explaining how the Metadata manager works, we will select the Users module. 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.

Note: This determines how the user information will be displayed in the user profile header. It does not determine what user information will be displayed in a user list.

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 in the Metadata manager are further explained below, from left to right:

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.

Beneath the "Field name", you cab use the dropdown to assign the metadata to an existing category. More information on categories

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:

• 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.
• Boolean
  This adds a checkbox to be used for the field.
• Choice
  This is used to create predefined selectable options that users can choose from for the field using radio buttons.
  Click in the Edit button and add each selectable option to a line in the field.
  
• Choice list
  This works the same as the Choice type, however the user will select their choice in a dropdown list instead of radio buttons.
  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.
• Color 
  This allows a hex color code to be added as a value to the field.
• Content-page
  This is used to select a previously created content page.
• Display only
  This means that the field in Backstage cannot be edited by the Backstage user. It is only displayed.
• 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.
• SpotMe object
  Allows you to select a SpotMe content type as a field.
• Formatted-datetime
  Used only in registration pages, to add a date and time picker.
• 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.
• 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.
• List
  Can add multiple value fields with predefined kind.
• Nested-object
  This used to edit the properties of objects that are nested within pages.
• Number
  Only numbers can be entered in this type of field.
• Password
  Allows a password to be entered that is hidden from view, and displayed as  "•••••••••••••"
• Number
  Only numbers can be entered in this type of field.
• 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.
• Text
  Only text and numbers can be used.
• Timestamp
  This is used to add values to the field in date/time format.
• Video-call
  This is used to add a "Start a video call" button to a page or profile.

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.

Label, tooltip & placeholder
On the top line there is the "Label": this is the name of the field as seen in Backstage and the app (when applicable).
On the second line is the "Tooltip": this can be used to add additional information for that field and will only be visible in Backstage.
On the third line is the "Placeholder": this is text that will be pre-filled in the field to provide an example of the data that the field can hold. Placeholders can be used for all metadata types except Auto / Boolean / Choice / List / Nested objects / Timestamps / Video call. Placeholders, when populated, are currently not visible in the pages in Backstage (this will be remedied in the next release).

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

Preview and default value
You can set a specific default value that populates the metadata field when no data is added. You will also see a preview of how the value looks in the field.

Private checkbox
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 or category for the selected module, simply click on the Add field + or Add category button at the bottom of the screen:

 

When you create a new field, you will need to select a category for the field to belong to, and then enter the details fort the field. Here you can add a Field name, Label, etc. based on the indications provided above.

You can also create categories to add metadata to. When you create a category, you will need to give it a name. 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.

Moving categories and metadata fields

The order of the metadata fields and the categories that they belong to can be modified. 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.

This is done by dragging and dropping the items, by selecting the ≡ icon and then moving the item up or down:

You can also move a field to the top of its category by clicking on the ⋮ button to the right, and selected "Move on top".

Deleting metadata

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