Saving State

The localStorage api exists in JavaScript based custom checks, JavaScript custom actions 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 availabl in the different extensibility locations, when the data is available again differs between these use cases:

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