API Reference

The following common arguments are accepted or made available by many functions.

Object Object Type Description
si SessionInfo Generic information about the current user session, including the type of client. See the API Overview Guide for details.
brGlobals BRGlobals Generic object to store and retrieve data between calls in the same execution thread.See the API Overview Guide for details.
args DashboardDataSetArgs, DashboardExtenderArgs, ExtenderArgs Run-specific context properties.
workspace DashboardWorkspace The Workspace containing the object that is being processed.
maintUnit DashboardMaintUnit The Maintenance Unit containing the object that is being processed.
dynamicDashboardEx WsDynamicDashboardEx The dashboard that is being processed.
dynamicComponentEx WsDynamicComponentEx The component that is being processed.
dynamicAdapterEx WsDynamicAdapterEx The adapter that is being processed.

customSubstVarsAlreadyResolved

 Dictionary (Of String, String) Populated dashboard Parameters.
nextLevelNameSuffixToAdd String In a Repeater configuration, this string is attached to the name of the original component to create the dynamic instance. For example, generated instances are called <originalName>_dynamic_<nextLevelNameSuffixToAdd>.
nextLevelTemplateSubstVarsToAdd Dictionary (Of String, String) In a Repeater configuration, this dictionary contains the Template Parameters available to repeated objects.
convertStoredComponentToDynamic TriStateBool To mark the original component as a dynamic version.
dynamicItemStateType WsDynamicItemStateType How an object is persisted when saving or replicating state across servers.

Service Factory

The Service Factory class must implement interface IWsAssemblyServiceFactory and contain the following CreateWsAssemblyServiceInstance method:

Copy
C# Code
 public IWsAssemblyServiceBase CreateWsAssemblyServiceInstance(SessionInfo si, BRGlobals brGlobals,
            DashboardWorkspace workspace, WsAssemblyServiceType wsAssemblyServiceType, string itemName)
Copy
VB.Net Code
Public Function CreateWsAssemblyServiceInstance(ByVal si As SessionInfo, ByVal globals As BRGlobals, ByVal workspace As DashboardWorkspace, ByVal wsasType As WsAssemblyServiceType, ByVal itemName As String) As IWsAssemblyServiceBase Implements IWsAssemblyServiceFactory.CreateWsAssemblyServiceInstance

The object returned must implement interface IWsAssemblyServiceBase. All supported service types inherit the IWsAssemblyServiceBase interface through their specific interfaces.

wsasType

The type of service that the Service Factory expects to provide. This is used to determine which Service object to return.

itemName

This contains the name of the invoked function if it is present. For example, a Data Set name or a Custom Calculation Function name.

Component Service

The Component Service responds to component-triggered actions in dashboards. It is similar to a feature found in traditional Dashboard Extenders, such as DashboardExtenderFunctionType.ComponentSelectionChanged.

It must implement interface IWsasComponentV800, which requires the following method:

Copy
C# Code
public XFSelectionChangedTaskResult ProcessComponentSelectionChanged(SessionInfo si, BRGlobals brGlobals, DashboardWorkspace workspace, DashboardExtenderArgs args)
Copy
VB.Net Code
Public Function ProcessComponentSelectionChanged(ByVal si As SessionInfo, ByVal globals As BRGlobals, ByVal workspace As DashboardWorkspace, _
            ByVal args As DashboardExtenderArgs) As XFSelectionChangedTaskResult Implements IWsasComponentV800.ProcessComponentSelectionChanged

Dashboard Service

The Dashboard Service responds to Dashboard-triggered actions. It is similar to a feature found in traditional Dashboard Extenders, for example DashboardExtenderFunctionType.LoadDashboard.

It must implement interface IWsasDashboardV800, which requires the following method:

Copy
C# Code
public XFLoadDashboardTaskResult ProcessLoadDashboardTask(SessionInfo si, BRGlobals brGlobals, DashboardWorkspace workspace, DashboardExtenderArgs args)
Copy
VB.Net Code
 Public Function ProcessLoadDashboardTask(ByVal si As SessionInfo, ByVal globals As BRGlobals, ByVal workspace As DashboardWorkspace, _
            ByVal args As DashboardExtenderArgs) As XFLoadDashboardTaskResult Implements IWsasDashboardV800.ProcessLoadDashboardTask

Data Management Step Service

The Data Management Step Service runs when invoked by a Data Management Step of an Execute Business Rule type. This is similar to a feature found in traditional Extensibility rules, for example ExtenderFunctionType.ExecuteDataMgmtBusinessRuleStep.

It must implement interface IWsasDataManagementStepV800, which requires the following method:

Copy
C# Code
public void ProcessDataManagementStep(SessionInfo si, BRGlobals brGlobals, DashboardWorkspace workspace, ExtenderArgs args)
Copy
VB.Net Code
 Public Sub ProcessDataManagementStep(ByVal si As SessionInfo, ByVal brGlobals As BRGlobals, ByVal workspace As DashboardWorkspace, _
            ByVal args As ExtenderArgs) Implements IWsasDataManagementStepV800.ProcessDataManagementStep

Data Set Service

The Data Set Service returns a Data Set or DataTable object, often to be processed by a Data Adapter or Bound List Parameter. It is similar to a feature found in traditional Dashboard Data Set rules, for example, DashboardDataSetFunctionType.GetDataSet.

It must implement interface IWsasDataSetV800, which requires the following method:

Copy
C# Code
 public object GetDataSet(SessionInfo si, BRGlobals brGlobals, DashboardWorkspace workspace, DashboardDataSetArgs args)
Copy
VB.Net Code
Public Function GetDataSet(ByVal si As SessionInfo, ByVal globals As BRGlobals, ByVal workspace As DashboardWorkspace, _
            ByVal args As DashboardDataSetArgs) As Object Implements IWsasDataSetV800.GetDataSet

Dynamic Grid Service

This service type feeds data to the Dynamic Grid Component. It implements interface IWsasDynamicGridV800, which has the following two methods:

This method is called whenever the dynamic grid requests data, such as on the initial page load.

Copy

C# Code

public XFDynamicGridGetDataResult GetDynamicGridData(SessionInfo si, BRGlobals brGlobals, DashboardWorkspace workspace, DashboardDynamicGridArgs args)
Copy

VB.Net Code

Public Function GetDynamicGridData(ByVal si As SessionInfo, ByVal brGlobals As BRGlobals, ByVal workspace As DashboardWorkspace, ByVal args As DashboardDynamicGridArgs) As XFDynamicGridGetDataResult Implements IWsasDynamicGridV800.GetDynamicGridData

DashboardDynamicGridArgs has everything needed to request data, such as start row index, page size, and column filters.

This method is called whenever the user clicks the Save button on the toolbar to save modified rows.

Copy

C# Code

public XFDynamicGridSaveDataResult SaveDynamicGridData(SessionInfo si, BRGlobals brGlobals, DashboardWorkspace workspace, DashboardDynamicGridArgs args)
Copy

VB.Net Code

Public Function SaveDynamicGridData(ByVal si As SessionInfo, ByVal brGlobals As BRGlobals, ByVal workspace As DashboardWorkspace, ByVal args As DashboardDynamicGridArgs) As XFDynamicGridSaveDataResult Implements IWsasDynamicGridV800.SaveDynamicGridData

The DashboardDynamicGridArgs has everything needed to save data, including a list of modified rows.

Dynamic Cube View Service

This service type enables you to manipulate Cube View formatting and data at runtime by modifying the CubeViewItem object. It must implement interface IWsasDynamicCubeViewV800, which requires the following method:

Copy

C# Code

public CubeViewItem GetDynamicCubeViewItem(SessionInfo si, IWsasDynamicCubeViewApiV800 api, DashboardWorkspace workspace, CubeViewItem cubeViewItem, DynamicCubeViewArgs args)
Copy

VB.Net Code

Public Function GetDynamicCubeViewItem(ByVal si As SessionInfo, ByVal api As IWsasDynamicCubeViewApiV800, ByVal workspace As DashboardWorkspace, _ ByVal cubeViewItem As CubeViewItem, ByVal args As DynamicCubeViewArgs) As CubeViewItem Implements IWsasDynamicCubeViewV800.GetDynamicCubeViewItem

Dynamic Dashboard Service

The Dynamic Dashboard Service is responsible for preprocessing dashboards at runtime. It provides several hooks to manipulate objects created by dashboards of an Embedded Dynamic Dashboard type or an Embedded Dynamic Repeater Dashboard type. For more information on general strategies, see Dynamic Dashboards

It must implement interface IWsasDynamicDashboardV800, which requires the following method:

Copy
C# Code
 public WsDynamicDashboardEx GetEmbeddedDynamicDashboard(SessionInfo si, IWsasDynamicDashboardsApiV800 api, DashboardWorkspace workspace, DashboardMaintUnit maintUnit,
            WsDynamicComponentEx parentDynamicComponentEx, Dashboard storedDashboard, Dictionary<string, string> customSubstVarsAlreadyResolved)
Copy
VB.Net Code
        Public Function GetEmbeddedDynamicDashboard(ByVal si As SessionInfo, ByVal api As IWsasDynamicDashboardsApiV800, ByVal workspace As DashboardWorkspace, _
            ByVal maintUnit As DashboardMaintUnit, ByVal parentDynamicComponentEx As WsDynamicComponentEx, ByVal storedDashboard As Dashboard, _
            ByVal customSubstVarsAlreadyResolved As Dictionary(Of String, String)) As WsDynamicDashboardEx Implements IWsasDynamicDashboardsV800.GetEmbeddedDynamicDashboard

This method returns an object representing a completed dashboard of an Embedded Dynamic Dashboard type or an Embedded Dynamic Repeater Dashboard type. Use this function to modify dashboard-specific properties, such as layout or data used by Repeaters. It is considered similar to the LoadDashboard approach of traditional Dashboard Extenders with these significant differences:

  • The method will always be triggered, regardless of embedded status.

  • The method will trigger before any other event is processed. For example, before LoadDashboard extenders would run.

  • The API allows for extensive access to Dashboard Properties.

parentDynamicComponentEx

The dashboard that will embed the dashboard generated by this function.

storedDashboard

The stored dashboard from which the function will generate a dynamic instance.

Implement the GetDynamicComponentsForDynamicDashboard method to modify any component property. This method returns a collection of dynamic components to use on an Embedded Dynamic Dashboard type or an Embedded Dynamic Repeater Dashboard type.

Copy
C# Code
public WsDynamicComponentCollection GetDynamicComponentsForDynamicDashboard(SessionInfo si, IWsasDynamicDashboardsApiV800 api, DashboardWorkspace workspace,
            DashboardMaintUnit maintUnit, WsDynamicDashboardEx dynamicDashboardEx, Dictionary<string, string> customSubstVarsAlreadyResolved)
Copy
VB.Net Code
Public Function GetDynamicComponentsForDynamicDashboard(ByVal si As SessionInfo, ByVal api As IWsasDynamicDashboardsApiV800, ByVal workspace As DashboardWorkspace, _
            ByVal maintUnit As DashboardMaintUnit, ByVal dynamicDashboardEx As WsDynamicDashboardEx, ByVal customSubstVarsAlreadyResolved As Dictionary(Of String, String)) _
            As WsDynamicComponentCollection Implements IWsasDynamicDashboardsV800.GetDynamicComponentsForDynamicDashboard

Implement the GetDynamicAdaptersForDynamicComponent method to modify any adapter. This method returns a collection of Data Adapters to use on an Embedded Dynamic Dashboard type or an Embedded Dynamic Repeater Dashboard type.

Copy
C# Code
  public WsDynamicAdapterCollection GetDynamicAdaptersForDynamicComponent(SessionInfo si, IWsasDynamicDashboardsApiV800 api, DashboardWorkspace workspace,
            DashboardMaintUnit maintUnit, WsDynamicComponentEx dynamicComponentEx, Dictionary<string, string> customSubstVarsAlreadyResolved)
Copy
VB.Net Code
    Public Function GetDynamicAdaptersForDynamicComponent(ByVal si As SessionInfo, ByVal api As IWsasDynamicDashboardsApiV800, ByVal workspace As DashboardWorkspace, _
            ByVal maintUnit As DashboardMaintUnit, ByVal dynamicComponentEx As WsDynamicComponentEx, ByVal customSubstVarsAlreadyResolved As Dictionary(Of String, String)) _
            As WsDynamicAdapterCollection Implements IWsasDynamicDashboardsV800.GetDynamicAdaptersForDynamicComponent

Implement the GetDynamicCubeViewForDynamicAdapter method to modify the Cube View configuration, for example, changing row filters. This method is used to return a Cube View that will be used by a Data Adapter on an Embedded Dynamic Dashboard type or an Embedded Dynamic Repeater Dashboard type.

storedCubeViewItem

The stored Cube View referenced by the Adapter configuration.

Copy
C# Code
  public WsDynamicCubeViewEx GetDynamicCubeViewForDynamicAdapter(SessionInfo si, IWsasDynamicDashboardsApiV800 api, DashboardWorkspace workspace,
            DashboardMaintUnit maintUnit, WsDynamicAdapterEx dynamicAdapterEx, CubeViewItem storedCubeViewItem, Dictionary<string, string> customSubstVarsAlreadyResolved)
Copy
VB.Net Code
    Public Function GetDynamicCubeViewForDynamicAdapter(ByVal si As SessionInfo, ByVal api As IWsasDynamicDashboardsApiV800, ByVal workspace As DashboardWorkspace, _
            ByVal maintUnit As DashboardMaintUnit, ByVal dynamicAdapterEx As WsDynamicAdapterEx, ByVal storedCubeViewItem As CubeViewItem, _
            ByVal customSubstVarsAlreadyResolved As Dictionary(Of String, String)) As WsDynamicCubeViewEx Implements IWsasDynamicDashboardsV800.GetDynamicCubeViewForDynamicAdapter

Implement the GetDynamicParametersForDynamicComponent method to modify the configuration or state of any Parameter referenced by components or by the dashboard itself. This method returns a collection of Parameter instances used on an Embedded Dynamic Dashboard type or an Embedded Dynamic Repeater Dashboard type.

Copy
C# Code
  public WsDynamicParameterCollection GetDynamicParametersForDynamicComponent(SessionInfo si, IWsasDynamicDashboardsApiV800 api, DashboardWorkspace workspace,
            DashboardMaintUnit maintUnit, WsDynamicComponentEx dynamicComponentEx, Dictionary<string, string> customSubstVarsAlreadyResolved)
Copy
VB.Net Code
  Public Function GetDynamicParametersForDynamicComponent(ByVal si As SessionInfo, ByVal api As IWsasDynamicDashboardsApiV800, ByVal workspace As DashboardWorkspace, _
            ByVal maintUnit As DashboardMaintUnit, ByVal dynamicComponentEx As WsDynamicComponentEx, ByVal customSubstVarsAlreadyResolved As Dictionary(Of String, String)) _
            As WsDynamicParameterCollection Implements IWsasDynamicDashboardsV800.GetDynamicParametersForDynamicComponent

Implement the GetDynamicCubeViewForDynamicComponent method to modify the WsDynamicCubeViewEx that is returned as part of the Dynamic Dashboard creation.

Copy

C# Code

   WsDynamicCubeViewEx GetDynamicCubeViewForDynamicComponent(SessionInfo si, IWsasDynamicDashboardsApiV800 api, DashboardWorkspace workspace, DashboardMaintUnit maintUnit,
            WsDynamicComponentEx dynamicComponentEx, CubeViewItem storedCubeViewItem, Dictionary<string, string> customSubstVarsAlreadyResolved)
Copy

VB.Net Code

Public Function GetDynamicCubeViewForDynamicComponent(ByVal si As SessionInfo, ByVal api As IWsasDynamicDashboardsApiV800, ByVal workspace As DashboardWorkspace, _
            ByVal maintUnit As DashboardMaintUnit, ByVal dynamicComponentEx As WsDynamicComponentEx, ByVal storedCubeViewItem As CubeViewItem, _
            ByVal customSubstVarsAlreadyResolved As Dictionary(Of String, String)) As WsDynamicCubeViewEx Implements IWsasDynamicDashboardsV800.GetDynamicCubeViewForDynamicComponent

IWsasDynamicDashboardsApiV800

Dynamic Dashboard Services make an API instance of the IWsasDynamicDashboardsApiV800 interface available to their methods. This object has several methods and properties.

Property Name Type Notes
DbConnFW DbConnInfo Open connection to the Framework database. Use this to avoid opening a new connection.
DbConnAppOrFW DbConnInfo Open connection to the Application database or the Framework database, depending on which dashboard it is run in. Use this to avoid opening a new connection.
IsSystemLevel Boolean Whether this code is being run as part of a System dashboard.
BRGlobals BRGlobals Can be used to cache data between runs.

These are the main types of methods provided by this API object:

GetDynamic*/GetEmbedded*

This is used to load in one or more dynamic instances, typically to modify them.

SaveDynamic*State

This is used to save the state of a particular element.

GetStored*

This is used to load in the configuration of specific elements, typically to modify them.

GetDynamic*/GetEmbedded* Functions

The call provided in the following example will load in memory any instance of the specified storedDashboard dashboard, typically so that some of its properties or components can be modified. convertStoredDashboardToDynamic will determine whether the resulting dashboard should be considered dynamic. This will impact available properties and further running of Services.

Copy
C# Code
WsDynamicDashboardEx GetEmbeddedDynamicDashboard(SessionInfo si, DashboardWorkspace workspace, WsDynamicComponentEx parentDynamicComponentEx, Dashboard storedDashboard, string nextLevelNameSuffixToAdd, Dictionary<string, string> nextLevelTemplateSubstVarsToAdd, TriStateBool convertStoredDashboardToDynamic, WsDynamicItemStateType dynamicItemStateType);

The call provided in the following example will load in memory the collection of Component instances necessary to display the dashboard. convertStoredComponentsToDynamic will determine whether the resulting instances should be considered Dynamic. This will impact available properties and further running of Services.

Copy

C# Code

WsDynamicComponentCollection GetDynamicComponentsForDynamicDashboard(SessionInfo si, DashboardWorkspace workspace, WsDynamicDashboardEx dynamicDashboardEx, string nextLevelNameSuffixToAdd, Dictionary<string, string> nextLevelTemplateSubstVarsToAdd, TriStateBool convertStoredComponentsToDynamic, WsDynamicItemStateType dynamicItemStateType);

The call provided in the following example will generate all repeated dashboards and components necessary to display a Dynamic Repeater dashboard. repeatArgsList is a list containing instances of type WsDynamicComponentRepeatArgs. This is a representation of key value pairs that should be used for each iteration. See Service-based Dynamic Repeater.

Copy

C# Code

WsDynamicComponentCollection GetDynamicComponentsRepeatedForDynamicDashboard( SessionInfo si, DashboardWorkspace workspace, WsDynamicDashboardEx dynamicDashboardEx, List<WsDynamicComponentRepeatArgs> repeatArgsList, TriStateBool convertStoredComponentsToDynamic, WsDynamicItemStateType dynamicItemStateType);

The call provided in the following example will load in memory an instance of the specified storedComponent Component. This is typically so that some of its properties or components can be modified. convertStoredComponentToDynamic will determine whether the resulting instances should be considered Dynamic. This will impact available properties.

Copy

C# Code

WsDynamicComponentEx GetDynamicComponentForDynamicDashboard(SessionInfo si, DashboardWorkspace workspace, WsDynamicDashboardEx dynamicDashboardEx, DashboardComponent storedComponent, string nextLevelNameSuffixToAdd, Dictionary<string, string> nextLevelTemplateSubstVarsToAdd, TriStateBool convertStoredComponentToDynamic, WsDynamicItemStateType dynamicItemStateType);

The call provided in the following example will load in memory a collection of Data Adapters necessary to display the specified component instances.

Copy

C# Code

WsDynamicAdapterCollection GetDynamicAdaptersForDynamicComponent(SessionInfo si, DashboardWorkspace workspace, WsDynamicComponentEx dynamicComponentEx, string nextLevelNameSuffixToAdd, Dictionary<string, string> nextLevelTemplateSubstVarsToAdd, TriStateBool convertStoredAdaptersToDynamic, WsDynamicItemStateType dynamicItemStateType);

The call provided in the following example will load in memory a single Data Adapter necessary to display a component. storedAdapter must be the source Adapter configuration.

Copy

C# Code

WsDynamicAdapterEx GetDynamicAdapterForDynamicComponent(SessionInfo si, DashboardWorkspace workspace, WsDynamicComponentEx dynamicComponentEx, DashboardAdapter storedAdapter, string nextLevelNameSuffixToAdd, Dictionary<string, string> nextLevelTemplateSubstVarsToAdd, TriStateBool convertStoredAdapterToDynamic, WsDynamicItemStateType dynamicItemStateType);

The call provided in the following example will load in memory a single Cube View, which will be used to provide records for a Data Adapter. dynamicAdapterEx is the source Adapter configuration. storedCubeViewItem is the source Cube View configuration.

Copy

C# Code

WsDynamicCubeViewEx GetDynamicCubeViewForDynamicAdapter(SessionInfo si, DashboardWorkspace workspace, WsDynamicAdapterEx dynamicAdapterEx, CubeViewItem storedCubeViewItem, string nextLevelNameSuffixToAdd, Dictionary<string, string> nextLevelTemplateSubstVarsToAdd, TriStateBool convertStoredCubeViewToDynamic, WsDynamicItemStateType dynamicItemStateType);

The call provided in the following example will load in memory a collection of Parameter instances necessary to display the provided component.

Copy

C# Code

WsDynamicParameterCollection GetDynamicParametersForDynamicComponent(SessionInfo si, DashboardWorkspace workspace, WsDynamicComponentEx dynamicComponentEx, string nextLevelNameSuffixToAdd, Dictionary<string, string> nextLevelTemplateSubstVarsToAdd, TriStateBool convertStoredParametersToDynamic, WsDynamicItemStateType dynamicItemStateType);

GetStored* Functions

  • List<DashboardDbrdCompMemberEx> GetStoredComponentsForDynamicDashboard(SessionInfo si, DashboardWorkspace workspace, WsDynamicDashboard dynamicDashboard);

  • DashboardDbrdCompMemberEx GetStoredComponentForDynamicDashboard(SessionInfo si, DashboardWorkspace workspace, WsDynamicDashboard dynamicDashboard, string componentName);

  • DashboardDbrdCompMemberEx GetStoredComponentForDynamicDashboard(SessionInfo si, DashboardWorkspace workspace, WsDynamicDashboard dynamicDashboard, Guid componentID);

Save*State Functions

  • void SaveDynamicDashboardState(SessionInfo si, WsDynamicComponent parentComponent, WsDynamicDashboardEx dynamicDashboardEx, WsDynamicItemStateType dynamicItemStateType);

  • void SaveDynamicComponentState(SessionInfo si, WsDynamicDashboard parentDashboard, WsDynamicComponentEx dynamicComponentEx, WsDynamicItemStateType dynamicItemStateType);

  • void SaveDynamicAdapterState(SessionInfo si, WsDynamicComponent parentComponent, WsDynamicAdapterEx dynamicAdapterEx, WsDynamicItemStateType dynamicItemStateType);