Data Source Objects

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.

Adding dependent tables

If you attempt to import an object that has dependencies on other objects—i.e. other SQL tables—then you may receive an error. This is because Skuid cannot parse the relationships of the object properly, and thus cannot form proper data source object metadata.

Should this happen the Add Dependent Tables and Retry button will appear at the top of the import page. Clicking this will cause Skuid to recursively retrieve all objects the selected object depends on, which will then allow for normal import of the selected object.

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 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 permission sets 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 name: A human-friendly name for the condition, typically a short description of the condition’s purpose.

  • Field: The field whose value will be analyzed for this condition.

  • Value source:

    • Single specified value: The field value must exactly match a particular value, which is set in the Value field.
    • Skuid user attribute: The field value must exactly match a Skuid user’s attribute. This is a dynamic value, updating based on which Skuid user is accessing the page.
    • Session variable: The field value must exactly match the value of a session variable—which connects to a SAML attribute from an identity provider.
    • None - blank value: The field value must be empty.
  • Value: The value used to limit incoming data. The options available here rely on the Value source.

  • Enforce on: Determines when the condition is enforced, with the following options available:

    • Query: Whenever this data source is queried, it will only display data that matches the rules of this condition. Useful for filtering records.
    • 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
    • Update: Whenever an end 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.
    • Delete: Whenever an end user attempts to delete an existing record, the condition will be enforced. These conditions are useful for records that can only be deleted in certain conditions, preventing accidental data loss.

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 end users do not already have access to. Fields, conditions, or the entirety of DSO can be configured per site permission set. 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, an end 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 site permission sets—besides Admin—start with zero permissions, and you’ll need to grant permissions from the bottom up.

Warning

Any end user assigned a site permission set 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 site permission set.

Troubleshooting

DSO Import [[]]

Errors while importing DSOs can be caused by several things:

  • Verify that Skuid’s IPs are allowlisted 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.

Permission Set 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.