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.
Click
Import Data Source Objects.A popup containing a list of the tables—or objects—within the database will appear, organized by name and schema.
For each object you wish to use within Skuid, click
Import Object.
You can also manually create DSOs:
- Click the down arrow beside Import Data Source Objects.
- Click Manually Create Data Source Object.
- 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
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
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
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
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 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 Object Permissions. You may further finetune permissions by clicking Field and Condition Permissions.