Services

Dynamic Cube Services must be enabled via a Service Factory. See the section on Configuring a Service Factory for more details on the overall approach.

Dynamic Dimension Service

This type of service is responsible for creating and refreshing a Dynamic Dimension. It should be returned by the Service Factory when an instance of type WsAssemblyServiceType.DynamicDimension is requested.

It must implement interface IWsasDynamicDimensionV800, which requires the following methods:

ReadDynamicDimensionContentTimestamp

Return Type: DateTime

This method returns a timestamp representing the last time the dimension has changed. If the system receives a timestamp more recent than the one associated with the last execution of ReadDynamicDimensionInfo, that method is executed again to rebuild the dimension.

ReadDynamicDimensionContentTimestamp will be executed at periodic intervals, as specified by the DynamicDimensionInfo object returned by ReadDynamicDimensionInfo. In addition, different application servers might execute it at different times, and it might be triggered by a number of internal events. For this reason, it is recommended to keep its execution time as short as possible (i.e. very simple logic, few or no I/O calls, etc), to avoid impacting system performance.

Note that individual application servers maintain their memory separately, so they might execute this method at different times, potentially returning different timestamps and hence letting users work with different hierarchies. Cache coordination can be implemented with custom logic between this method and ReadDynamicDimensionInfo.

Specific Arguments

api As IWsasDynamicDimensionApiV800 - see the related section

args As DynamicDimensionArgs - see the related section

ReadDynamicDimensionInfo

Return Type: DynamicDimensionInfo

This method is responsible for creating and returning the DynamicDimensionInfo object representing the generated Dimension. It will be executed the first time the dimension is requested; the resulting object will be kept in the application server memory until its timestamp is found older than the one returned by a call to ReadDynamicDimensionContentTimestamp, at which point it will be discarded and replaced with a new execution of this method.

Note that individual application servers maintain their memory separately, so they might execute this method at different times, potentially producing different hierarchies. Cache coordination can be implemented with custom logic between this method and ReadDynamicDimensionContentTimestamp.

Specific Arguments

api As IWsasDynamicDimensionApiV800 - see the related section

args As DynamicDimensionArgs - see the related section

Service-specific arguments

Api as IWsasDynamicDimensionApiV800

This object provides various utilities for building and maintaining dynamic dimensions.

Property	Type	Description
DbConnFW	DbConnInfo	Open connection to the Framework database
DbConnApp	DbConnInfo	Open connection to the Application database
BRGlobals	BRGlobals	In-memory store for basic data, which can be used to communicate between different methods of the same class as part of the execution flow. Note that its lifespan is short: as soon as a data request is fully satisfied (i.e. a dimension or dataunit has been created and returned), the object is destroyed.
Workspace	DashboardWorkspace	Reference to the Workspace containing the Assembly, including Text properties.

 

Methods

ReadDynamicDimensionInfo

Return Type: DynamicDimensionInfo

This method will build the entire hierarchy by executing an SQL query and mapping the resulting columns to member properties. It is not compulsory to use this function, but it is recommended whenever source member definitions are in SQL tables. Note that items can be further customized by manipulating the returned object.

Specific Arguments:

DateTime contentTimestamp

The Timestamp to associate with this execution. As long as it continues to be more recent than what returned by ReadDynamicDimensionContentTimestamp, the system will not refresh the dimension.

Int numSecondsBeforeReadingContentTimestamp

How often, in seconds, the server should call RadDynamicDimensionContentTimestamp to verify cache validityi

DbConnInfo dbConnExt

Open connection to the database where the query will be executed. Please consider creating it with a Using block, for safety.

string selectStatement

The SELECT statement to execute.
Note that WHERE and ORDER BY clauses should be omitted, and provided separately with their dedicated arguments listed below; this will allow for performance optimizations in the background.

List<DbWhere> dbWheres

WHERE clauses to be appended to the query, added to a List. For example a clause like "WHERE isEnabled = 'true' " should be expressed as:

Dim dbWheres as new List(Of DbWhere)dbWheres.Add(New DbWhere("isEnabled", DbOperator.IsEqualTo, "true")

List<DbOrderBy> dbOrderBys

ORDER BY clauses to be appended to the query, added to a List. Ordering records will influence the position of Members in the generated dimension.

For example, a clause like "ORDER BY Name ASC" should be expressed as:

Dim dbOrderBys As New List(Of DbOrderBy)dbOrderBys.Add(New DbOrderBy("Name", True))

string memberNameColumn

Name of the table field that contains member names.

string memberDescriptionColumn,

Name of the table field that contains member descriptions.

string externalMemberIdColumn,

Name of the table field that contains individual IDs for each member as present in the source system. OneStream will generate its own set of IDs, that will be automatically associated with the external ones in order to maintain a relationship with the source definitions.

string externalMemberNameColumn

name of the table field that contains member names as they appear in the source system. Note that it can be the same as memberNameColumn.

string parentMemberNameColumn

name of the table field that contains the names of the direct parent of a member. This will be used to build the hierarchy.

string parentExternalMemberIdColumn

name of the table field that contains the ID of the direct parent of a member, as it appears in the source system. If present, it will be used to build the hierarchy, taking precedence over parentMemberName and parentExternalMemberName.

string parentExternalMemberNameColumn

name of the table field that contains the name of the direct parent of a member, as it appears in the source system. If present, it will be used to build the hierarchy, taking precedence over parentMemberName.

string aggWeightColumn

name of the table field that will contain values to be used for the Aggregation Weight property of parent-child relationships.

bool aggWeightIsPercentageNotFraction

Boolean to specify whether the values found in aggWeightColumns are percentages (for example, 75) or fractions (for example, 0.75).

CreateAndAddDynamicMembers

This method can create several Dynamic Members starting from a source DataTable, adding them to a DynamicMemberCollection instance.    

Specific arguments

DataTable dataTable

The DataTable object containing member data.

string memberNameColumn

Name of the table field that contains member names.

string memberDescriptionColumn,

Name of the table field that contains member descriptions.

string externalMemberIdColumn,

Name of the table field that contains individual IDs for each member as present in the source system. OneStream will generate its own set of IDs, that will be automatically associated with the external ones in order to maintain a relationship with the source definitions.

string externalMemberNameColumn

name of the table field that contains member names as they appear in the source system. Note that it can be the same as memberNameColumn.

DynamicMemberCollection dynamicMembers

The collection object that will receive newly-created members.

CreateAndAddDynamicRelationships

This method can create several DynamicRelationships and add them to a DynamicRelationshipCollection object, starting from a DataTable that expresses such relationships. Note that any Dynamic Member involved must already exist in a DynamicMemberCollection object. See the sections on DynamicRelationship and DynamicRelationshipCollection for other details.

Specific arguments

DataTable dataTable

The datatable object containing relationship information.

DynamicMemberCollection dynamicMembers

The collection object containing all DynamicMembers referenced in the relationships. See the relevant section.

string memberNameColumn

Name of the table field that contains member names.

string externalMemberIdColumn,

Name of the table field that contains individual IDs for each member as present in the source system. OneStream will generate its own set of IDs, that will be automatically associated with the external ones in order to maintain a relationship with the source definitions.

string externalMemberNameColumn

name of the table field that contains member names as they appear in the source system. Note that it can be the same as memberNameColumn.

string parentMemberNameColumn

name of the table field that contains the names of the direct parent of a member. This will be used to build the hierarchy.

string parentExternalMemberIdColumn

name of the table field that contains the ID of the direct parent of a member, as it appears in the source system. If present, it will be used to build the hierarchy, taking precedence over parentMemberName and parentExternalMemberName.

string parentExternalMemberNameColumn

name of the table field that contains the name of the direct parent of a member, as it appears in the source system. If present, it will be used to build the hierarchy, taking precedence over parentMemberName.

string aggWeightColumn

name of the table field that will contain values to be used for the Aggregation Weight property of parent-child relationships.

bool aggWeightIsPercentageNotFraction

Boolean to specify whether the values found in aggWeightColumns are percentages (for example, 75) or fractions (for example, 0.75).

DynamicRelationshipCollection dynamicRelationships

The collection object that will receive newly-created relationships. See the relevant section.

Args as DynamicDimensionArgs

This object provides context-specific properties of the dimension.

Properties

• Dim: Dim

  • Description: Generic properties for the dimension, including source configuration. Name Value Pairs defined on the Dimension configuration can be found in its DimMemberSourceNVPairs property1.

• CachedDynamicDimensionInfo: DynamicDimensionInfo

  • Description: The dimension structure as it currently exists in cache. Note that this object can be null (for example, on first execution on a given appserver)

 

Dynamic Data Service

This service is responsible for creating and refreshing a Dynamic DataUnit for a Dynamic Cube. It should be returned by the Service Factory when an instance of type WsAssemblyServiceType.DynamicData is requested.

It must implement interface IWsasDynamicDataV800, which requires the following methods:

ReadDynamicDataUnitContentTimestamp

Return Type: DateTime

This method returns a timestamp representing the last time the dimension has changed. If the system receives a timestamp more recent than the one associated with the last execution of ReadDynamicDataUnitData, that method is executed again to rebuild the dimension.

ReadDynamicDataUnitContentTimestamp will be executed at periodic intervals, as specified by the DynamicDataUnitData object returned by ReadDynamicDataUnitData. In addition, different application servers might execute it at different times, and it might be triggered by a number of internal events. For this reason, it is recommended to keep its execution time as short as possible (i.e. very simple logic, few or no I/O calls, etc), to avoid impacting system performance.

Note that individual application servers maintain their memory separately, so they might execute this method at different times, potentially returning different timestamps and hence letting users work with different data. Cache coordination can be implemented with custom logic between this method and ReadDynamicDataUnitData.

Specific Arguments

api As FinanceRulesApi - see related section

dynamicDataBindingInfo As DynamicDataBindingInfo - see related section

ReadDynamicDataUnitData

Return Type: DynamicDataUnitData

This method is responsible for creating and returning the DynamicDataUnitData object representing the generated DataUnit. It will be executed the first time data is requested; the resulting object will be kept in the application server memory until its timestamp is found older than the one returned by a call to ReadDynamicDataUnitContentTimestamp, at which point it will be discarded and replaced with a new execution of this method.

Note that individual application servers maintain their memory separately, so they might execute this method at different times, potentially producing different data. Cache coordination can be implemented with custom logic between this method and ReadDynamicDataUnitContentTimestamp.

Specific Arguments

api As FinanceRulesApi - see related section

dynamicDataBindingInfo As DynamicDataBindingInfo - see related section

SaveDynamicDataCells

This method can be used to receive data entered by users through a Cube View or Form, and save it to a source system or table.

IMPORTANT: DO NOT WRITE INTO INTERNAL ONESTREAM TABLES. Always save data in custom tables or external systems.

Specific Arguments

cube As Cube

Object representing Cube information and configuration.

scenario As Member

The Scenario containing modified cells.

dynamicDataBindingInfo As DynamicDataBindingInfo

see related section

dataCellExs As List(Of DataCellEx)

List of datacells containing submitted data.

Service-specific arguments

api As FinanceRulesApi

This object contains methods and properties typically used in Finance Business Rules, see the generic API Guide for details.

IMPORTANT: although the object contains several "Set" methods to save data into cubes (api.Data.SetDataCell etc), they should NEVER be invoked in this service.

dynamicDataBindingInfo As DynamicDataBindingInfo

This object contains information related to the configuration of the dynamic cube. Note that this is also available in Hybrid Scenario rules. All properties are Read-Only.

Properties

• IsCubeNotScenarioDataBinding: Boolean

  • Indicates whether the binding is used in a Dynamic Data Service (True) or in a Hybrid Scenario Business Rule (False).

• DataBindingType: DynamicDataBindingType

  • Represents the value of the "Data Binding Type" property.

• SourceCubeOrScenarioOrBRName: String

  • Contains the value of the "Source Cube or Workspace Assembly" property for cubes, or the "Source Scenario or Workspace Assembly" property for scenarios.

• MemberFilters: String

  • Description: Holds the value of the "Member Filters" property.

• MemberFiltersToExclude: String

  • Value of property "Member Filters to Exclude"

• PreAggregatedMembers: String

  • Value of property "Pre-aggregated Members"

• EndYear: int

  • In Hybrid Scenario Business Rules, the last Year containing data retrieved from Source

• Options: String

  • Value of property "Options"

• OptionsNameValuePairs: IReadOnlyDictionary(Of String, String)

  • Value of property "Options", parsed as a collection of Name-Value Pairs