Apps

An app is a collection of Skuid pages, data sources, files, and permissions that make Skuid software available to end users.

Apps and their pages are accessed visiting specific URLs within the Skuid site. In addition to providing a single area for resource management, apps are also the primary means of deploying all of an application’s required resources from one Skuid environment to another.

App-centered development and primary concepts

When building applications with Skuid, it’s best practice to adopt an app-centered development mindset, which means to build and work primarily in the context of a single app and its detail screen. The app should be seen as the primary means of organizing all the resources needed for a collection of Skuid pages to operate.

It’s important to keep this app-resource relationship in mind because pages, data sources, design systems, and files exist at the site level. It’s possible to create resources outside of the context of an app—such as in the Pages or Data Sources screens. This can be useful for creating experimental pages, which may not want to be associated with any app. However, this should only be done if you don’t plan on end users seeing that resource—a form of deployment.

Deployment is one of the key benefits of app-centered development. Creating resources as needed within the app you are working on automatically creates app-resource relationships, which ensures a smooth deployment process:

  • When deploying an app to end users, the app-resource association is often used for more advanced permissioning through app permission sets. If a user does not have permission to access a resource, like a data source, it will not load, and the end user could encounter unexpected behaviors.
  • When deploying an app to another environment, any resources not associated with an app will not deploy as part of that app. For example, if deploying an app from a sandbox environment to a production environment, any pages, data sources, or files not associated with the app will be missing when the app arrives in the destination environment. It’s still possible to deploy these resources individually instead of as part of an app, but this is not best practice.

To safeguard against referencing unassociated resources, Skuid tries to associate resources automatically. When adding existing pages to an app, Skuid will try to associate all necessary resources referenced in the page with the app. And Skuid’s Composer will automatically associate some resources whenever they are selected while working on a page—for example selecting a model’s data source or a Page Include component’s page.

With these safeguards in place, and by practicing app-centered development, the many parts that make up your applications stay organized and easily managed. If you begin to see issues with certain resources not appearing correctly for your end users, be sure they are associated with all the apps they are used within.

Managing Apps

The Apps list screen is accessed by clicking Apps in the Skuid UI navbar. This screen displays all apps configured in the current Skuid environment, with ordering and search options for navigating existing apps. From here you can create new apps, as well as configure or delete existing ones.

Create an app

  1. In the Apps page, click Create.

  2. Set your app details:

    • Name: The name of the app, displayed in the user’s My Apps selector.

    • URL: The URL end users visit to access the app. This URL is a combination of the Skuid environment’s URL and a path specified here. While this field is auto-populated based on your app’s name, you can enter any URL-encoded value.

    • Design system: The design system applied by default to all pages within this app and included as an app resource.

      Note

      If you have v1 pages available, then it is possible to set a theme as the app’s design system.

  3. Click Create.

Delete an app

Note

When deleting an app, its URLs are no longer accessible and its pages are no longer available to end users. The resources are not deleted, but they must be associated with a new app to once again be made accessible.

  1. Click the dots-vertical More Options icon.
  2. Click Delete.
  3. Confirm the deletion by clicking Yes, delete app.

Configuring an App

To access and configure an app’s details:

  1. Click the dots-vertical More Options icon.
  2. Click Details. Alternatively, click the app’s row within the app list.

This navigates to the app’s detail screen, where the app’s settings and resources are configured. You’ll need to configure the following within the app detail screen before end users can access the app:

  • Create the Skuid resources to be used in the app—or add existing resources. This includes pages, data sources, and files.
  • Setting and activating page URLs for all necessary app pages
  • Configuring and assigning proper permission sets to users

These steps may not necessarily happen in this order, but they are all necessary in order to deploy an app to end users.

Setting an app’s design system

Setting an app’s design system does two things:

  • It associates the design system as an app resource, meaning it deploys with the app to other environments.
  • It sets that design system as the default for the app’s pages. Newly created pages within the app automatically select the app’s design system.

Apps can only have one associated design system. However, it’s still possible to add pages that use a different design system to an app. When adding pages with a different design system, you will see a warning, but Skuid will not change the page’s settings. A page’s design system is never automatically updated because existing style variant display logic could break within the page. You’ll need to manually update a page’s design system to match the app. If you’ll be deploying your app to other environments, and it contains pages using other design systems, you must manually deploy those design systems.

Also be wary of changing an app’s design system after you’ve added pages to the app. Existing pages will not be updated to match the newly set design system. If you must change an app’s design system later, then be sure to manually update each page in the app.

Note

If you have v1 pages available, it’s also possible to set a theme as an app’s design system. The same limitations apply: that theme should be used for all pages within the app, as any other themes (or design systems if the app also contains v2 pages) will not be associated as an app resource.

Updating an app’s name and URL

An app’s name determines how it’s listed within the Apps screen, while its URL determines the web address users must visit to see the app. Both of these settings can be updated in the app detail screen.

  1. Within the app detail screen’s header, click the dots-vertical More Options > Edit.
  2. Edit the App Name and App URL fields as needed.
  3. Click Save.

Note

The app URL does not automatically update to reflect any changes to the app name within this modal.

App details and resources

Once in an app’s detail screen, it’s possible to configure the app’s settings in the header section, while the lower portion of the screen deals with the app’s resources.

The tab list, on the left, displays the resources and access settings available to configure within it. This includes the following:

  • Pages
  • Files
  • Data
  • Permissions
  • Users

Creating resources within the app automatically associates them with the app. For example, when creating a page from an app’s detail screen instead of the Pages list screen, the newly created page is automatically associated with the app. That page is also available at the site level and can be used in other apps.

Pages

Apps are made up of Skuid pages, each of which can be made accessible at one or more URLs or used within other pages through the Page Include component. This tab is especially important for app deployment, as you’ll set page URLs within it.

The list within the Pages tab shows several pieces of page info at a glance:

  • Each URL for a page, as well as whether they are enabled (on) or disabled (off)

  • The page type

    • home-page-icon : This page is the app’s home page
    • master-page-icon : This page is master page, which can contain one or more child pages
    • normal-page-icon : A standard Skuid page, also used to represent child pages

  • The last user to update the page and the last modified date

Adding pages, previewing, and removing pages

To create a new page within the app:

  1. Navigate to the app’s Pages tab.
  2. Click Create

To add existing pages that have been created in a separate app or from within the Pages list:

  1. Navigate to the app’s Pages tab.
  2. Click Add.
  3. Select the page you wish to add to the app.

When adding an existing page you will also see a list of the page’s resources that will be added to the app, such as data sources and any included pages.

To preview a page:

  1. Click the dots-vertical More Options > Preview.
  2. If needed, select the URL at which to preview the page.
  3. If necessary, enter values for any parameters required by the page URL. For more information on URL parameters, see the Setting page URLs section.
  4. Click Preview.

The page opens at the selected URL in a new tab.

To remove a page:

  1. Click the dots-vertical More Options > Remove.
  2. Confirm by clicking Remove.

Note

  1. Files are not automatically detected when adding an existing page to an app. Be sure to manually add any files referenced in the page.
  2. If an added page contains Page Include components, Skuid will also add the included pages. However, Skuid only checks one page level deep. If the included pages also use a Page Include component to include other pages, you’ll need to add them manually.

Setting a home page

Apps have a single home page, which serves as a landing page for the app’s URL, and they can have many additional pages.

The first page created within or added to an app is set as the home page, but it is possible to set a different home page after more than one page is associated with the app:

  1. Click the dots-vertical More Options > Make home page.
  2. Click Save.

Note

While normal and child pages can be set as an app’s home page, master pages cannot.

Setting page URLs

Page URLs—the web addresses end users visit to see a Skuid page—are a combination of the app’s URL and one or more URL path elements:

https://sub-domain.skuidsite.com/app-url/page-url

Once a URL is added and activated, end users can access the page if they have app access. Pages can also have multiple active URLs.

Apps are not deployed to end users until their pages have URLs set and activated, and end users have been given access to the app through either a site permission set or an app permission set. Feel free to test and edit your app’s pages at their configured URLs until they are fully functional; your users won’t be able to access the app until they have the correct permissions.

Note

One notable exception to assigning page URLs is the master page type. Master pages serve as structural templates for their associated child pages and cannot function on their own—thus they can’t have URLs assigned to them.

To access a page’s URLs:

  1. Click the dots-vertical More Options icon beside the page.
  2. Click Configure URLs.

From this modal you can take several actions:

To add a page URL:

  1. Click add-circle Add URL.

  2. Set the first path element’s type to Text or Parameter.

    Note

    For information on the types of path elements, see the Path elements in page URLs section.

  3. Enter a value for the path element.

  4. If necessary, click add-circle Add path element and repeat the path element process as needed.

  5. Click Save.

The URL configuration section closes, and the URL is added.

There are several actions you can take on each page URL from the More Options menu.

To enable or disable a page URL:

  1. Click the dots-vertical More Options icon beside the page.
  2. Click Enable or Disable as needed.

To edit an existing page URL:

  1. Click the dots-vertical More Options > Edit.
  2. Update the URL as needed.
  3. Click Save.

To delete a page URL:

  1. Click the dots-vertical More Options > Delete.
  2. Confirm by clicking Delete.
Path elements in page URLs

Path elements determine the structure of page URLs and are used to provide information about the context of the page. They can explain where the page sits in a site’s hierarchy or provide data for the page to use in its components. Each path element can be a fixed text string or dynamic parameter. Path elements are added by clicking Add path element, entering the element’s value, and clicking Save within the Configure URLs modal for a page.

Text path elements are static descriptors for the app’s logical hierarchy. You can convey how related pages are grouped using them.

For example, consider example.skuidsite.com/marketing/dashboard.

  • The app’s URL is example.skuidsite.com/marketing
  • The page’s single path element is the text dashboard

However it’s possible to have more dynamic URLs using a parameter path element. These path elements function as variables that can be used in the page. They are commonly used for passing in model condition values, like record Ids, to the page.

For example, consider example.skuidsite.com/marketing/promotional-materials/{materialId}

  • The app’s URL is example.skuidsite.com/marketing
  • The page’s first path element is the text promotional-materials
  • The page’s second path element is the parameter materialId

In this case, materialId is used to set the record Id of the promotional material item the user is viewing. The parameter element is what passes in the necessary information to the detail page.

A parameter can be made optional only if it is the final path element, as it’s not possible to have a missing path element in the middle of a page URL.

Whether a text or parameter, a path element’s value can only use URL-acceptable characters—letters, numbers, underscores, and dashes.

Using multiple path elements

Depending on the structure of your app, you may have many path elements for a single page. Text elements are useful for setting the hierarchy of your app, while parameters provide important contextual information.

As an example, consider an HR app that allows users to submit paid timeoff (PTO) requests and then review their requests as a list.

  • This app is available at example.skuidsite.com/hr.
  • The Skuid page used to submit and review requests is located at example.skuidsite.com/hr/pto/request
    • This URL uses two text path elements. Because of these two path elements, users can understand how the page they are on relates to other areas of the app.

But the user may also want to review the details of a single request. To do so, there’s a separate Skuid page that shows the details of a single request available at example.skuidsite.com/hr/pto/request/{requestId}.

  • The URL has the two previous text path elements.
  • It also contains a parameter element in addition to the previous two text elements. Using the {requestId}} parameter in a model condition allows the Skuid page to query the proper details. By placing that after the previous two elements, the user still understands where they are in the app.

Depending on your page’s setup, this could also be a good use case for an optional last parameter. To do so, the Skuid page would need to contain detail view components that conditionally render if a requestId page parameter exists. With this setup, you could render the detail-related components of your Skuid page when that parameter is available. If it isn’t available, only the “list” view components renders. This may or may not work for your particular use case, but it is possible.

Files

The Files tab lists all files associated with the app. Files are typically used for images or JavaScript resources.

To upload a new file and associate it with the app:

  1. Click Upload.
  2. Select the file and confirm the selection.

The file is now uploaded and associated with the app.

To add an existing file to the app:

  1. Click Add.
  2. Select each file you wish to associate with the app—using the Search form to narrow the listed options as needed.
  3. Click Add.

Each selected file is now associated with the app.

Data

The Data tab lists all data sources associated with the app. For more information on data source configuration, see the Data documentation section.

Note

Just because a data source is added to an app does not mean that users have access. Access to data sources must be granted via permissions sets (either in the app or at the site-level). Also, if a data source uses data source objects—like SQL data sources—more granular permissions must be set for each object. For more information, see the Permissions in Skuid topic.

To create a new data source and associated it with the app:

  1. Click Create.

  2. Proceed through the data source creation process, which varies depending on your selected data source type.

    Note

    It may appear that you have left the app’s UI, but Skuid tracks the app you began data source creation from.

  3. After configuring all necessary data source properties, click Save.

You are redirected to the app’s detail screen, and the newly created data source is associated with the app.

To add an existing data source to the app:

  1. Click Add.
  2. Click the checkbox beside each data source to add.
  3. Click Add.

Permissions

The Permissions tab lists all of the app permission sets created for the app. In contrast to site permission sets, app permission sets apply only when the user is visiting a page within the app.

To create an app permission set:

  1. Click Create.
  2. Fill out the permission set’s information:
    • Name
    • Description
  3. Click Save and continue.
  4. Select the data sources the app permission set should grant access to.
    • If applicable, configure the data source object permissions as needed.
  5. Click Save and finish.

For more information on permissioning concepts and management, see the Permissions in Skuid topic.

Users

The Users tab shows all users who have access to the app, either through their site permission set or through one or more app permission sets.

Permission sets are an essential part of app deployment, because they determine which users have app access—and what they can do within those apps. Because of that, you’ll often move back and forth between the Permissions and Users tab often—creating the necessary app permission sets in the former and ensuring all necessary users have app access in the latter.

Within the Users tab, each user is listed with the following information:

  • First and last name
  • User name
  • Federation ID
  • Their site permission set if it grants access to the app
  • Any app permission sets granted to the user within the app

To add users to the app:

  1. Click Add.

  2. Click Add beside each user you wish to grant app access to—using the Search form to narrow the listed users as needed. To remove a user from the process, click Remove.

    Note

    Only users without app access appear in this list. Existing users cannot be selected here.

  3. Click Next.

  4. Select each permission set you assign to all selected users—using the Search form to narrow the listed permission sets as needed.

  5. Confirm the selected choices and click Finish.

    • If you’d like to remove a user at this screen, click remove-circle beside the user.

When managing an app’s users, there are two different detail screens within dots-vertical More Options menu beside each user:

  • App user detail: Accessible by clicking dots-vertical More Options > Manage app access. This detail screen, which appears as a sliding panel in the Users tab, is used to manage a user’s permissions within the context of the app. It displays the assigned permission sets that grant the user app access—whether that be a site permission set or one or more app permission sets—as well as some basic user information.
  • Site user detail: Accessible by clicking dots-vertical More Options > Go to site user detail. This screen is used to manage a user’s site-level details—name, email address, site permission set, and other settings.

Troubleshooting

My end users are seeing data access errors

Data access issues that occur only in specific apps typically have two main causes:

  • Permissions: Ensure that users have the appropriate permissions assigned to them through their site permission set or an app permission set. For more information, see the Permissions in Skuid topic.
  • App resource association: If a data source is used in a page model, but not associated with the page’s app, then end users could see errors. Ensure that all data sources are added to the app.

If you are seeing issues in your models or data sources in general, check that your data source settings are properly configured. See the Data section for more information.