Skip to main content

Connecting to Excel via the AtScale Add-In

This section describes how to use AtScale's branded add-in to connect to Microsoft Excel via SSO.

Prerequisites​

  • AtScale must be configured with Microsoft Entra ID.

  • The Store Tokens option must be enabled for your IdP.

  • The Identity Broker must have an atscale-excel-plugin client configured with the following:

    • The offline_access client scope.
    • Valid Redirect URIs set to https://login.microsoftonline.com/common/oauth2/nativeclient.

  • All users who will use the add-in to log in to AtScale from Excel must have the offline_access and query_user roles assigned in the Identity Broker (note that these are automatically granted to admin users), as well as the necessary runtime permissions for the catalogs they will connect to.

  • Any federated users must have the offline_access role assigned in the Identity Broker.

  • You must be using a supported version of Excel. For the versions AtScale currently supports, see AtScale Supported Tools and Platforms.

Note

If any Installer-based versions of the add-in are currently installed on your machine, you must uninstall them before installing or upgrading a Container-based version.

Container-based versions of the add-in can be upgraded in-place.

Install the AtScale certificate​

First, an AtScale admin needs to install the AtScale certificate:

  1. Download the installer that corresponds to your OS architecture and extract the .zip file. You can download the latest version here:

    Note

    If you need another version of the installer, see Available Versions.

  2. Right-click the .msi file and select Properties.

  3. Click Digital Signatures, select the certificate, then click Details.

  4. Click View Certificate > Install Certificate.

  5. Select Local Machine.

  6. Select the Place all certificates in the following store option, then select Trusted Publishers.

  7. Click Ok, then click Next.

  8. Click Finish.

Install the AtScale add-in​

Next, the Excel add-in needs to be installed on users' machines. This can be done either with the standard installer, or silently via the command line.

Install the add-in with the standard installer​

  1. Download the installer that corresponds to your OS architecture and extract the .zip file. You can download the latest version here:

    Note

    If you need another version of the installer, see Available Versions.

  2. Double-click the .msi file.

  3. Click Next.

  4. (Optional) In the Default AtScale Server URL (optional) field, enter the MDX connection string for the AtScale model you want to connect to. This can be obtained from the Connect tab for the deployed catalog in Design Center.

    If you provide this information, the connection string will be prepopulated when you add an AtScale connection in Excel; for more information, see the following procedure.

  5. (Optional) Enable the Require authentication on workbook open option as needed:

    • Enabled: AtScale prompts the user to log in when a saved workbook is opened.

    • Disabled: When the user opens a saved workbook, they are not prompted to log in to AtScale. The workbook opens in a locked state, displaying all previously saved data.

      The user can authenticate with AtScale and unlock the pivot table without refreshing the data by either double-clicking within the pivot table, or by double-clicking the filter or page field area of the table. AtScale does not refresh the table data at this time.

      AtScale only updates the pivot table data if the user explicitly changes the data (for example, if they change a filter), or if they click Refresh All or Refresh Selected.

      For workbooks with multiple pivot tables, unlocking one table automatically unlocks the others. None of them update. If the user explicitly changes or refreshes one of them, AtScale only updates that table, not the others.

  6. (Optional) Enable the Remember sign-in between Excel sessions option as needed:

    • Enabled: Users only need to sign in when they first use the add-in. After that, they are not prompted again.
    • Disabled: Users must sign in to AtScale when they start Excel, open a saved workbook, unlock a pivot table, open a saved .odc file, and refresh their connections to AtScale.

  7. Click Next.

  8. Click Install.

If the installation was successful, a folder for the add-in appears in your Program Files folder. The next time you open Excel, an AtScale tab appears in the ribbon.

Install the add-in silently via the command line​

To install the add-in silently via the command line:

  1. Download the installer that corresponds to your OS architecture and extract the .zip file. You can download the latest version here:

    Note

    If you need another version of the installer, see Available Versions.

  2. Run the following from an elevated prompt:

    msiexec /i <msi> /qn

    Where <msi> is the installer you extracted in the previous step.

    You can optionally include the following arguments:

    • DEFAULTSERVERURL=<url>: Defines the MDX connection string for the AtScale model users will connect to. This can be obtained on the Connect tab for the deployed catalog in Design Center.

      If you provide this argument, the connection string will be prepopulated when users add an AtScale connection in Excel; for more information, see the following procedure.

    • REQUIREAUTHONOPEN=1|0: When enabled (1), AtScale prompts the user to log in when a saved workbook is opened.

      When disabled (0), when the user opens a saved workbook, they are not prompted to log in to AtScale. The workbook opens in a locked state, displaying all previously saved data.

      The user can authenticate with AtScale and unlock the pivot table without refreshing the data by either double-clicking within the pivot table, or by double-clicking the filter or page field area of the table. AtScale does not refresh the table data at this time.

      AtScale only updates the pivot table data if the user explicitly changes the data (for example, if they change a filter), or if they click Refresh All or Refresh Selected.

      For workbooks with multiple pivot tables, unlocking one table automatically unlocks the others. None of them update. If the user explicitly changes or refreshes one of them, AtScale only updates that table, not the others. |

    • PERSISTREFRESHTOKEN=1|0: When enabled (1), users will only need to sign in when they first use the add-in. After that, they will not be prompted again.

      When disabled (0), users must sign in to AtScale when they start Excel, open a saved workbook, unlock a pivot table, open a saved .odc file, and refresh their connections to AtScale.

    Note

    Values provided via the command-line take precedence over any remembered from a previous install.

Configure a connection to AtScale in Excel​

Once the add-in has been installed, users must configure a connection to AtScale within Excel:

  1. In Excel, open a blank workbook.

  2. In the ribbon, click AtScale.

  3. Select a cell in the workbook, then click Add Connection in the ribbon. The Enter Server URL dialog appears.

  4. Enter the MDX connection string for the model. This can be obtained from the Connect tab for the deployed catalog in Design Center.

    Note

    The connection string will be prepopulated if a Default AtScale Server URL was provided when the add-in was installed.

  5. Click Next.

  6. Enter your login credentials and sign in, if you are prompted to do so.

  7. In the Select Data Model dialog, select a catalog and model, then click Next.

  8. (Optional) Enter a name and description for the connection.

  9. Click OK.

Additional information​