Developing a connected page

A connected page is a standalone web page and its content can be created using any current web development technologies. The SDK contains a boilerplate based on React and Typescript, which you can use as a starting point to build your own pages. The boilerplate contains type definitions for the services that are injected into the page by the Skedulo connected page runtime. This chapter and examples are based on this boilerplate.

The Services.ts file located in the connected page project’s source (/src/Services) folder. This file contains all of the type definitions for the services that Skedulo injects into the connected page. For example, we include type definitions for making GraphQL requests and mutations, error handling types, metadata types, and credentials types for fetching vocabulary:

export interface Services {
  graphQL: {
    fetch<T>(operation: GraphQLRequest, endpoint?: string): Promise<T>
    mutate(operation: GraphQLRequest, endpoint?: string): Promise<GraphQLMutationResult>
    fetchMetadataFor(model: string): Promise<IntrospectionModelType>
  },
  metadata: {
    fetchVocabulary(): Promise<Vocabulary>
  },
  errorClasses: {
    GraphQLNetworkError: GraphQLError,
    GraphQLExecutionError: GraphQLError
  },
}

export interface Profile {
  tenantId: string
  userId: string
  username: string
  roles: string[]
}

export interface Credentials {
  apiServer: string
  apiAccessToken: string

  vendor: { type: 'skedulo', url: string, token: null } | { type: 'salesforce', url: string, token: string }
}

Skedulo keeps these type definitions up to date, and any new connected pages created will have access to the newly-created type definitions.

DataServices.ts is the file used to handle CRUD operations and queries you need to execute through your connected page. You can use the GraphiQL connected page in the Skedulo web application to build and test your queries to ensure that they work correctly, then copy and paste the query into the DataServices.ts file.

Enable developer mode

To begin developing a connected page, you will have to enable developer mode.

Prerequisite

You must have installed and set up the SDK and it must be running. For more information about how to do this, see Installation and Setup.


  1. In the web application, click your user Profile -> Settings -> Connected Pages, or click here.

    Connected Pages

  2. In the Connected Pages section, click the Developer Mode Enabled toggle button at the upper-right.

  3. When developer mode is turned on the web app will connect to the SDK and display the development options. If it does not connect, check that your SSL certificates are set up correctly.

    The following screen message appears:

    “Welcome to Skedulo’s Connected Pages platform. To begin, select one of the following options.”

    Connected Pages

Creating and editing a connected page

  1. In the Skedulo SDK, click Manage Connected Pages -> Create new project to get started. You will be asked to fill out some additional metadata related to the page that you intend to build.

    Connected Pages

    • Title: The title of the page – this shows up as the title of the page once it has been deployed.
    • Description: A description summarizing the functionality of this page (useful during page management).
    • Page URL: The URL slug where this page should be available. This is specific to your tenant.
    • Menu I.D: A short, two character identifier for this page that will be rendered on the Skedulo web app nav bar.
    • Show In Nav Bar?: Should this page be accessible via a nav bar link? If you are intending to build a contextual page relying on context passed in via URL, this could be set to False.
  2. Select a base template for your connected page. The SDK ships with a React/Typescript template that will help you get up and running quickly with the stack. The templates ship with type definitions that will help you use the services that we provide on the connected page.

  3. Click in the Directory field to select a directory and create a folder in which to store your project files. It is important that you create a new, empty folder for the project, as when you create the connected page in the following step it will create the required files in the folder you have selected, so if you have a non empty folder it will store all of those files and folders next to the existing ones.

  4. After you have selected a template and the directory where you would like to create and save the project files, click Create page.

    Connected Pages

  5. The SDK will then proceed to set up the project folder with the template files and bootstraps the project ready for development. Once this is done, the SDK will transition to the project page.

    Connected Pages

  6. Click Start Development in the upper-right to turn on the development tooling. You should see a URL to the hosted development page (at the top of the SDK window), as well as some output on the terminal.

    Connected Pages

  7. To view the page currently under development, click the URL specified at the top of the SDK window. By default, the template shows the default (or draft) view of the page.

    In the following example, the draft page features a simple GraphQL query used to fetch a list of jobs that is rendered on the screen:

    Connected Pages

  8. Open the project folder to edit the following template files in an editor of your choice:

    • $PROJECT_FOLDER/src/App.tsx
    • $PROJECT_FOLDER/src/Services/DataServices.ts
  9. Update these files to change the data displayed. For example:

    a. Add JobStatus, Duration, and Start fields to the information retrieved by the GraphQL query by editing the DataServices.ts file:

    const JobsQuery = `
    {
      jobs {
        edges {
          node {
            UID
            Name
            Description
            JobStatus
            Duration
            Start 
          }
        }
      }
    }

    b. Then edit the App.tsx file to display the new fields on the connected page:

    renderTableOfData = (data: AppState['data']) => {
    
      return (
        <table>
          <tbody>
            { data.map(d => (<tr key={ d.UID }><td>{ d.Name }</td><td>{ d.Description }</td><td>{ d.JobStatus }</td><td>{ d.Duration }</td><td>{ d.Start }</td></tr>)) }
          </tbody>
        </table>
      )
    }

    When you save the changes in the App.tsx file the SDK terminal automatically applies the changes. Use the Reload button in the upper-right of the page preview in the web application to quickly reload the contents of the page.


Last modified August 1, 2019: updated to end of connected pages (8161217)