Dodeca Excel Add-In for Essbase Installation Guide (MSI)

Prerequisites

The Dodeca Excel Add-in for Essbase has two primary prerequisites, in addition to a supported version of Excel. The supported versions of Excel for this release include the following: Excel 2010, Excel 2013, Excel 2016, and Office365 Desktop. Although not explicitly supported, there are currently no known issues when using the add-in with Excel 2007.

Microsoft .NET Framework v4.0

The Dodeca Excel Add-In for Essbase requires the .NET Framework, version 4.0 or higher.

Suggested Package:

https://www.microsoft.com/en-us/download/details.aspx?id=17718

Visual Studio Tools for Office Runtime

The Dodeca Excel Add-In for Essbase is written in Microsoft .NET and leverages the Microsoft Office developer tools. In order to run the solution, the Visual Studio Tools for Office Runtime must be installed.

Suggested Package:

https://www.microsoft.com/en-us/download/details.aspx?id=56961

Deployment Trust / Certificate Management

The Dodeca Excel Add-In for Essbase is a VSTO (Visual Studio Tools for Office) deployment, which must be signed with a code-signing certificate in order to be installed on an end-user machine. Signing of the VSTO deployment is accomplished via the ClickOnce Prep Utility, which is provided as part of the the Dodeca Framework.

When generating the Dodeca Excel Add-In deployment package, the certificate used to sign the deployment is governed by the following settings:

VSTO Add-In Trust

A VSTO deployment is considered fully trusted and can be installed silently and without user interaction only when the certificate used to sign the deployment is present in the Trusted Publishers key store and the root certification authority (CA) is present in the Trusted Root Certification Authorities key store. For a self-signed certificate, such as those generated by the ClickOnce Prep Utility, this means that the generated certificate must be present in both the Trusted Publishers and Trusted Root Certification Authorities key stores.

In most cases, when the deployment is not considered fully trusted, an end-user will be prompted that the publisher cannot be verified and be permitted to proceed with the installation:

In some cases, however, depending on the .NET and Office security policies utilized within an organization, the deployment may need to be fully trusted, regardless of whether user interaction to complete the installation is acceptable. In these cases, the installation will fail unless the deployment is fully trusted.

If a fully silent installation without user interaction is required, the deployment must be trusted, regardless of applied security policies.

Trusting VSTO Deployment Certificates

Depending on the certificate used to sign the Dodeca Excel Add-In for Essbase and the intended deployment mechanism, it may be required to add the certificate to the Trusted Publishers and Trusted Root Certification Authorities key stores under either the Current User or Local Machine scope on end-user machines. If your organization has its own Trusted Root Certification Authority, a trusted certificate may already be available for this purpose.

Via Group Policy

Distribution and trust of the utilized deployment signing certificate via Group Policy is the recommended approach to ensure that end-users are able to install the Dodeca Excel Add-In for Essbase without issue, regardless of the intended deployment mechanism.

See the following article for details:

https://docs.microsoft.com/en-us/windows-server/identity/ad-fs/deployment/distribute-certificates-to-client-computers-by-using-group-policy

Via Certutil.exe

If desired, certificates can be trusted at the local machine or current user level using Microsoft’s certutil.exe, regardless of the intended deployment mechanism.

When the GenerateCertificate policy is used by the ClickOnce Prep Utility, a self-signed certificate for each deployment URL will be generated in a location similar to the following:
C:\Program Files\Applied OLAP\Dodeca Framework 8.2.0\bin

Certificates generated by the ClickOnce Prep Utility are assigned the following password:
password

Example Local Machine Import for Generated Certificate:

certutil.exe -f -p "<password>" -importPFX Root "<cert>.pfx"
certutil.exe -f -p "<password>" -importPFX TrustedPublisher "<cert>.pfx"

Example Current User Import for Generated Certificate:

certutil.exe -f -user -p "<password>" -importPFX Root "<cert>.pfx"
certutil.exe -f -user -p "<password>" -importPFX TrustedPublisher "<cert>.pfx"

See the following article for further details:

https://docs.microsoft.com/en-us/windows-server/administration/windows-commands/certutil

Via Microsoft Management Console

If desired, certificates can be trusted at the local machine or current user level using the Certificates snap-in for Microsoft Management Console (MMC).

See the following article for details:

https://docs.microsoft.com/en-us/biztalk/adapters-and-accelerators/accelerator-rosettanet/importing-certificates-using-mmc

Deployment Mechanisms

The Dodeca Excel Add-in for Essbase has two primary deployment mechanisms:
ClickOnce for VSTO and what is termed an XCopy deployment, whereby the deployment files are copied to the end-user machine and registered into Excel via a Windows Installer package (MSI) or executable installer. This document will detail the XCopy deployment mechanism via a Windows Installer (MSI) package.

XCopy

The XCopy deployment mechanism provided for the Dodeca Excel Add-In for Essbase represents a traditional software installation, whereby the software package and updates to that package are installed either directly by end-users, by package advertisement, or via an administrative process provided by a software management console like Microsoft’s System Center Configuration Manager (SCCM).

Windows Installer (MSI)

A Windows Installer package (MSI) for the Dodeca Excel Add-In for Essbase is provided as part of the Dodeca Framework. When a deployment is built using the ClickOne Prep Utility, a Windows Installer package is generated with the contents of that deployment in a location similar to the following:

C:\Program Files\Applied OLAP\Dodeca Framework 8.2.0\xcopy\exceladdin\ windowsinstaller\DodecaExcelAddInForEssbase.8.2.0.msi

The generated Windows Installer package can be signed with the same certificate used to sign the deployment, signed manually after the fact using a trusted certificate within an organization, or distributed unsigned. Whether the certificate used to sign the deployment will be used to sign the installation package is governed by the following settings:

Per-User Installation

If a per-user installation, which refers to an installation targeting a single end-user account, is desired, the provided dual-purpose installation package needs only be run as the end-user. If an installation path other than the default install location is required for the installation, an INSTALLFOLDER accessible to and writable by the end-user may be passed to msiexec or configured in the software management console of choice.

Example Per-User Installation via msiexec:

msiexec.exe /i "DodecaExcelAddInForEssbase.8.2.0.msi"

If the per-user installation is intended to require no user interaction upon the subsequent launch of Excel, the deployment will need to be trusted according to the procedure described in the section titled Trusting VSTO Deployment Certificates.

Per-Machine Installation

If a per-machine installation, which refers to an installation targeting every end-user account on a target machine, is desired, the provided dual-purpose installation package needs to be executed in ALLUSERS=1 configuration under an account with administrative privilege. If an installation path other than the default install location is required for the installation, an INSTALLFOLDER accessible to end-users may be passed to msiexec or configured in the software management console of choice.

Example Per-Machine Installation via msiexec:

msiexec.exe /i "DodecaExcelAddInForEssbase.8.2.0.msi" ALLUSERS=1

If the per-machine installation is intended to require no user interaction upon the subsequent launch of Excel by individual users, the deployment will need to be trusted according to the procedure described in the section titled Trusting VSTO Deployment Certificates.

Quick Install Guides

The following sections describe the basic installation workflow for a manual installation of the Dodeca Excel Add-In for the deployment mechanisms and package types described in this document.

XCopy

In its simplest form, an XCopy installation of the Dodeca Excel Add-In for Essbase consists of ensuring that the deployment signing certificate is trusted at the machine or user context and running the appropriate XCopy installation package.

Windows Installer (MSI)

The following sections describe the basic installation workflow for a manual installation of the Dodeca Excel Add-In using the Windows Installer (MSI) package.

Per-User, Quick Install

The following instructions assume that the GenerateCertificate policy is used by the ClickOnce Prep Utility. If an existing certificate is used via the UseExisting policy, please review the Deployment Trust / Certificate Management section before proceeding.

After building the deployment in the ClickOnce Prep Utility and deploying the servlet, execute the following commands as the end-user for whom the Dodeca Excel Add-In will be installed, adjusting the path and name of the deployment signing certificate as necessary:
```
certutil.exe -f -user -p "password" -importPFX Root "server.8080.dodeca.pfx"

certutil.exe -f -user -p "password" -importPFX TrustedPublisher "server.8080.dodeca.pfx"
```
If the package will be installed for multiple users on a machine, it is advisable to import the certificate in the machine context. See: Local Machine Import for Generated Certificate.
After importing the generated certificate in the machine or user context, proceed with the package installation by either double-clicking the Windows Installer (MSI) package, advertising it to end-users, or launching it via your organization’s software management console of choice.

Per-Machine, Quick Install

After building the deployment in the ClickOnce Prep Utility and deploying the servlet, execute the following commands as an administrative user, adjusting the path and name of the deployment signing certificate as necessary:
```
certutil.exe -f -p "password" -importPFX Root "server.8080.dodeca.pfx"

certutil.exe -f -p "password" -importPFX TrustedPublisher "server.8080.dodeca.pfx"
```
After importing the generated certificate in the machine context, proceed with the package installation using the following command as an administrative user or launching it via your organization’s software management console of choice in the ALLUSERS=1 configuration.
```
msiexec.exe /i "DodecaExcelAddInForEssbase.8.2.0.msi" ALLUSERS=1
```