Menu Component in Practice
If you create the new Menu Component in your Maintenance Unit, you will quickly notice that it has very few properties. That's because its configuration will actually come from an attached Data Adapter, which must produce a set of tables containing all menu items and their configuration. The format of such tables has to be somewhat precise, matching what the component expects. For this reason, the best way to produce them (at least while you familiarize yourself with this mechanism) is to create a Dashboard DataSet using a couple of utility classes built for this specific task. The first thing we will do, in our rule, is to create an XFMenuItemCollection object. This represents our menu, which we will populate with items and eventually return (as a DataSet) at the end of the function. Public Function Main(ByVal si As SessionInfo, ByVal globals As BRGlobals, ByVal api As Object, ByVal args As DashboardDataSetArgs) As Object Try Select Case args.FunctionType Case Is = DashboardDataSetFunctionType.GetDataSet If args.DataSetName.XFEqualsIgnoreCase("MainMenu") Then ' create the menu object Dim menu As New XFMenuItemCollection() Menu items will be created by instantiating objects of type XFMenuItem. These objects will hold all the configuration properties for the item, including the font and colors that it will use. There are a few different constructors you can use, to specify all sorts of properties; the one used here is the shortest one! ' create top-level item ' XFMenuItem(string uniqueName, string headerText, string foreground, string background, bool isBold, bool isItalic, bool isEnabled, bool isSeparator, string parameterValue) Dim parentMenuItemOne As New XFMenuItem("1", "Parent", _ "White", "SlateGray", False, False, True, False, Nothing) ' create items for the second level Dim childMenuItemOne As New XFMenuItem("1.1", "Child 1", _ "Black", "White", True, True, True, False, Nothing) Dim childMenuItemTwo As New XFMenuItem("1.2", "Child 2", _ "Black", "White", True, True, True, False, Nothing) ' create item for the third level Dim grandChildMenuItemOne As New XFMenuItem("1.1.1", "Grandchild 1", _ "White", "SlateGray", True, True, True, False, Nothing) Most of the properties are self-explanatory, but you might wonder what "parameterValue" is. That's the value that will be pushed into the Bound Parameter specified on the actual component later on, so that Actions or other components can pick it up. We will come back to this later. Now we need to define the relationships between items. We do that by manipulating the .Children property of each parent item, which must be a list containing the children (duh!) items. ' create the hierarchy by adding children to direct parents as a List ' attach 1.1.1 as a child of 1.1 childMenuItemOne.Children = New List(Of XFMenuItem) From {grandChildMenuItemOne} ' attach 1.1 as a child of 1 parentMenuItemOne.Children = New List(Of XFMenuItem) From {childMenuItemOne} ' you can also manipulate the list once created. ' attach 1.2 as a child of 1 parentMenuItemOne.Children.Add(childMenuItemTwo) In a similar way, top-level items are added to the list contained in the .MenuItems property of our XFMenuItemCollection instance. ' add item 1 as a top-level members of the menu menu.MenuItems.Add(parentMenuItemOne) Before we return the resulting menu, if you are dealing with dynamically-generated structures with a lot of members, you might want to perform a safety check and purge extra members: While menu.IsAboveMaxMenuItemLimit(si) menu.MenuItems.RemoveAt(menu.MenuItems.Count - 1) End While Last, we use the .CreateDataSet method of our menu object to return the DataSet. ' generate the dataset and return it Return menu.CreateDataSet(si) Now that we have the rule, we can create a DataAdapter to execute it. Notice how, when testing it, it produces two tables: one with item properties, and one with their relationships. Now that we have an Adapter, we can create the Menu Component and attach the Adapter to it. You can then assign it to a Dashboard and preview it, after you save it. This is fun but a bit pointless! We want menus so that the user will actually choose something and we'll get the result of that choice. In order to do that, we need to specify the Bound Parameter. Whenever the user selects an item, the "parameterValue" associated with that item will be pushed into the specified Parameter; we can then reference that Parameter in an Action or extender rule, to trigger something like navigating to a website. Note that the Parameter doesn't need to exist! OneStream will just create one for you in the background. Then we place an Action on our Component, referring to the Parameter. The last step is to go back to our rule and specify a different parameterValue for "leaf" items, so that the Parameter will contain something. Dim childMenuItemTwo As New XFMenuItem("1.2", "Main Page", _ "Black", "White", True, True, True, False, "https://www.onestream.com") ' create item for the third level Dim grandChildMenuItemOne As New XFMenuItem("1.1.1", "OneCommunity", _ "White", "SlateGray", True, True, True, False, "https://community.onestreamsoftware.com") Et voilà! You can now execute the Dashboard and verify that it works!
Map Component Tutorial
So you’ve bought the OneStream Advanced Reporting and Dashboards book - congratulations on being on your way to mastering these tools! The book is chocked full of examples and guidance on how to tailor your user experience, but here’s something extra – a tutorial on how to use Map Components in your application. We’ll walk through setting up a Dashboard with an interactive map to provide users with a visual display of locations, from collecting coordinates to displaying locations that are click-enabled to display relevant data.Meeting Notes: EMEA Technical User Group
This past week we held our first Virtual EMEA Technical User Group with some great attendees from across our customer-base in EMEA. We had a few speakers from OneStream who spoke on performance- and security-related topics, which I have summarized below, and attached their presentations to this post. You can also watch the replay recording here. Thanks again to all those in attendance, and we look forward to holding these regularly. Stay tuned for more information to come! Performance session Aymar gave a presentation on performance, focusing on tips and tricks to avoid common pitfalls in application design and performance optimization. They discussed the importance of data units, how to keep them small, and the impact of consolidation on data unit size. They also shared best practices for data quality, importing, and calculation optimization. Albert provided insights on building efficient dashboards and running cube views, including filtering data at the source and using session data tables. Security session Terry covered security approaches for entities, workflows, and user dimensions, emphasizing the importance of naming conventions, child groups, and balancing maintenance, user experience, and data governance. Follow-up and Important Info Make sure to visit the OneStream Community and IdeaStream for interacting with OneStream and the broader developer community, and to submit ideas and feedback. We are planning an in-person developer activity/happy hour in London the week of March 24. Stay tuned for more info. Splash North America is happening in Nashville on May 13-15, 2025, and registration is open now! Splash EMEA is happening in London on October 13-15, 2025, and registration will open up in March!
OneStream 8.4/5 New features
Since version 8.4, OneStream has introduced an updated look and feel, with a new logo and a transition from blue to black as the main color. In this post, we focus on the following new features: Working with parameters in spreadsheets/Excel add-in Send links to dashboards to colleagues using Smart Links Make your dashboards more interactive with the new Menu component Use richly formatted text boxes to inform your users in dashboards. 1. Parameters in Excel With the latest release of OneStream, you can add more flexibility to your Excel reports. Using the menu option Parameters, workspace parameters can be linked to a cell. This cell displays a dropdown menu with the options of the parameter. For each parameter, the user can choose whether it relates to the current workspace or the entire workspace: In addition, In-Sheet Actions can be added, allowing you to run a Data Management Sequence directly from your Excel sheet, for example, to seeding or calculating data. 2. Smart Links Ithappens to all of us: you send a colleague an email asking them to look at a strange number in a dashboard, and after countless back-and-forth emails, it turns out that they are seeing a different representation of the data due to other selected parameters. OneStream has now introduced Smart Links, which allow the administrator to create predefined links with fixed parameters. These links can be created via a button and forwarded to a colleague. This opens the exact same dashboard, with the appropriate filters and parameters. The button can even generate a mailto:-link, so that an e-mail containing the link is created directly from the dashboard. The user is directed to the dashboard through the Web environment and must first log in if no active session is available. A Smart Link is created from a business rule, which since version 8 can be stored in an assembly within the workspace itself. On the button, it is activated via: Our assembly is called Assembly85. The CreateSmartlink function in the SolutionHelper looks like this: (In the above example, all values are hardcoded, but they can be made dynamic if needed). 3. Menu One of the newest additions to the dashboard components is the Menu. This menu can be created dynamically via a business rule, similar to a Tree View component. The menu is associated with a parameter that can be used in the dashboard to refresh other embedded dashboards or components. You can extensively format the menu with fonts, text and background colors and even logos. Unique to the menu are two options: Auto Open: The menu expands automatically when a user moves over it. If this option is set to false, the menu must be clicked on first. Show Down Arrow: Highlights menu options that can be expanded by displaying a down arrow. The menu uses a data adapter associated with a Dashboard DataSet business rule (in our case, within the assembly). The rule for our menu is as follows: First, the main level menu items are created as new XFMenuItems with their properties. Then the underlying and subitems are created, also as XFMenuItems. Finally, the items are linked as parent-child items, after which the menu is returned. 4. Rich formatted text boxes Text box components now have the propertion Allow Rich Text (and even Enable Spell Check), as shown below: Many things are possible, but the text must be entered via the text box. In our usage scenario, we want to use the richly formatted text as user instructions for the selected dashboard. However, the challenge with the defaults is that a user can change the text or the text is user-specific (via an Input Value parameter). Manually adding the text in a Literal parameter(and setting the text box as read-only) is also a challenge because the text is not HTML-formatted, for example. Below is an example of the stored text for the "type some text" above: A total of 33 lines! Full of letters and numbers. What we have done is to create two text boxes. The first text box is linked to an Input Value parameter where the administrator can enter the text in the desired format. The second text box is associated with a Literal parameter with the IsReadOnly property set to true. Next, we created a small business rule linked to a button that copies the value of the first parameter to the second. The fixed text box can then be used in the dashboard presented to your users. Wrap Up What version of OneStream are you currently using? Are you considering an upgrade to the latest version or want to discover how these new features can enhance your OneStream application? Feel free to contact me. I always make sure to keep up to date with the latest features and releases, so don't hesitate to get in touch to learn more about these or other enhancements to OneStream!Enriching Embedded Dashboards with Custom Controls
This is an introduction to Custom Controls in OneStream Workspaces. In this blog we will walk you through a simple (almost) No-Code example, creating a Custom Control dashboard with an embedded Button component. Custom Control is a new Dashboard Type that enriches what you can do with an Embedded Dashboard in terms of OneStream Dashboard wizardry. It was released in conjunction with Dynamic Dashboards in v8+ (see my previous blog on this concept here) but uses a different approach to solve for a different type of use case. Custom Controls are much more about taking an existing dashboard template (our Custom Control Dashboard) that contains embedded elements and then repurposing it to behave differently by embedding the embedded version of this Custom Control Dashboard into a new Dashboard and using something called Event Listeners to control that component / or components differently, when each independent instance of that embedded Custom Control Dashboard is invoked inside a new Dashboard. This means that Dashboard Templates can be repurposed in different ways, without always recreating the same Dashboards and components for each slightly different use case. Think of this a bit like the old trick to create a custom Embedded Dashboard and pass a parameter value in to it, to render different Dashboard content based on User Selection e.g. But with a much more sophisticated layer of control over the actions performed by your Dashboard Components that reside in your Custom Control Dashboard template. Now let's look at the setup. Setup: Dashboards This example has been created in its own Workspace called WsCustomControl. Let's start by looking at the Custom Control Dashboard. Here we have set the Dashboard Type as Custom Control and selected Layout Type Vertical Stack Panel. Inside this Custom Control Dashboard we have our Button component. When we review the Button itself, we can see that we have to set the Navigation options as below e.g. Selection Changed Navigation Action is Forward Custom Control To Parent Event Listener and the Selection Changed Navigation Arguments must include the EventListenerName Key in the KeyValuePair passed in to the arguments. Hint: If you hover over the Selection Changed Navigation Arguments. You receive some guidance on this (see below). The ButtonEventLister value (it could be called anything) we pass in to EventListenerName KeyValuePair will be explained in the next steps. Let's run the Custom Control Dashboard to see what it looks like, before we dive into the setup. So a simple button, that performs no actions. Since we haven't configured the Button component to perform an action, only to forward a Custom Control Event. Dashboard Button Action 1: Open Dialog Setup So the first example of using an Embedded Custom Control Dashboard, we want our button to perform the action of opening another Dashboard as a Dialog. So let's review that Dialog first before we review the Button itself (in the Custom Control Dashboard) in more detail. In this Dashboard is a Label and a Supplied Parameter (to handle the parameter handshake from Button to Label via Dialog). Let's look at the Label next. Here you can see that we pass in a parameter called |!prm_Label!| Now, let's review the button again. This time observe the Bound Parameter called prm_Button and the Parameter Value for Button Click. Also, please observe that here is where we pass in our Key Value Pair value ButtonEventListener that we saw earlier to the EventListenerName key e.g. EventListenerName=ButtonEventListener. So when do we get to open the Dialog? I hear you ask.... Well we needed some context before we step into the Embedded Dashboard setup. We start with the Dashboard we are launching using our Embedded Custom Control Dashboard template. Here we have added the Embedded version of the Dashboard that we have created. So far, pretty standard right? A Uniform dashboard with an Embedded Dashboard; albeit we don't normally add the Embedded version of a Dashboard to itself... But, let's now have a look at the Embedded Dashboard itself. Dashboard Button Action 1: Open Dialog Logic There are a couple of things to observe here before we get to the Collection. The Embedded Dashboard property is set to pick up our Custom Control Dashboard e.g. CustomControl_Button. Each fresh instance of the Custom Control Dashboard template must have a unique instance name e.g. CustomControl_Button1, CustomControl_Button2, etc. Now let's look at the Event Listeners Collection for this embedded Dashboard. Here we can see this is where we name our Event Listener e.g. ButtonEventListener. We also pass the value from our Button parameter (prm_Button) to our Label parameter (prm_Label) in the Map Bound Parameters property e.g. prm_Label=prm_Button. Remember these from earlier? Finally we set the Button component action to (a) Open Dialog and (b) to open the Dialog we had created earlier with our Label embedded in it e.g. dlg_CustomControl. This means that we are invoking the Button action in the Embedded Dashboard itself by using the Embedded Custom Control Dashboard and changing the action for this instance of the template. This means that when we open our new Dashboard (that uses this Embedded Dashboard), it creates a fresh instance of our Embedded Custom Control Dashboard, where the Button component now opens a Dialog based on our Event Listener logic e.g. Observe, The Label in the Dialog is now displaying the Parameter Value For Button Click value from the Button itself. Next we are going to look at another example of making this Custom Control Dashboard perform a different action. This time it will return a Message to the Dashboard via a Dashboard Extender Business Rule. Dashboard Button Action 2: Return Message to Dashboard Setup So to execute a Dashboard Extender (or Component Service), we first need an Assembly (mine is called Code) to be created in our Workspace (or we can use traditional Business Rules) and then some logic. You'll see how simple this example is below. All we are doing is executing a Dashboard Extender Business Rule to return a Message Box with a custom Message using the XFSelectionChangedTaskResult object e.g. "Event Listener Message Example" Dashboard Button Action 2: Return Message to Dashboard Logic Now we understand how to setup the Embedded Custom Control Dashboard, let's review our second example using the same Custom Control Dashboard template as before. Here we have a new Dashboard, again that is embedded to itself (the same setup as before), but this time we create a different instance of the Embedded Custom Control Dashboard. So let's look at the Embedded Dashboard, again we have set the Embedded Dashboard to look at our Custom Control Dashboard e.g. CustomControl_Button. But we have also given the Embedded Custom Control Dashboard a unique Instance Name e.g. CustomControl_Button2. Now, if we review the Event Listeners Collection in this example, we can see that we are using the same EventListenerName e.g. ButtonEventListener, but this time we have updated the Selection Changed Server Task property to Execute a Dashboard Extender Business Rule and then set the Selection Changed Server Task Arguments to execute our Dashboard Extender Business Rule and Function, which will return a Message Box Dialog to the Dashboard. So let's have a look at this in action. This time when we click the Button from our fresh instance of the same Custom Control Dashboard, it performs the action to return a Message Box that contains the Message from our Dashboard Extender Business Rule instead. So we can make a Component perform a completely different action for each instance by using the same Custom Control Dashboard as a template. Conclusion Now that you have a better understanding of some of these concepts, we can see a lot of new possibilities for reusing Dashboards and Components based on a templated approach and for varying use cases. Once you understand how to harness Custom Controls and combine these techniques with Dynamic Dashboards or even traditional Dashboard techniques, you will have the capability to make more strategic design decisions in your Workspace Development, that simply were not possible before Workspaces and hopefully more creativity and fun on your Dashboard development journey.Building BiBlend table names, or: a classic tale of XFBR escapology
Tables produced by BiBlend are named with a simple convention, which makes it easy to build dynamic DataAdapters to report on them; however, day-to-day practice is often made awkward by a few gotchas. We can address this task with a very short XFBR function - the perfect tool for a simple fix like this! While working our way through the solution, we'll discuss a few best practices for text-replacement jobs and general rule writing.
