Dynamic Dashboard Management

This section provides best practices for WsDynamicItemState table. The WsDynamicItemState table stores state information for dynamically generated dashboard items to ensure correct synchronization across multiple servers. Using this table and the WsDynamicItemStateType enum correctly is essential for maintaining database performance and ensuring dashboard functionality.

Managing Database Table Growth from Dynamic Button IDs

In an Embedded Dynamic Repeater dashboard, items may be generated with unique IDs, for example Guid.NewGuid().ToString(). Because of the unique GUID, each button instance will be treated as a new item and every postback for each button creates a new record in the WsDynamicItemState table. This causes the WsDynamicItemState table to grow significantly.

Use the following code pattern to generate consistent, deterministic IDs and maintain database performance. This approach ensures records are updated on postback rather than created, and it ensures button names remain consistent across dashboard refreshes, reducing record growth.

var buttonID = btnModel.ItemName + "-" + btnModel.Order;

WsDynamicItemStateType Enum Reference

The WsDynamicItemStateType enum controls how much data is saved to the WsDynamicItemState table when a dynamic dashboard item is created.

IMPORTANT: Do not modify these IDs because their values are stored in the WsDynamicItemState table.

Review the following enum values:

Unknown (-1)

This enum is treated the same as MinimalWithTemplateParameters. Use this when you want standard behavior without specifying explicit behaviors.

NOTE: This is the recommended value for most dynamic dashboard operations.

NotUsed (0)

With this enum, nothing is saved to the WsDynamicItemState table. There is no database impact since no new rows are created. Use this enum in custom WsAssemblyService code where you are manipulating objects and intending to manually call SaveDynamicState later.

CAUTION: Do not use NotUsed for standard dynamic dashboard processing. If data is removed from the table, it will attempt to find records that were deleted, and this flag does not regenerate them. This will cause functionality to fail.

MinimalWithTemplateParameters (1000)

MinimalWithTemplateParameters is the default. This enum saves minimal item identification and template parameter data. It has a small storage size and only stores IDs, names, and parameter values. Use this enum for dashboard items created only by substituting template parameters. For example, substituting Color1 and Color2 for a color picker dashboard. When reconstructing, the system loads the base template from the database and applies the stored parameter values.

The following table details what data is saved with this enum reference:

The following example displays saved data:

ItemID: {new-guid}
ItemName: "MyDashboard_dynamic_Blue_5"
BasedOnID: {template-dashboard-guid}
BasedOnName: "MyDashboard"
TemplateParameterValues: "Color1=Blue|Color2=5"

EntireObject (2000)

This enum saves all metadata and serializes the complete object as JSON. This uses significant storage size. Each row can consume a kilobyte or more depending on the dashboard or the complexity of the component. Use this enum when dashboard item properties are modified directly, rather than populated through template parameter substitution. When reconstructed, the system deserializes the entire object from JSON.

Recommended API Usage

When calling methods to process dynamic dashboards, use WsDynamicItemStateType.Unknown, unless experiencing synchronization issues.

public WsDynamicAdapterCollection? GetDynamicAdaptersForDynamicComponent(
    SessionInfo si, 
    IWsasDynamicDashboardsApiV800 api, 
    DashboardWorkspace workspace,
    DashboardMaintUnit maintUnit, 
    WsDynamicComponentEx dynamicComponentEx, 
    Dictionary<string, string> customSubstVarsAlreadyResolved)
{
    try
    {
        if (api != null)
        {
            return api.GetDynamicAdaptersForDynamicComponent(
                si, 
                workspace, 
                dynamicComponentEx, 
                string.Empty, 
                null, 
                TriStateBool.Unknown, 
                WsDynamicItemStateType.Unknown);  // <-- Use Unknown
        }
        return null;
    }
    catch (Exception ex)
    {
        throw ErrorHandler.LogWrite(si, new XFException(si, ex));
    }
}

WsDynamicItemState Table Structure

The WsDynamicItemState table is used in both the Framework and Application databases.

NOTE: The table is automatically purged approximately every 30 days based on the SavedTimeTicks column. You can manually configure more aggressive cleanup routines through data management and extender rules. These tasks should be run outside of business hours.