Appendix E: Smart Link APIs

Create Smart Link

The following business rules create Smart Links and allow developers to provide dynamic parameters (Custom Substitution Variables) using name-value pairs. In the code snippets below, link expiration is set to 240 hours (10 days) and outputs the Smart Link in a message box. Optionally, the link can direct a user to a different OneStream environment using Host Override or append a custom name to the end of the Smart Link URL using Custom Name.

C# Code Snippet:

Copy 
public XFSelectionChangedTaskResult CreateSmartLink(SessionInfo si, BRGlobals globals, object api, DashboardExtenderArgs args)
        {
            // Create new smart link and set expiration
            var smartlink = new XFSmartLink();    
            smartlink.IsSystemlevel = true;
            smartlink.ExpirationDateUtc = DateTime.UtcNow.AddHours(240);
            
            // Optional Properties
            // Host override: Allows to change the host value. Must be a value host
            //smartlink.HostOverride = "https://buxtest.com:444";
            
            // Custom Name: Adds a suffix at the end of the smart link. Alphanumeric, 50 characters max.
            //smartlink.CustomName = "ThisIsACustomName";

            var dashboard = new XFSmartLinkDashboard();
            
            // Change values below to target different applications/ Dashboards
            dashboard.ApplicationName = "GolfStreamDemo_v36";
            dashboard.DashboardName = "SmartLinks";
            dashboard.WorkspaceName = "Default";
            dashboard.DashboardProfileName = "Default";
            dashboard.CustomSubstVars = new Dictionary<string, string>();
            
            // Add/ Remove the lines below to modify the custom subst vars that will be applied.
            dashboard.CustomSubstVars.Add("parameter1", "value");
            dashboard.CustomSubstVars.Add("parameter2", "value2");            
            
            smartlink.TargetObject = dashboard;
                
            string sValue = BRApi.State.CreateSmartLink(si, smartlink);
            var match = System.Text.RegularExpressions.Regex.Match(sValue, @"share/([A-Z0-9]{32})");
            
            BRApi.Dashboards.Parameters.SetLiteralParameterValue(si, false, "slid", match.Groups[1].Value);
            
            var result = new XFSelectionChangedTaskResult();
            result.IsOK = true;
            result.ShowMessageBox = true;
            result.Message = sValue;
            return result;
        }

VB Code Snippet: 

Copy 
Public Function CreateSmartLink(ByVal si As SessionInfo, ByVal globals As BRGlobals, ByVal api As Object, ByVal args As DashboardExtenderArgs) As XFSelectionChangedTaskResult
            ' Create new smart link and set expiration
            Dim smartlink = New XFSmartLink()
            smartlink.IsSystemlevel = True
            smartlink.ExpirationDateUtc = DateTime.UtcNow.AddHours(240)
            
            ' Optional Properties
            ' Host override: Allows To change the host value. Must be a value host
            'smartlink.HostOverride = "https://buxtest.com:444"
            
            ' Custom Name: Adds a suffix at the End Of the smart link. Alphanumeric, 50 characters max.
            'smartlink.CustomName = "ThisIsACustomName"
            
            Dim dashboard = New XFSmartLinkDashboard()
            
            ' Change values below to target different applications/ Dashboards
            dashboard.ApplicationName = "GolfStreamDemo_v36"
            dashboard.DashboardName = "SmartLinks"
            dashboard.WorkspaceName = "Default"
            dashboard.DashboardProfileName = "Default"
            dashboard.CustomSubstVars = New Dictionary(Of String, String)()
            
            ' Add/ Remove the lines below to modify the custom subst vars that will be applied.
            dashboard.CustomSubstVars.Add("parameter1", "value")
            dashboard.CustomSubstVars.Add("parameter2", "value2")
            
            smartlink.TargetObject = dashboard
            
            Dim sValue As String = BRApi.State.CreateSmartLink(si, smartlink)            
            Dim match = System.Text.RegularExpressions.Regex.Match(sValue, "share/([A-Z0-9]{32})")
            
            BRApi.Dashboards.Parameters.SetLiteralParameterValue(si, False, "slid", match.Groups(1).Value)
            
            Dim result = New XFSelectionChangedTaskResult()
            result.IsOK = True
            result.ShowMessageBox = True
            result.Message = sValue
            Return result
        End Function

Retrieve Smart Link

Smart Links are stored for a set period of time. Using the following business rules, developers can retrieve a stored Smart Link using slid (Smart Link ID)

C# Code Snippet:

Copy 
public XFSelectionChangedTaskResult GetSmartLink(SessionInfo si, BRGlobals globals, object api, DashboardExtenderArgs args)
        {
            var id = BRApi.Dashboards.Parameters.GetLiteralParameterValue(si, false, "slid");
            
            var guidId = Guid.Parse(id);
            XFSmartLink sValue = BRApi.State.GetSmartLink(si, true, guidId);
            var text = System.Text.Json.JsonSerializer.Serialize(sValue);
            
            var result = new XFSelectionChangedTaskResult();
            result.IsOK = true;
            result.ShowMessageBox = true;
            result.Message = text;
            return result;
        }

VB Code Snippet: 

Copy 
Public Function GetSmartLink(ByVal si As SessionInfo, ByVal globals As BRGlobals, ByVal api As Object, ByVal args As DashboardExtenderArgs) As XFSelectionChangedTaskResult
            Dim id = BRApi.Dashboards.Parameters.GetLiteralParameterValue(si, False, "slid")
            
            Dim guidId = Guid.Parse(id)
            Dim sValue As XFSmartLink = BRApi.State.GetSmartLink(si, True, guidId)
            Dim text = System.Text.Json.JsonSerializer.Serialize(sValue)
            
            Dim result = New XFSelectionChangedTaskResult()
            result.IsOK = True
            result.ShowMessageBox = True
            result.Message = text
            Return result
        End Function

Delete Smart Link

The following business rules delete stored Smart Links.

C# Code Snippet:

Copy 
public XFSelectionChangedTaskResult DeleteSmartLink(SessionInfo si, BRGlobals globals, object api, DashboardExtenderArgs args)
        {
            var id = BRApi.Dashboards.Parameters.GetLiteralParameterValue(si, false, "slid");        
            var guidId = Guid.Parse(id);
            
            BRApi.State.DeleteSmartLink(si, true, guidId);
            var text = "Deleted";
            
            var result = new XFSelectionChangedTaskResult();
            result.IsOK = true;
            result.ShowMessageBox = true;
            result.Message = text;
            return result;
        }

VB Code Snippet:

Copy 
    Public Function DeleteSmartLink(ByVal si As SessionInfo, ByVal globals As BRGlobals, ByVal api As Object, ByVal args As DashboardExtenderArgs) As XFSelectionChangedTaskResult
            Dim id = BRApi.Dashboards.Parameters.GetLiteralParameterValue(si, False, "slid")            
            Dim guidId = Guid.Parse(id)
            
            BRApi.State.DeleteSmartLink(si, True, guidId)
            Dim text = "Deleted"
            
            Dim result = New XFSelectionChangedTaskResult()
            result.IsOK = True
            result.ShowMessageBox = True
            result.Message = text
            Return result
        End Function

Modify Smart Link

The following business rules are designed to overwrite an existing Smart Link while retaining its URL. Since modifying a link overwrites all stored values, all required values need to be provided when using this rule.

C# Code Snippet:

Copy 
public XFSelectionChangedTaskResult ModifySmartLink(SessionInfo si, BRGlobals globals, object api, DashboardExtenderArgs args)
        {
            var id = BRApi.Dashboards.Parameters.GetLiteralParameterValue(si, false, "slid");
            var guidId = Guid.Parse(id);
            
            var smartlink = new XFSmartLink();    
            smartlink.IsSystemlevel = true;
            smartlink.ExpirationDateUtc = DateTime.UtcNow.AddHours(240);

            var dashboard = new XFSmartLinkDashboard();
            
            // Change values below to target different applications/ Dashboards
            dashboard.ApplicationName = "GolfStreamDemo_v36";
            dashboard.DashboardName = "Modified";
            dashboard.WorkspaceName = "Default";
            dashboard.DashboardProfileName = "Default";
            dashboard.CustomSubstVars = new Dictionary<string, string>();
            
            // Add/ Remove the lines below to modify the custom subst vars that will be applied.
            dashboard.CustomSubstVars.Add("parameter1", "test");
            dashboard.CustomSubstVars.Add("parameter2", "value2");            
            dashboard.CustomSubstVars.Add("parameter3", "value3");
            dashboard.CustomSubstVars.Add("parameter4", "value4");    
            
            smartlink.TargetObject = dashboard;
            
            BRApi.State.ModifySmartLink(si, true, guidId, smartlink);
            
            var result = new XFSelectionChangedTaskResult();
            result.IsOK = true;
            result.ShowMessageBox = true;
            result.Message = "Modified";
            return result;
        }
    }
}

VB Code Snippet:

Copy 

        Public Function ModifySmartLink(ByVal si As SessionInfo, ByVal globals As BRGlobals, ByVal api As Object, ByVal args As DashboardExtenderArgs) As XFSelectionChangedTaskResult
            Dim id = BRApi.Dashboards.Parameters.GetLiteralParameterValue(si, False, "slid")
            Dim guidId = Guid.Parse(id)
            
            Dim smartlink = New XFSmartLink()
            smartlink.IsSystemlevel = True
            smartlink.ExpirationDateUtc = DateTime.UtcNow.AddHours(240)
            
            Dim dashboard = New XFSmartLinkDashboard()
            dashboard.ApplicationName = "GolfStreamDemo_v36"
            dashboard.DashboardName = "Modified"
            dashboard.WorkspaceName = "Default"
            dashboard.DashboardProfileName = "Default"
            dashboard.CustomSubstVars = New Dictionary(Of String, String)()
            
            ' Change values below to target different applications/ Dashboards
            dashboard.CustomSubstVars.Add("parameter1", "test")
            dashboard.CustomSubstVars.Add("parameter2", "value2")
            dashboard.CustomSubstVars.Add("parameter3", "value3")
            dashboard.CustomSubstVars.Add("parameter4", "value4")
            
            smartlink.TargetObject = dashboard
            
            BRApi.State.ModifySmartLink(si, True, guidId, smartlink)
            
            Dim result = New XFSelectionChangedTaskResult()
            result.IsOK = True
            result.ShowMessageBox = True
            result.Message = "Modified"
            Return result
        End Function
    End Class
End Namespace