Field Metadata Overrides and Cross-Object References

It’s not uncommon to have data across multiple objects and services all related to one specific thing, whether that thing be an account, a transaction, or something else. Perhaps a company’s invoices are stored in one data source, while its contact data is stored in yet another. Or maybe a company’s design specs need to be linked with their design drafts, which are stored within a separate data object. Whatever the scenario, creating links between these disparate pieces of data can prove useful for a variety of applications.

Enter field metadata overrides: Skuid can create links between different data objects—even across different data sources—by overriding an object field’s metadata.

When Skuid retrieves a field from a data object, it will return the field name and field type as it is stored within the data source. This is part of the field’s metadata—which describes what the data is and how it is used. However, Skuid can also override that metadata to use that field in new ways not dictated within the original metadata.

In this instance, Skuid admins can create a link between a field and a separate data object, allowing runtime users to easily create the data connections:

  1. Users click a field—which has been configured with overridden metadata—to search records of the linked data object using an autocomplete box. Skuid only returns records that match that search.
  2. Users select a record, and Skuid will update the value of that field to contain the selected record’s key (or ID) field.
  3. Skuid then displays a label—set in the Display Text field—to the end user instead of the raw key value stored in the database.
    • While that user-friendly label is displayed, Skuid keeps track of the record’s key value in the background.
    • By keeping track of the record’s key, Skuid can access all the information related to the record set by the user at runtime.

Before You Begin

  • Skuid can only override metadata for fields that exist within the data source.
    • Any text or number field within the data source can be used.
    • UI-only fields created within Skuid will not work, as they do not reside within the data source’s database.
  • Creating a field to store your references within your data source is highly recommended. Using fields in which end users manually enter data may cause unexpected behaviors.
  • Not all Skuid data source types currently support referencing. Compatible data source types include:
    • Salesforce
    • OData
    • REST

Overriding field metadata in the App Composer

First, you’ll need to add a compatible field to your model.

  1. Click an existing model within the Models tab of the App Elements pane, or create a new one.
  2. Click Fields.
  3. Add a text or number field to the model.

After adding this field to the model, you’ll now override its metadata.

  1. Click the field, and set its properties in the properties pane:
    • Override field metadata: Checked.
    • Display Type: Reference
  2. Click the Reference tab in the properties pane.

On this tab, you’ll begin configuring which data object—and which data source—this reference field should be pointing to.

In the Reference Setup area:

  • Data Source Type: Choose a specific Skuid data source type.
  • Data Source: Choose a specific data source configuration for your data source type.
  • Relationship Field Name:  This is the name of the (Ui-Only) field that will be created (if it does not exist already) to store related information about the referenced record.
  • Related Entity: Key Field: This is the name of the primary key / id field on the related entity that will be used as the key to link the data.

After you’ve specified which object to reference, you must specify which fields from that object to list within the reference by clicking Item Labels Route. The next steps vary, depending on whether you are using a Salesforce, OData, or REST data source type.

Additional configurations

Referencing Salesforce objects

  1. Select the SObject Type of the object you wish to reference.
  2. Click Item Labels Route then click the Plus button to specify fields that will be added as related data.
    • Any fields on the related object that are used in search or display templates will need to be added here.

When you add an instance of this field in a table or field editor, you need to specify a Display Template for that field. This tells Skuid which fields from your related object to use as the label.

Referencing OData objects

  1. Select the Entity Type of the object you wish to reference.
  2. Click Item Labels Route then click the Plus button to specify fields that will be added as related data.
    • Any fields on the related object that are used in search or display templates will need to be added here.

When you add an instance of this field in a table or field editor, you need to specify a Display Template for that field. This tells Skuid which fields from your related object to use as the label.

Referencing REST objects

  1. Configure a Search Route.
    • Specify a route to search for related records.
    • The URL must include a {{search}} merge as a placeholder for a string containing the user’s entered search text. (For this to work properly, your REST API must implement searching.)
  2. Configure an Item Labels Route.
    • Specify a route to get the labels for related records in a single batch.

The URL must include an {{ids}} merge as a placeholder for a comma-separated list of keys to load. (This is not needed if the related records are from the same data source as this model, and if your model’s query method returns the related record’s labels as well as Ids.)