Horizon Framework

Object Names

Overview

Admins on Skedulo platform tenants can rename standard objects, for example Jobs to "Visit" and "Visits". Components that show an object's name need the tenant's labels rather than a hard-coded English word. Horizon Core keeps every object's labels in one module store, so React code, plain functions and templates all read the same values.

Most tenants never rename an object. With no override every text stays exactly as it is today, and only a real Skedulo override changes a text, one form (singular or plural) at a time. The store reads two requests in each refresh:

  • the Data Model API, query { objects { name label labelPlural } } posted to dataaccess/graphql/datamodel, which gives the final label of every object;
  • GET custom/standard_schemas, which gives the default label and the Skedulo overrides labelOverride and labelPluralOverride of every standard object.

Labels load once per page. Window focus and the tab becoming visible refresh them at most once every 60 seconds, and refreshObjectNames() refreshes them on demand. They load for every tenant, including Salesforce. Labels are kept in memory only.

Nothing here throws or rejects. If a request fails, the last good labels stay in place. If the Data Model API returns GraphQL errors, for example because the tenant's data model does not build, a console warning is logged once per tenant. If custom/standard_schemas returns 401 or 403, for example for a custom role without skedulo.tenant.schema.view, no object is renamed and a console warning is logged once per tenant, with no Datadog log and no extra backoff. Other failures are logged to Datadog; a failed custom/standard_schemas read keeps the overrides last read.

The ObjectNames type

Every reader returns an ObjectNames value. The type is exported, so you can use it for props and helpers.

import type { ObjectNames } from '@skedulo/horizon-core'

// { readonly singular: string; readonly plural: string; readonly renamed: boolean }
const describe = ({ singular, renamed }: ObjectNames) =>
  renamed ? `${singular} (renamed)` : singular

React hook

useObjectNames returns the names for an object and renders again when they load or change. It needs no provider and never suspends: until the labels arrive it returns the English defaults.

import { useObjectNames } from '@skedulo/horizon-core'

const JobsHeading = () => {
  const { singular, plural, renamed } = useObjectNames('Jobs')

  return <h1>{renamed ? `${plural} (${singular})` : plural}</h1>
}

A component only renders again when the names for its own object change.

Reading outside React

readObjectNames returns the current names synchronously. The result is the same object until its values change. subscribeObjectNames and getObjectNamesVersion let non-React code react to changes.

import {
  readObjectNames,
  subscribeObjectNames,
  getObjectNamesVersion,
} from '@skedulo/horizon-core'

const { singular, plural } = readObjectNames('Jobs')

const unsubscribe = subscribeObjectNames(() => {
  console.log('Labels changed, version', getObjectNamesVersion())
})

The version starts at 0 and rises by 1 each time a label state changes, including a change of an override. A refresh that changes labels but no label state leaves it alone. A listener that throws does not stop the others.

An empty, blank or non-string name returns { singular: '', plural: '', renamed: false }.

In a sentence

readObjectNamesInSentence returns the same names lower-cased for use in the middle of a sentence. Title-case words are lower-cased. Acronyms, mixed-case words and words with punctuation, such as Co-op, keep their case.

import { readObjectNamesInSentence } from '@skedulo/horizon-core'

// With Jobs renamed to "Visit" and "Visits"
readObjectNamesInSentence('Jobs') // { singular: 'visit', plural: 'visits', renamed: true }
// A label of "SKU Item" gives "SKU item"

Templates

Nunjucks templates read the names with _.host.objectNames, and the lower-cased names for the middle of a sentence with _.host.objectNamesInSentence. They return the same values as readObjectNames and readObjectNamesInSentence. A template renders again when a name changes.

You have no {{ _.host.objectNames("Jobs").plural }} scheduled.
Choose the {{ _.host.objectNamesInSentence("Resources").plural }} to notify.

_.host.objectLabel(name, form, defaultText, case) reads one form with readObjectLabel. With no override on Jobs it renders the default text, and after the override "Visits" it renders the tenant word:

{{ _.host.objectLabel('Jobs', 'plural', 'Work items', 'sentence') }}

This renders "Work items" with no override and "visits" after the override "Visits".

With Resources renamed to "Technician" and "Technicians", the second line renders as "Choose the technicians to notify."

The rename rule

One rule applies to every standard object. Each form is tested against its own default. The default plural is the label that custom/standard_schemas returns, and the default singular is pluralize.singular(label). An override counts when all of these hold:

  • it is set, and not blank;
  • it differs from the default of its form, ignoring case and surrounding spaces;
  • it holds none of {, }, <, >, a double quote, a backslash or a control character.

renamed is true when at least one form has a counted override. A form with no counted override keeps today's text. The client never builds a plural.

The same character filter applies to every word the store returns, not only to overrides. A word from the Data Model API (a custom object label, a Salesforce vendor label or a final label) or a default label that holds a filtered character is ignored, and that form falls back to the name derived from the object's API name.

Jobs, default "Job" and "Jobs"renamedSingularPlural
no overridefalseJobJobs
"Job" and "Jobs", or "JOB" and "JOBS"falseJobJobs
"Visit" and "Visits"trueVisitVisits
"Appointment" and no plural, or "Jobs"trueAppointmentJobs
a singular with a filtered character, "Visits"trueJobVisits

A custom object is never renamed: it keeps its own label, and its defaults is null.

Salesforce vendor labels do not count. Only Skedulo overrides count, on both vendors. A rename made in Salesforce Setup changes the label the Data Model API returns, but no longer sets renamed, and a text that has a default text keeps it. A text with no default text shows the final label for that form, as it does today, even when the other form is renamed. An admin who wants every text to follow a rename sets the Skedulo override through the API, PUT custom/standard_schemas/<Object> with {"label": "...", "labelPlural": "..."}.

Label state and the label reader

readObjectLabelState returns the state behind every reader:

import { readObjectLabelState } from '@skedulo/horizon-core'

// { singular, plural, renamed, overridden: { singular, plural }, defaults: { singular, plural } | null }
const state = readObjectLabelState('Jobs')

overridden[form] is true only for a counted override. defaults is null whenever there is no standard row for the name: a custom object, an unknown name, labels not loaded yet, or access denied. For a form that is not overridden, the word is the default of the form, or the Data Model API label when the tenant stored nothing for that form, so a vendor label still shows.

readObjectLabel(name, form, options) and useObjectLabel(name, form, options) return the text of one form, 'singular' or 'plural'. The tenant word wins when it counts. Then the caller's defaultText, returned exactly as written, except that a blank defaultText counts as absent. Then the platform word.

import { useObjectLabel } from '@skedulo/horizon-core'

const Empty = () => {
  const text = useObjectLabel('Jobs', 'plural', {
    defaultText: 'Work items',
    case: 'sentence',
  })

  return <p>No {text} scheduled.</p>
}

case: 'sentence' lower-cases title-case words of a tenant word or a platform word. case: 'capital' does the same and then sets a capital first letter. Neither option changes the default text. A blank name, a name that is not a string or an unknown form returns an empty string.

Loading and refresh

  • The first request starts when HorizonRootProvider mounts with an API client that has a tenant id. This includes Salesforce tenants.
  • The window gaining focus and the tab becoming visible start a request only if none is in flight and 60 seconds have passed since the last one started. The Data Model API caches for 60 seconds, so refreshing sooner gains nothing. Route changes do not start a request.
  • After a failed request, the wait doubles for each failure in a row, up to 30 minutes. A successful request or a tenant change resets the wait to 60 seconds.
  • refreshObjectNames() starts a request straight away, whatever the wait, or returns the one already in flight. The promise resolves when the request ends and never rejects.
  • If the same tenant gets a new API client the labels stay. If the tenant changes, the labels are cleared and requested again, and a late response for the old tenant is dropped.
  • A refresh sends one Data Model API request and one custom/standard_schemas request. If it returns the same data, nothing is notified and the version does not change.

Defaults

Before the labels load, after a failed first request, and when no API client with a tenant id is connected, the English defaults are returned. For a name no endpoint returned, the API name is spaced and inflected, so WidgetParts gives "Widget Part" and "Widget Parts", and SMSTemplates gives "SMS Template" and "SMS Templates". The derivation keeps the spelling it is given, so jobs gives "job" and "jobs".

Testing

seedObjectNames, seedObjectLabels and resetObjectNamesStore are exported for tests. seedObjectNames seeds Data Model API labels. seedObjectLabels({ model, standard }) seeds both endpoint rows, so a test goes through the real rule. Seeding applies labels the same way a response does, and resetting restores the empty initial state. Seeding also tags the store with a tenant id, 'tenantId' unless you pass another as the second argument, so connecting a client for a different tenant clears the seeded labels.

import {
  renderWithContext,
  resetObjectNamesStore,
  seedObjectLabels,
  useObjectNames,
} from '@skedulo/horizon-core'

const JobsHeading = () => <h1>{useObjectNames('Jobs').plural}</h1>

beforeEach(() => {
  resetObjectNamesStore()
})

it('shows the tenant label', () => {
  seedObjectLabels({
    standard: [
      {
        name: 'Jobs',
        label: 'Jobs',
        labelOverride: 'Visit',
        labelPluralOverride: 'Visits',
      },
    ],
  })

  const { getByRole } = renderWithContext(<JobsHeading />)

  expect(getByRole('heading').textContent).toBe('Visits')
})