You can configure a Turnkey client timeout to stop an inactive Streaming client screen and show a page that does not keep the client’s active server resources; this is for Turnkey application administrators and ViewModel designers.

Why configure a client timeout?

A Streaming client, also called a Streaming app, is a client that uses the Turnkey Streaming API. While it is active, the Turnkey server keeps the objects required by that client in memory and maintains subscriptions so the client can respond to data changes. The standard AngularJS Client is one implementation of a Streaming client.

Use a timeout when an inactive user should leave the interactive Streaming screen instead of continuing to occupy its active server-side resources. For example, you can time out an order-entry ViewModel after 15 minutes without user interaction and show a non-interactive MVC timeout page.

Client timeout is one part of managing server memory. For the built-in pruning and other memory behavior, see Documentation:Memory optimization.

Timeout behavior

The timeout controls how long a client screen continues to show its user interface when there is no user interaction.

• The default is -1, which means no timeout is active.
• Set a timeout in minutes.
• You can set a server-wide default in TurnkeySettings.xml.
• You can override that default for one ViewModel with the TurnkeyTimeoutMinutes tagged value.
• A ViewModel-specific tagged value takes precedence over the server-wide setting.

Configuration location	Scope	When to use it
<TurnkeyTimeoutMinutes>...</TurnkeyTimeoutMinutes> in TurnkeySettings.xml	All pages, unless a ViewModel overrides it	You want one inactivity policy for the application.
TurnkeyTimeoutMinutes tagged value on a ViewModel	That ViewModel only	One screen needs a shorter or longer timeout than the application default.

Configure a server-wide timeout

Configure the server-wide value when all Turnkey pages should use the same timeout unless explicitly overridden.

1. Open TurnkeySettings.xml.
2. Add or update the TurnkeyTimeoutMinutes setting.
3. Set the value to the number of minutes the screen may remain without user interaction.

For example, this configuration sets a one-minute timeout for all pages that do not have their own ViewModel setting:

<TurnkeyTimeoutMinutes>1</TurnkeyTimeoutMinutes>

For the available Turnkey settings and their context, see Documentation:TurnkeySettings.

Override the timeout for one ViewModel

Configure the TurnkeyTimeoutMinutes tagged value on a ViewModel when that screen needs an exception to the server-wide policy.

For example, if the server-wide value is 15 minutes but a status screen should time out after 5 minutes, set the status screen ViewModel’s TurnkeyTimeoutMinutes tagged value to 5. The ViewModel value is used instead of the 15-minute server setting.

For the tagged-value setting, see Documentation:Span.TurnkeyTimeoutMinutes.

Choose the timeout page

Turnkey includes a basic Timedout page and uses it by default when a user exceeds the configured timeout.

You can replace that page with your own design:

1. Create a ViewModel named exactly Timedout.
2. Design the page users should see after their inactive screen times out. For example, include text that explains that the interactive session ended and provide the navigation appropriate for your application.
3. Ensure that the Timedout ViewModel is an MVC page. A custom timeout ViewModel works only when it is an MVC page.
4. Wait longer than the configured timeout on a target screen without user interaction, then verify that Turnkey displays the custom page.

The ViewModel name is significant: Turnkey uses a ViewModel called Timedout as the timeout page. For the focused requirements for that ViewModel, see Documentation:Timedout viewmodel.

Example configuration

Assume that most application screens may remain inactive for 20 minutes, while a data-entry ViewModel should close sooner.

1. Set the server-wide value in TurnkeySettings.xml:

<TurnkeyTimeoutMinutes>20</TurnkeyTimeoutMinutes>

1. On the data-entry ViewModel, set the TurnkeyTimeoutMinutes tagged value to 5.
2. Create an MVC ViewModel named Timedout if the built-in timeout page does not meet the application’s needs.

In this example, ordinary pages time out after 20 minutes without user interaction, while the data-entry ViewModel times out after 5 minutes.

Check before enabling the setting

• Do not expect a timeout when the value is -1; this is the default and disables the feature.
• Do not rely on the server-wide value for a ViewModel that has its own TurnkeyTimeoutMinutes tagged value; the ViewModel value wins.
• Do not create a custom Timedout ViewModel as a non-MVC page; it will not work as the timeout page.
• Review the effect on users who may leave unsaved work open. The timeout moves the user away from the interactive client screen.

See also

• Documentation:Streaming Client
• Documentation:TurnkeySettings
• Documentation:Span.TurnkeyTimeoutMinutes
• Documentation:Timedout viewmodel
• Documentation:Memory optimization