Data Source Objects

Note

This feature is currently exclusive to Skuid Platform.

Data source objects (DSOs) are Skuid’s way of translating the various tables and columns—or objects and fields—of a database into the declarative objects that Skuid models can work with. As different databases / data services may not always provide easily digestible metadata, Skuid instead relies on this set list of data source objects, which correlate to an object or table in a database. Additionally, data source objects can be configured with an array of conditions and security options on top of any security configurations in place on the database side.

Note

Though you can regularly import data source objects, Skuid cannot automatically keep track of changes to the database.

If a database’s schema and structure change often, you’ll need to update the DSOs within its data source to match whenever you make those changes. Consider waiting until the database reaches a more permanent state before setting up DSOs.

DSO Properties

There are several DSO properties you may update from the DSO table or the DSO detail page:

  • Name: The name of the object, which must correlate with the object’s name in the database.
  • Label: Typically a human-friendly identifier for an object, used in Skuid pages whenever the object’s label would display within a component.
  • Label Plural: The plural form of the above label, used whenever the object is referenced in a context that makes it plural, e.g. when working with multiple records or navigating pages of records within a component.

Creating and Configuring Data Source Objects

Creating DSOs is the first step in using a SQL data source, and importing DSOs is the recommended approach.

Note

The Skuid admin who imports data source objects must have permission within the database to list its schema. If you are unsure if this applies to you, or if you are seeing issues, contact your database administrator.

  1. Click fa-magic Import Data Source Objects.

    A popup containing a list of the tables—or objects—within the database will appear, organized by name and schema.

  2. For each object you wish to use within Skuid, click fa-sign-in Import Object.

You can also manually create DSOs:

  1. Click the down arrow beside Import Data Source Objects.
  2. Click fa-plus-circle Manually Create Data Source Object.
  3. In the newly created row on the DSO table, enter the Name and Schema of the object you wish to use within Skuid.

Warning

Creating a new data source object in Skuid will not create a corresponding table or object in your database. Only create objects that already exist in your database.

DSO Details

After creating DSOs, you’ll need to configure them before using them within a Skuid page. To do so, click fa-cogs Details beside the DSO you wish to configure. Within the DSO details page, you’ll find several tabs where you can finetune the details of that object.

Fields

Fields represent the columns of the object within your database. The fields of an object will be imported within the object itself, or you can also create fields manually by clicking fa-plus-circle Create Data Source Field. Much like with objects themselves however, importing fields is recommended over manual creation.

Warning

Creating a new field on a DSO in Skuid will not create a corresponding field on the table or object in your database. Only create fields that already exist within tables or objects in your database.

Each field’s Name and Display Type must match the field’s configuration within the database, but there are several other properties you can configure:

  • Label: The label that will display whenever the field is shown within a Skuid page. While the Name field is often bound by the character and syntax rules of the database, the Label property allows you for more human-friendly display names.

  • Required: When enabled, a field must have some value before Skuid will allow a record on the object to be saved.

  • Readonly: When enabled, a field—regardless of database permissions—will not be editable within Skuid

  • Id Field: Specifies that this field stores specially-generated identification values for each new record on the object. These read-only fields help identify each newly-created record as unique; they are also commonly used to connect an object with other objects.

  • Name Field: Specifies that this field contains human-readable values correlating to the ID field. Name Fields are substituted anywhere the object is referenced by its ID field, most commonly seen in reference fields on other objects.

    For example, an opportunity has a contact connected to it, and that contact has an ID field with the value of 000-AAA-BBB. The ID field’s correlating Name field has the value of “Contact A;” this Name field value is displayed wherever the opportunity references that contact record—allowing end users to easily parse object-to-object relationships.

Note

For many objects in most databases, it is common to have one ID field and one name field, and it is best practice to ensure these are marked within your data source object. In some rare cases you may have more than one of these types of fields. If you are unsure, work with your database administrator to verify these fields and how they should be configured within Skuid.

For additional field options, click fa-cogs Details beside a field:

  • Filterable: Designates that this field may be filtered by options within Skuid components.
  • Groupable: Designates that this field may be used as a grouping within aggregate models.
  • Sortable: Designates that this field may be used for sorting within a Skuid page.

Note

If you add additional fields to a data source object after using it in a Skuid page, you may need to click fa-refresh Refresh Fields on any models connected to that object to make those fields available.

Conditions

Data source conditions are used to either limit incoming data anytime a data source is queried or enforce field values in particular situations. While you can create a condition, it isn’t actually enforced until you select one or more of the enforcement options below.

Note

Conditions can be used in conjunction with Access Control permissions to enforce different rules for different profiles on the same data source object. Since these rules supersede any page-level conditions, you can provide different user experiences across pages with minimal effort through clever data source object configurations.

Condition Logic: By default, all conditions are applied. Condition logic determines how to group and apply conditions when loading the Model, e.g., ((1 AND 2) OR (3 AND 4)).

  • Name: A human-friendly name for the condition, typically a short description of the condition’s purpose.
  • Type:
    • Single specified value: The field must exactly match the value in the Value field.
    • Skuid user attribute: The field must exactly match a Skuid user’s attribute. This is a dynamic value, updating based on which Skuid user is accessing the page.
    • None - blank value: The field must be empty.
  • Field: The field whose value will be analyzed for this condition.
  • Value: The value used to limit incoming data.
  • Enforce on Query: Whenever this data source is queried, it will only display data that matches the rules of this condition. Useful for filtering records.
  • Enforce on Insert: Whenever a new record is created, the field for that record will match the value of the condition. Particularly useful for Created By <User> fields
  • Enforce on Update: Whenever a user modifies an existing record, the condition will be enforced. Meaning that, whether the user changes or removes a field’s value, Skuid will disregard whatever the user entered and will instead match the condition’s value.

Access Control

Access control provides an extra degree of security beyond any database-level permissions. This security is additive; it only sits atop any measures you have already set and cannot grant permissions your users do not already have access to. Fields, conditions, or the entirety of DSO can be configured per profile. Permissions for objects and fields are assigned based on the following operations:

  • Create: The creation of a new record within the object.
  • Read: The querying and receiving of record data.
  • Update: The modification of an existing record.
  • Delete: The deletion of an existing record

While there is commonly overlap between each of these operations, they are exclusive from one another. For example, a user with the Create and Update operation permissions could technically do those things, but they couldn’t do anything at runtime without the Read permission because they wouldn’t see any data in the first place. Consider the actual operations your users should be privy to, but also how those operations need to interact with other operations.

And by the same token, granting access to an object does not immediately grant access to all of its fields. These permissions are additive, meaning that all profiles—besides Admin—start with zero permissions, and you’ll need to grant permissions from the bottom up.

Warning

Any user assigned a profile with the Configure Site permission will have full access to all data sources and DSOs by default—though runtime data may still be filtered based on any data source conditions enforced on the Admin profile.

Troubleshooting

DSO Import

Errors while importing DSOs can be caused by several things:

  • Verify that Skuid’s IPs are whitelisted on the database host.
  • Test that you can properly connect to the database by clicking fa-plug Test Connection on the data source.
  • Try enabling Use SSL to Connect in the data source’s properties.
  • Work with your database administrator to verify that you have permission to list database schema.
  • Ensure that your database has tables/objects to import.
  • Check that you are connecting to the correct database.

Profile Permissions

  • To update permissions on data source objects within a data source that utilizes them, click fa-cogs Object Permissions. You may further finetune permissions by clicking fa-cogs Field and Condition Permissions.