# System Status Messages

Canonical page: https://www.adaptabletools.com/docs/handbook-system-status-message

- System Status Messages keep users informed about application or data health at run time
- They appear in the System Status toolbar, tool panel, status bar, dashboard module button, and Settings Panel history
- Optional **toast** popups use the same notification stack as Alerts (`showSystemStatusMessageNotifications`)
- Post messages via **`systemStatusApi`**; configure history size and toasts in **`notificationsOptions`**

AdapTable allows developers and support teams to send **System Status Messages** at run time.

Each message has a **`StatusType`** (`Info`, `Success`, `Warning`, `Error`) with an associated theme colour.

Messages are sent through **`adaptableApi.systemStatusApi`** — see [Sending messages](https://www.adaptabletools.com/docs/handbook-system-status-message/index.md#sending-messages) below.

## Topics in this Section

| Topic                                                                                                             | Summary                                                                    |
| ----------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
| This page                                                                                                         | Where messages appear, status types, sending, session history              |
| [Configuring System Status Messages](https://www.adaptabletools.com/docs/handbook-system-status-message-configuring/index.md)       | `maxSystemMessagesInStore`, `showSystemStatusMessageNotifications`         |
| [System Status Message Technical Reference](https://www.adaptabletools.com/docs/technical-reference-system-status-message/index.md) | **`systemStatusApi`**, **`SystemStatusMessageDisplayed`** event            |
| [Toast Notifications](https://www.adaptabletools.com/docs/ui-tutorial-using-toast-notifications/index.md)                           | Shared toast styling (`notificationsOptions`) for System Status and Alerts |

## Displaying Messages

System Status Messages are displayed in the System Status Message section of the [Settings Panel](https://www.adaptabletools.com/docs/ui-settings-panel/index.md).

This screen can be accessed by selecting _Show System Status_ in the Column and Context Menus

This shows a history of **all** System Status Messages (sent in the current session) and ordered by the most recently received Message.

- Messages which include a `FurtherInformation` property (or which are very long Messages) display an **ellipsis**
- This allows for the whole Message to be read when it is clicked

There is a _Delete All Messages_ button which will clear the Messages from State.

### Other Message Locations

System Status messages can also be displayed in multiple places in AdapTable including:

- as a Toast Notification (if `showSystemStatusMessageNotifications` is set to _true_ in [Notifications Options](https://www.adaptabletools.com/docs/technical-reference-notifications/index.md))

- in System Status Toolbar

- in System Status ToolPanel

- in the [Dashboard](https://www.adaptabletools.com/docs/ui-dashboard/index.md) via the `SystemStatus` Module Button which shows a different icon appropriate to the last Message's Status Type

- in the Status Bar

- in a Custom Div (if one is provided by a developer in [Container Options](https://www.adaptabletools.com/docs/technical-reference-container/index.md) via `systemStatusContainer`)

- through the [System Status Message Displayed Event](https://www.adaptabletools.com/docs/technical-reference-system-status-message/index.md#system-status-message-displayed-event)

See [Configuring System Status Messages](https://www.adaptabletools.com/docs/handbook-system-status-message-configuring/index.md) for toast and history limits.

## Status Types

Each System Status Message has a `StatusType` with an associated colour.

- AdapTable associates each StatusType with a [CSS Variable](https://www.adaptabletools.com/docs/handbook-theming-custom/index.md) to set the colour of the System Status Message
- The colour returned by any of these variables can be set when [Customising an AdapTable Theme](https://www.adaptabletools.com/docs/handbook-theming-custom/index.md)

The 4 Status Types (of type [`AdaptableMessageType`](https://www.adaptabletools.com/docs/reference/adaptablemessagetype.md)) and their associated default colours are:

| Status Type | CSS Variable           | Default Colour                                                                                         |
| ----------- | ---------------------- | ------------------------------------------------------------------------------------------------------ |
| Info        | --ab-color-info        | <div style={{background: 'var(--ab-color-info)', padding: '0.5rem', borderRadius: 5}}>Blue</div>       |
| Success     | --ab-color-success     | <div style={{background: 'var(--ab-color-success)', padding: '0.5rem', borderRadius: 5}}>Green</div>   |
| Warning     | --ab-color-warn        | <div style={{background: 'var(--ab-color-warn)', padding: '0.5rem', borderRadius: 5}}>Orange</div>     |
| Error       | --ab-color-destructive | <div style={{background: 'var(--ab-color-destructive)', padding: '0.5rem', borderRadius: 5}}>Red</div> |

**Example: System Status**

Sending and Displaying System Status Messages

- This demo **sends** System Status messages (via **`systemStatusApi`**) in 2 ways:
  - clicking the buttons in the 'Setting Message Buttons' _Custom Toolbar_ - there is one button for each available Status Type
  - selecting the entries in the 'Set System Status' User Menu Item in the Context Menu
- It **displays** these System Status messages:
  - in the System Status Toolbar
  - in the System Status Tool Panel
  - the System Status Module Button in the Dashboard (which changes colour and image based on the System Type)
  - in the System Status section of the Settings Panel (available by clicking the System Status Module Button or the configure button in the System Status Toolbar)

- Click the buttons in the _Setting Message Buttons_ Toolbar to see the System Status Message change

Demo project (Vanilla); the files without a marker are shown below:

```text
src/
  adaptableOptions.ts
  agGridModules.ts     [template]
  columnDefs.ts        [template]
  gridOptions.ts       [template]
  index.ts             [template]
  onAdaptableReady.ts  [template]
  rowData.ts           [template]
  styles.css           [template]
index.html             [template]
package.json           [template]
tsconfig.json          [template]
```

Files marked `[template]` are the same in every demo; see the [demo template](https://www.adaptabletools.com/llms/demo-template.md#vanilla).

**`src/adaptableOptions.ts`**

```ts
import {
  AdaptableButton,
  AdaptableOptions,
  ContextMenuContext,
  CustomContextMenuContext,
  CustomToolbarButtonContext,
  UserContextMenuItem,
} from '@adaptabletools/adaptable';
import {WebFramework} from './rowData';

export const adaptableOptions: AdaptableOptions<WebFramework> = {
  primaryKey: 'id',
  adaptableId: 'System Status Message',
  dashboardOptions: {
    customToolbars: [
      {
        name: 'SettingMessageButtons',
        title: 'Setting Message Buttons',
        toolbarButtons: [
          {
            label: 'Set Info',
            buttonStyle: {
              variant: 'text',
              tone: 'info',
            },
            onClick: (
              button: AdaptableButton<CustomToolbarButtonContext>,
              context: CustomToolbarButtonContext
            ) => {
              context.adaptableApi.systemStatusApi.setInfoSystemStatus(
                'No issues'
              );
            },
          },
          {
            label: 'Set Success',
            buttonStyle: {
              variant: 'text',
              tone: 'success',
            },
            onClick: (
              button: AdaptableButton<CustomToolbarButtonContext>,
              context: CustomToolbarButtonContext
            ) => {
              context.adaptableApi.systemStatusApi.setSuccessSystemStatus(
                'All working fine'
              );
            },
          },
          {
            label: 'Set Warning',
            buttonStyle: {
              variant: 'text',
              tone: 'warning',
            },
            onClick: (
              button: AdaptableButton<CustomToolbarButtonContext>,
              context: CustomToolbarButtonContext
            ) => {
              context.adaptableApi.systemStatusApi.setWarningSystemStatus(
                'Problems with server',
                'Avoid any unnecessary edits'
              );
            },
          },
          {
            label: 'Set Error',
            buttonStyle: {
              variant: 'text',
              tone: 'error',
            },
            onClick: (
              button: AdaptableButton<CustomToolbarButtonContext>,
              context: CustomToolbarButtonContext
            ) => {
              context.adaptableApi.systemStatusApi.setErrorSystemStatus(
                'The server is down!',
                'Please do not make any edits until the server comes back up'
              );
            },
          },
        ],
      },
    ],
  },
  notificationsOptions: {
    duration: 2000,
  },
  contextMenuOptions: {
    customContextMenu: (context: CustomContextMenuContext) => {
      const {defaultAgGridMenuStructure, defaultAdaptableMenuStructure} =
        context;

      const setSystemStatusMenuItem: UserContextMenuItem = {
        menuType: 'User',
        label: 'Set System Status',
        subMenuItems: [
          {
            menuType: 'User',
            label: 'Set Error',
            icon: {
              name: 'error',
            },
            onClick: (menuContext: ContextMenuContext) => {
              menuContext.adaptableApi.systemStatusApi.setErrorSystemStatus(
                'System Down'
              );
            },
          },
          {
            menuType: 'User',
            label: 'Set Warning',
            icon: {
              name: 'warning',
            },
            onClick: (menuContext: ContextMenuContext) => {
              menuContext.adaptableApi.systemStatusApi.setWarningSystemStatus(
                'System Slow'
              );
            },
          },
          {
            menuType: 'User',
            label: 'Set Success',
            icon: {
              name: 'check',
            },
            onClick: (menuContext: ContextMenuContext) => {
              menuContext.adaptableApi.systemStatusApi.setSuccessSystemStatus(
                'System Fine'
              );
            },
          },
          {
            menuType: 'User',
            label: 'Set Info',
            icon: {
              name: 'info',
            },
            onClick: (menuContext: ContextMenuContext) => {
              menuContext.adaptableApi.systemStatusApi.setInfoSystemStatus(
                'Demos working fine'
              );
            },
          },
        ],
      };

      return [
        setSystemStatusMenuItem,
        '-',
        ...defaultAgGridMenuStructure,
        '-',
        ...defaultAdaptableMenuStructure,
      ];
    },
  },
  initialState: {
    Dashboard: {
      ModuleButtons: ['SystemStatus'],
      Tabs: [
        {
          Name: 'Messages',
          Toolbars: ['SystemStatus', 'SettingMessageButtons'],
        },
      ],
    },
    StatusBar: {
      StatusBars: [
        {
          Key: 'Center Panel',
          StatusBarPanels: ['SystemStatus'],
        },
      ],
    },
    Theme: {CurrentTheme: 'dark'},
    Layout: {
      CurrentLayout: 'Standard Layout',
      Layouts: [
        {
          TableColumns: [
            'name',
            'language',
            'github_stars',
            'license',
            'has_projects',
            'has_pages',
            'created_at',
            'has_wiki',
            'updated_at',
            'pushed_at',
            'github_watchers',
            'week_issue_change',
          ],
          Name: 'Standard Layout',
          AutoSizeColumns: true,
        },
      ],
    },
  },
};
```

## Sending Messages

Use **`adaptableApi.systemStatusApi`** (see [System Status API](https://www.adaptabletools.com/docs/technical-reference-system-status-message/index.md#system-status-api)):

| Method                                                       | Purpose                              |
| ------------------------------------------------------------ | ------------------------------------ |
| `setInfoSystemStatus(message, furtherInformation?)`          | Info status                          |
| `setSuccessSystemStatus(message, furtherInformation?)`       | Success status                       |
| `setWarningSystemStatus(message, furtherInformation?)`       | Warning status                       |
| `setErrorSystemStatus(message, furtherInformation?)`         | Error status                         |
| `setSystemStatus(message, messageType, furtherInformation?)` | Any `AdaptableMessageType`           |
| `getCurrentSystemStatusMessageInfo()`                        | Current message (if any)             |
| `deleteAllSystemStatusMessages()`                            | Clear session history                |
| `openSystemStatusSettingsPanel()`                            | Open Settings Panel on System Status |

Optional **`furtherInformation`** shows expandable detail in the Settings Panel history.

Alerts can also write to System Status when **`DisplaySystemStatusMessage`** is enabled on the Alert — see [Scheduled Alerts](https://www.adaptabletools.com/docs/handbook-alerting-schedule/index.md) and [Alerting](https://www.adaptabletools.com/docs/handbook-alerting/index.md).

## Storing Messages

By default AdapTable stores the 100 most recent System Status Messages in **session** state (in memory for the current grid session).

This is configurable via the `maxSystemMessagesInStore` property in [Notifications Options](https://www.adaptabletools.com/docs/technical-reference-notifications/index.md)

System Status Messages are <b>not</b> stored between sessions and are not part of persisted Adaptable State

### FAQ

**Can I choose where System Status messages are displayed?**
Yes. The System Status message will **always** display in the Toolbar and ToolPanel but additionally you can

- provide a Div (via the `systemStatusContainer` property in [Container Options](https://www.adaptabletools.com/docs/technical-reference-container/index.md)) where it will display
- set `showSystemStatusMessageNotifications` to _true_ in [Notifications Options](https://www.adaptabletools.com/docs/technical-reference-notifications/index.md) to also show a toast
- subscribe to the [System Status Message Displayed Event](https://www.adaptabletools.com/docs/technical-reference-system-status-message/index.md#system-status-message-displayed-event) and handle messages in custom UI

**Can Alerts post System Status messages?**
Yes. Set **`DisplaySystemStatusMessage`** on the Alert definition (or in Alert Properties in the wizard). [Team Sharing](https://www.adaptabletools.com/docs/handbook-team-sharing-active/index.md) can publish System Status when active shares update (`updateNotification: 'SystemStatus'`).

**Can I react in code when a message is shown?**
Subscribe to **`SystemStatusMessageDisplayed`** — see [System Status Message Displayed Event](https://www.adaptabletools.com/docs/technical-reference-system-status-message/index.md#system-status-message-displayed-event).
