# Saving State

The localStorage api exists in JavaScript based custom checks and within Script based output channels with the same methods. This API allows you to save values to influence future executions.

While the API is available in the different extensibility locations, when the data is available again differs between these use cases:

- JavaScript based custom checks

  Any saved values exist for future executions of this check on the same monitored object.

- Script Based Notification Channels

  Any saved values exist only for future calls to the same Notification action for the same check/system.

## Code Walkthrough

The API offers two methods to save and retrieve values using the global object localStorage.

The object itself behaves as a regular JavaScript object and allows you to query values directly:

    if (localStorage.mySavedValue) {
        // ... we've done this before

    } else {
        // ... this is the first time
    }

    // After the logic completes, save the state
    localStorage.mySavedValue = "12345";
    localStorage.otherValue = true;

| There is a limitation that the property name cannot be one of `setItem`, `getItem`, `removeItem` or `item` due to a confusion with the other API. For example, `localStorage.getItem = 1234` will not do the correct thing.

Additionally, you can use the methods getItem(..), setItem(..) and removeItem(..) to get, set and remove a thing from storage respectively.

For example, this does the same thing as the last example:

    if (localStorage.getItem("mySavedValue")) {
        // ... we've done this before

    } else {
        // ... this is the first time
    }

    // After the logic completes, save the state
    localStorage.setItem("mySavedValue", "12345");
    localStorage.setItem("otherValue", true);

| It is advisable to only store "primitive" values in local storage to ensure that they are saved properly and available the next time. For example, only store text strings, numbers, boolean values etc. and do not store things such as JavaScript date objects directly. Rather convert these to a raw format first. For dates use `new Date().valueOf()` and for JSON objects use `JSON.stringify(..)` to save and 'JSON.parse(..)' to restore.

## API Reference

### Global Variable localStorage

LocalStorage is a method to persist data/state between different messages sent and allows you to create custom business logic depending on what had happened before.

The localStorage data for checks exists only for the check id (specific to a certain system) so that data for other systems does not complicate the logic.

The localStorage data for notifications exists only for the combination of action and check id so that messages for other systems do not complicate the logic.

When using LocalStorage to save data, it is necessary to save primitive values and not objects. For example store numbers, text/strings and booleans and for dates, covert them to numeric values (e.g. `new Date().valueOf()`) rather than storing the date object itself.

    if (localStorage.mySavedValue) {
        // ... we've done this before

    } else {
        // ... this is the first time
    }

    // After the logic completes, save the state
    localStorage.mySavedValue = "12345";
    localStorage.otherValue = true;

Alternatively you can use the setItem, getItem, removeItem methods of this class to manipulate the data.

#### getItem(..)

    getItem(key: string): any

Find and return an item from local storage. Returns null if not found.

Parameters

  - `key`: string

    the key of the item to return

Returns

  any

  the stored item or null if not found

#### getItem(..)

    getItem(key: string, defaultValue: any): any

Find and return an item from local storage. Returns the default value if not found.

Parameters

  - `key`: string

    the key of the item to return

  - `defaultValue`: any

    the value to return if not found

Returns

  any

  the stored item or null if not found

#### removeItem(..)

    removeItem(key: string): boolean

Remove an item from storage, so it is no longer saved.

Parameters

  - `key`: string

    the key of the item to remove

Returns

  boolean

  true if the item was removed

#### setItem(..)

    setItem(key: string, value: any): void

Add an item to the store to persist to the next execution.

Parameters

  - `key`: string

    the key of the item to allow retrieval again

  - `value`: any

    the value/object to store