Skip to main content

Solution Install/Uninstall

Installing a Solution​

The following outlines the steps to download and install a Solution from the Solution Exchange into your OneStream development environment.

Prerequisites​

  • Ensure your OneStream development environment is already installed and up to date.
  • Verify that you have the necessary permissions and licenses to install solutions (key may be required to access partner solutions).

Step-by-Step Installation Instructions​

  1. Open the Solution Exchange: Launch your browser and navigate to the Solution Exchange at https://solutionexchange.onestream.com/.

  2. Search for the Solution: Navigate to the Solution Catalog and then use the search bar to locate the desired solution by name. For example, you might search for "Cube."

  3. Review of the Solution Details: Before installing, it’s recommended to review the solution’s description, publisher information, versioning, and release notes to ensure it meets your needs.

  4. Click “Download”: Once confirmed, click the Download button. The download process may take a few moments depending on the size of the solution.

  5. Load the Solution: After the download is completed, navigate to the Application tab of your OneStream development environment. Click “Load/Extract”, then click “Select File” and select the previously downloaded solution from the dialog. Click “Load” to finish the install.

  6. Refresh OneStream Application: Refresh the OneStream application. Navigate to the OnePlace tab. Launch the newly downloaded Solution.

Removing a Solution​

Solutions in OneStream can significantly enhance your development experience by adding value via extensibility. However, there are several reasons why you might want to uninstall a solution. Compatibility issues are one factor, as certain solutions may conflict with updates to OneStream, leading to errors or unexpected behavior. Additionally, different applications might require different sets of solutions, so uninstalling unnecessary ones can help keep your development environment clean and focused. Lastly, regularly reviewing and uninstalling unused or outdated solutions can help maintain the security of your development environment. By periodically managing your solutions, you can ensure that OneStream remains efficient and tailored to your specific needs.

How to Uninstall​

You will want to have a settings page that has descriptions of Uninstall Full, Uninstall UI, as well as buttons that a user can select for both options. If your solution does not have database tables, then you may only want to have one button just for Uninstall UI. Here’s what an end user would do to complete the process:

  1. Click Application > Solution’s Settings Page > Uninstall
  2. There are two uninstall options:
  • Uninstall UI removes the solution, including related dashboards and business rules but leaves the database and related tables in place. For some releases, this step should be performed before accepting any new version of the solution since some of the dashboards or other objects may have been modified.
  • Uninstall Full removes all the related data tables, all data, the solution dashboards, and business rules. Choose this option to completely remove the solution or to perform an upgrade that significantly changes the data tables.
caution

Uninstall procedures are irreversible.

Here’s an example of how an uninstall dashboard could look from your settings page.

uninstall dashboard

Behind the Scenes: Uninstall Routine​

When you uninstall a solution, OneStream runs several methods behind the scenes to ensure the solution is completely removed. These methods are executed based on which uninstall type was selected to ensure that all components of the solution are properly uninstalled. Here are the methods that are called during the Uninstall Routine:

DeleteWorkspace()​

Deleting a workspace will delete all nested maintenance units, dashboard groups, components, data adapters, parameters, files, and assemblies.

private void DeleteWorkspace(SessionInfo si)
{
    try
    {
	// Delete the workspace associated With this solution
	Guid workspaceId = Guid.Empty;
	// Get the workspace ID to delete
	workspaceId = BRApi.Dashboards.Workspaces.GetWorkspaceIDFromName(si, false, "Workspace Name Here");
	if (!workspaceId.Equals(Guid.Empty))
	{
	    // Delete workspace And all child items
	    BRApi.Dashboards.Workspaces.DeleteWorkspace(si, false, workspaceId, true);
	}
    }
    catch (Exception ex)
    {
	throw ErrorHandler.LogWrite(si, new XFException(si, ex));
    }
}

DeleteProfile()​

Deleting a profile will remove the solution’s UI from OnePlace.

private static bool DeleteProfile(SessionInfo si, DashboardExtenderArgs args)
{
    try
    {
	// Delete Solution Dashboard Profile
	using DbConnInfo dbConnApp = BRApi.Database.CreateApplicationDbConnInfo(si);
	using DbConnInfo dbConnFW = BRApi.Database.CreateFrameworkDbConnInfo(si);
	DashboardProfile dashProfile = null;
	dashProfile = EngineDashboardProfiles.GetProfile(dbConnApp, "[Insert Dashboard Profile Name]");
	if (dashProfile != null)
	{
	    SecurityHelperWcf.ValidateDelete(dbConnFW, dbConnApp, DashboardHelperWcf.GetRoleType(true), dashProfile, throwOnError: true);
	    EngineDashboardProfiles.DeleteProfile(dbConnApp, dashProfile.UniqueID);
	}
	return true;
    }
    catch (Exception ex)
    {
	BRApi.ErrorLog.LogError(si, new XFException(si, ex));
	return false;
    }
}

DropSolutionTables()​

Dropping solution tables will drop all the Solution’s related database tables. This requires a DROP TABLE SQL script which will be described in the next section.

private static bool DropSolutionTables(SessionInfo si, DashboardExtenderArgs args, ref StringBuilder returnMessage)
{
    try
    {
        // Open the DDL script used to create the custom tables required for this solution
        if (BRApi.Security.Authorization.IsUserInAdminGroup(si))
        {
            // Get the SQL from the TableDrop file in the dashboard
            string setupFileName = "[Insert Table Drop File Name]";
            DashboardFileResource fileResource = BRApi.Dashboards.FileResources.GetFileResource(si, false, args.PrimaryDashboard.WorkspaceID, setupFileName);
            if (fileResource == null)
            {
                returnMessage.AppendLine("Table Drop File (" + setupFileName + ") is missing or invalid.");
                return false;
            }
            else
            {
                // Define string to hold SQL table drop script
                string sqlScript = Encoding.UTF8.GetString(fileResource.FileBytes);

                // Create connection to application database
                using DbConnInfo dbConnApp = BRApi.Database.CreateApplicationDbConnInfo(si);
                try
                {
                    // Create the dashboard Table(s) from the defined script
                    BRApi.Database.ExecuteActionQuery(dbConnApp, sqlScript, false, true);

                    // Message that tables dropped successfully
                    returnMessage.AppendLine("Solution Tables and Data Uninstalled");
                    return true;
                }
                catch
                {
                    // Message that table drop failed
                    returnMessage.AppendLine("Error: Solution Tables and Data NOT Uninstalled");
                    return false;
                }
            }
        }
        else
            returnMessage.AppendLine("Security Error: Adminstration Rights Required to Execute Uninstall");
        return false;
    }
    catch (Exception ex)
    {
        throw ErrorHandler.LogWrite(si, new XFException(si, "Unhandled Exception in DropSolutionTables() function.", ex.Message, ex.InnerException));
    }
}

UninstallSolution()​

When called this method will uninstall the UI, Business Rules, and drop all the Solution’s related database tables. It calls a combination of the previous 3 methods based on the uninstall type. For example, if a user selects Uninstall UI (uninstall type does not equal “Full”), then only the DeleteProfile and DeleteWorkspace methods are invoked.

private static XFSelectionChangedTaskResult UninstallSolution(SessionInfo si, DashboardExtenderArgs args)
{
    try
    {
	// Uninstall UI, BRs and Drop Solution Tables
	Guid workspaceId = BRApi.Dashboards.Workspaces.GetWorkspaceIDFromName(si, false, "[Insert Workspace Name]");
	string solutionCode = BRApi.Dashboards.Parameters.GetLiteralParameterValue(si, false, workspaceId, "HelpAboutSolutionCode_DTKH");
	XFSelectionChangedTaskResult selectionChangedTaskResult = new();
	System.Text.StringBuilder message = new();
	bool tablesDropped = false;

	if (BRApi.Security.Authorization.IsUserInAdminGroup(si))
	{
	    // Uninstall the Solution
	    string uninstallType = args.NameValuePairs.XFGetValue("Type", "UI");

	    // Evaluate the uninstall type
	    if (uninstallType.XFEqualsIgnoreCase("Full"))
	    {
		// Drop all associated database tables
		tablesDropped = DropSolutionTables(si, args, ref message);
		if (!tablesDropped)
		{
		    message.Append("Error: User Interface & Solution Tables NOT Fully Uninstalled.");
		}
	    }

	    // Delete Solution Workspace, all child items of that Workspace and the Dashboard Profile

	    if (DeleteProfile(si) && DeleteWorkspace(si))
	    {
		message.AppendLine("To Complete the Process:");
		message.AppendLine("1) Close the Dialog");
		message.AppendLine("2) Close the Dashboard Page");

		// Log the Uninstall
		BRApi.ErrorLog.LogMessage(si, $"Solution ({solutionCode}) was uninstalled [Type: {uninstallType}]{Environment.NewLine}");
	    }
	    else
	    {
		message.Append("Error: Profile and/or Workspace could NOT be deleted.");
	    }

	}
	else
	    message.Append("Security Error: Adminstration Rights Required to Execute Uninstall.");

	// Set the return value
	selectionChangedTaskResult.IsOK = true;
	selectionChangedTaskResult.ShowMessageBox = true;
	selectionChangedTaskResult.Message = message.ToString();

	return selectionChangedTaskResult;
    }
    catch (Exception ex)
    {
	throw ErrorHandler.LogWrite(si, new XFException(si, ex));
    }
}

Drop Table Script​

A DROP TABLE script in SQL is used to delete an entire table from a database, including all its data and structure. The goal is to remove the table permanently, which can be useful for cleaning up unused tables or resetting a database. However, it's important to use this command with caution, as it cannot be undone and all data in the table will be lost.

When Uninstall Full is selected, the DROP TABLE script is run. This script will be a SQL command with the tables to dop stored in a TXT file.

USE [YourDatabaseName];

DROP TABLE [YourSchemaName].[TableName1];
DROP TABLE [YourSchemaName].[TableName2];
DROP TABLE [YourSchemaName].[TableName3];

Legacy Business Rules​

In the newer versions of the OneStream platform, business logic is handled by the solution’s assemblies in the current workspace. If you are running a OneStream platform version prior to 8.x, then your solution may contain legacy business rules, which you likely will want to remove from the application on uninstall. This requires an additional method.

DropSolutionBRs()​

When called this method will uninstall the legacy business rules from the application.

private string DropSolutionBRs(SessionInfo si)
{
    try
    {
        // Delete business rules associated with this app
        string message = String.Empty;

        // List of Business Rules that need to be removed
        Dictionary<string, BusinessRuleType> dsbBusinessRules = new Dictionary<string, BusinessRuleType>() {
                {"{DashboardExtender BRNames}", BusinessRuleType.DashboardExtender},
                {"{XFBRString BRNames}", BusinessRuleType.DashboardStringFunction},
                {"{DashboardDataSet BRNames}", BusinessRuleType.DashboardDataSet},
                {"{Extensibility BRNames}", BusinessRuleType.Extender},
                {"{Finance BRNames}", BusinessRuleType.Finance}
                };

        if (BRApi.Security.Authorization.IsUserInAdminGroup(si))
        {
            var frameworkObject = new Framework();

            // Get/Delete Dashboard Business Rules
            foreach (KeyValuePair<string, BusinessRuleType> br in dsbBusinessRules)
            {
                BusinessRuleInfo brInfo = frameworkObject.GetBusinessRule(si, false, br.Value, br.Key);
                if (brInfo != null && !string.IsNullOrEmpty(brInfo.Name))
                {
                    frameworkObject.DeleteBusinessRule(si, false, br.Value, br.Key);
                }

            }

        }
        else
            message = "Security Error: Administration Rights Required to Execute Uninstall.";

        return message;
    }
    catch (Exception ex)
    {
        throw ErrorHandler.LogWrite(si, new XFException(si, ex));
    }
}

Dashboard Settings Page​

A DROP TABLE script in SQL is used to delete an entire table from a database, including all its data and structure. The goal is to remove the table permanently, which can be useful for cleaning up unused tables or resetting a database. However, it's important to use this command with caution, as it cannot be undone and all data in the table will be lost. When Uninstall Full is selected, the DROP TABLE script is run.

Important Considerations​

Be sure to extract your solutions as a zip from OneStream so that you can have the current state as a backup before you uninstall. If you uninstall a solution without having an extract, you will lose the current state and any changes that were made.

  1. Click Application > Tools > Load/Extract
  2. Select the Extract tab
  3. From the File Type combo box, select XF Project
  4. Click the ellipsis button and a file explorer dialog will appear
  5. Navigate to and select the xfProj file for your solution, then hit Open
  6. Check the box for Extract To Zip
  7. Click Extract and save the zip to a destination folder
Last updated on by Jeremy Meiss

Was this page helpful?