Skip to main content

Version: 23.10

Service-level agreement

A service-level agreement (SLA) is a contract between parties stating how certain aspects of business between them is to be conducted. An SLA may define time-based escalation points, identified as specific time threshholds measured with respect to a reference timestamp. Workspaces includes support for this aspect of SLAs, offering two approaches:

  • A comprehensive SLA comprised of multiple time thresholds measured from a reference date in the future or the past.
  • A basic SLA with a warning threshold measured backwards from a reference date such as the SLA due date.

To learn how the SLA feature works from the end-user perspective, see Service level agreement (SLA) in the Workspaces user guide.

Properties​

An SLA configuration is a mapping with properties that define various aspects of the SLA. All properties are required.

Typescript
mappings: {
  ...
  $taskSla: {
    label: '',
    dataIndex: '',
    type: 'alert',
    sla: { ... },
  },
  ...
}
PropertyDescription
labelstring (GlobalLabel)
The display label for this mapping.
typestring (GlobalType)
The mapping's property type. For an SLA property, specify the value as 'alert'.
dataIndexstring (GlobalDataIndex)
A Txn property path representing the SLA Reference Date from which time thresholds are measured. dataIndex can refer to a defined Txn property such as date created, or a property with a calculated value. The SLA Reference Date can be the Txn's creation date or any later date such as the SLA Due Date.
slaobject (GlobalSla)
An object containing items mapping time thresholds to colors which are used in the user interface to style the SLA indicator displayed on List screens. Each SLA item represents an SLA status change.
  • Time thresholds: Specify a value that represents an amount of time, such as '2 days' or '48 hours'. Time thresholds support the same formats as the SugarJS Date.rewind function. While you can use time units such as 'hours', 'days', or 'weeks', we recommend using a single time unit consistently in this property.
    Note: A time threshold that corresponds to a date earlier than the Txn's creation date is ignored.
  • Colors: Specify a color name or hex value. Alternatively, you can specify 'transparent' for no color, effectively hiding any associated SLA status UI element.
tip

If your SLA includes a single time threshold only, consider using a basic SLA instead.

To review the list of all supported properties, see API Reference.

Configuration​

The key to configuring an SLA is specifying a set of time thresholds (sla) that represent SLA status changes, and an SLA Reference Date (dataIndex) against which the time thresholds are measured.

  • The SLA Reference Date corresponds to an sla item with a zero value such as '0 days' or '0 hours'.
  • Time thresholds for dates earlier than the SLA Reference Date are represented by positive values.
  • Time thresholds for dates later than the SLA Reference Date are represented by negative values.
  • Time thresholds representing dates earlier than the Txn's creation date are ignored.

While the order of sla items is not important, we recommend that you specify them in order of decreasing time threshold value to aid in understanding which color applies at any time. When considered in this order, the first sla item corresponds to the earliest date, with each successive item corresponding to a later date. The first and last sla items extend away from the SLA Reference Date, and their colors are applied accordingly to all days in their respective directions. The first sla item extends back as far as the Txn's creation date, while the last sla item extends indefinitely into the future.

note

The sla configuration does not handle time zone adjustments inherently. Ensure that time thresholds correspond to dates that align with the time zone used in your data to prevent discrepancies.

As you can see, configuring an SLA can be a little tricky, especially if your SLA requirements are not straightforward. Therefore, we recommend you test your SLA configuration thoroughly, validating that the sla time thresholds and colors align with your requirements, to ensure it behaves as expected.

Examples​

The examples below show three different ways to configure an SLA with a due date 2 weeks (14 days) after the Txn creation date. The examples vary in that they use different SLA Reference Dates (dataIndex) and, hence, different sla configurations.

The following image illustrates the example SLA.

An example SLA

The example SLA has six statuses as follows, each of which is associated with a different color:

  • Transparent is associated with the first three days after the Txn was created. In this SLA, this represents a cooling-off period during which the applicant has the opportunity to reconsider their application before application processing commences.
  • Green is associated with the next 7 days. After the cooling-off period, processing staff commence application processing in accordance with the further conditions of the SLA. Sufficient time remains to complete the task without breaching the SLA.
  • Orange is associated with the next 3 days, emphasizing the deadline for completing application processing is approaching, and that staff should attend to the task soon.
  • Red is associated with the next 1 day, signifying that the application processing deadline is imminent and that the task needs to be completed within 24 hours to avoid breaching the SLA's terms.
  • Black is associated with the next 1 day, indicating that the task is due or overdue, and that the SLA has been breached.
  • Purple is associated with every day thereafter, highlighting the need to work on the task urgently as the SLA has been breached.

Each of the examples defines six sla time thresholds corresponding to the six SLA statuses described above. Time thresholds are specified in order of decreasing time threshold value, starting with the earliest time threshold. Specifying time thresholds in this order makes it easy to see how each time threshold acts as a change in SLA status and, hence, color.

Example 1: SLA Reference Date is SLA Due Date​

Typescript
mappings: {
    ...
    $taskSla: {
        label: 'SLA',
        dataIndex: "properties['taskSla']",
        type: 'alert',
        sla: {
            '12 days': 'transparent',   // Tasks due within 14 days but not more than 11 days
            '11 days': 'green',         // Tasks due within 11 days but not more than 4 days
            '4 days': 'orange',         // Tasks due within 4 days but not more than 1 day
            '1 day': 'red',             // Tasks due within 1 day (24 hours)
            '0 days': 'black',          // Tasks due or overdue by up to 1 day (SLA Reference Date = SLA Due Date)
            '-1 day': 'purple',         // Tasks more than 1 day overdue
        },
    },
    ...
}

In this example:

  • The SLA Reference Date (dataIndex) is the SLA Due Date ("properties['taskSla']") which is assumed to have a calculated value equal to the Txn creation date plus 14 days.
  • The '12 days': 'transparent' time threshold effectively hides a Txn's SLA indicator prior to reaching the '11 days': 'green' time threshold.

The following image illustrates this SLA configuration.

The SLA Reference Date is the SLA Due Date

Example 2: SLA Reference Date is Txn creation date​

Typescript
mappings: {
    ...
    $taskSla: {
        label: 'SLA',
        dataIndex: `timeCreated`,
        type: 'alert',
        sla: {
            '0 days': 'transparent',    // SLA Reference Date = Txn creation timestamp
            '-3 days': 'green',         // 3 days after the SLA Reference Date
            '-10 days': 'orange',       // 10 days after the SLA Reference Date
            '-13 days': 'red',          // 13 days after the SLA Reference Date
            '-14 days': 'black',        // 14 days after the SLA Reference Date (SLA Due Date)
            '-15 days': 'purple',       // 15 days or more after the SLA Reference Date (1 day after the SLA Due Date)
        },
    },
    ...
}

In this example:

  • The SLA Reference Date (dataIndex) is the Txn creation date (timeCreated).
  • The '0 days': 'transparent' time threshold effectively hides a Txn's SLA indicator prior to reaching the '-3 days': 'green' time threshold.

The following image illustrates this SLA.

The SLA Reference Date is the Txn's creation date

Note that the 'transparent' item isn't required as the SLA is measured forward in time from the SLA Reference Date (Txn creation date) so the SLA is applied to Txns only once they have been created. Time thresholds before the SLA Reference Date are invalid because the SLA Reference Date is equal to the Txn creation date.

Example 3: SLA Reference Date is in between Txn creation date and SLA Due Date​

Typescript
mappings: {
    ...
    $taskSla: {
        label: 'SLA',
        dataIndex: "properties['taskSlaRef']",
        type: 'alert',
        sla: {
            '1 day': 'transparent', // Every day from the Txn creation date until the SLA Reference Date
            '0 days': 'green',      // SLA Reference Date = Txn creation timestamp
            '-7 days': 'orange',    // 5 days after the SLA Reference Date
            '-10 days': 'red',      // 9 days after the SLA Reference Date
            '-11 days': 'black',    // SLA Due Date, 10 days after the SLA Reference Date
            '-12 days': 'purple',   // 11 days after the SLA Reference Date (1 day after the SLA Due Date), and every day thereafter
        },
    },
    ...
}

In this example:

  • The SLA Reference Date is aligned with the commencement of application processing, 3 days after the Txn's creation.
  • The '1 day': 'transparent' time threshold effectively hides a Txn's SLA indicator prior to reaching the '0 days': 'green' time threshold.

The following image illustrates this SLA.

The SLA Reference Date is the Txn's creation date

Basic SLA​

A basic SLA is a mapping configured with properties defining a single time threshold measured backward from the SLA due date. All properties are required.

PropertyDescription
labelstring (GlobalLabel)
The display label for this mapping.
typestring (GlobalType)
The mapping's property type. For an SLA property, specify the value as 'alert'.
dataIndexstring (GlobalDataIndex)
The SLA due date. Specify a Txn property path that represents the Txn's SLA due date in the future.
warningstring (GlobalWarning)
The SLA's warning time threshold measured backwards from the SLA due date. Specify a value that represents an amount of time, such as '10 days' or '2 weeks'.
note

If a mapping contains both sla and warning properties, sla takes precedence.

info

The SLA due date value for the Txn property specified in dataIndex is set in a custom script.

The following example is a partial configuration showing a basic SLA with a 1-week warning threshold:

mappings: {
  ...
  $taskSla: {
    label: 'SLA',
    dataIndex: "properties['taskSla']",
    type: 'alert',
    warning: '1 week'
  },
  ...
}