Skip to main content

Connecting to Excel via the AtScale Add-In

You can use AtScale's branded add-in to connect to Microsoft Excel via SSO.

Prerequisites​

  • AtScale must be configured with either Microsoft Entra ID using OpenID Connect or Okta using SAML.

  • 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 you need to install a new version of the add-in, you must first fully uninstall any previous versions. This includes any versions from installer-based AtScale.

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:

  2. Right click the Installer.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:

  1. Download the installer that corresponds to your OS architecture and extract the .zip file:

  2. Double click the Installer.msi file.

  3. Click Next.

  4. When asked to select the authentication method for your AtScale deployment, select SML/Keycloak, then click Next.

  5. (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 on 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.

  6. 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, a Login with AtScale tab appears in the ribbon.

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 Login with 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 on the Connect tab for the deployed catalog in Design Center.

    Note

    The connection string will be prepopulated if you provided a Default AtScale Server URL in the procedure above.

  5. Click Next. The AtScale login screen opens in your browser.

  6. Enter your login credentials and sign in. The login screen closes, and the Select Data Model dialog appears.

  7. Select a catalog and model, then click Next.

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

  9. Click OK.

Refreshing AtScale connections​

To refresh all AtScale connections in a workbook:

  1. Open a workbook that contains connections to AtScale.
  2. Click the Login with AtScale tab in the ribbon.
  3. Click Refresh All in the ribbon.

To refresh a single connection:

  1. Open a pivot table that contains an AtScale connection.
  2. Click the Login with AtScale tab in the ribbon.
  3. Click Refresh Selected in the ribbon.

Troubleshooting​

The add-in keeps daily logs in ExcelPluginSSO\Logs\ExcelPluginLog-YYYYMMDD.txt files, under your My Documents folder. Up to seven log files are kept at a time. These can be used to debug issues, and can be shared with AtScale Support.

The default log level is Information, which is recommended for production use. If needed, this can be changed by modifying the following line in Program Files\AtScale Excel Add-in\atscalePlugin.config:

<add key="logLevel" value="Information"/>

Below are a few common issues you may encounter when using the add-in, with instructions for resolving them.

The add-in does not appear in the Excel ribbon​

Ensure Excel has not disabled the add-in:

  1. In Excel, go to File > Options > Add-ins.
  2. In the Manage select field, select Disabled add-ins, then click Go.
  3. Select the LoginToAtScale add-in and click Enable.
  4. Close and re-open Excel and see if the add-in appears.

The browser opens but the login screen doesn’t load or shows an error​

Possible solutions:

  • Ensure you used the correct AtScale server URL when you created the connection.
  • Ensure cookies are enabled in your browser.
  • Ensure the AtScale server is accessible from your machine.

After signing in, a "No connections found with the specified host name" error appears​

Ensure you have at least one connection to the AtScale instance configured in Excel.

After signing in, a "Connection Test Failed For Updating the Host" error appears​

Possible solutions:

  • Ensure your IdP is configured correctly based on the steps above, and that the Store Tokens option is enabled in the IdP settings. This issue is usually associated with 400 Bad Request errors reported in the log files.
  • Ensure the atscale-excel-plugin client is configured correctly and has the offline_access scope.
  • Ensure the user has the offline_access and query_user roles assigned in the Identity Broker, as well as runtime permissions to interact with the catalogs. This is usually associated with 401 Unauthorized errors reported in the log files.
  • Ensure there are connections to the AtScale servers configured in the Excel workbook. If there are, the add-in prompts for login when the workbook opens. If there aren’t, it doesn't prompt for login, indicating a URL may be misconfigured.

After signing in, trying to interact with the connection produces an error: "The query did not run, or the database table could not be opened" or "Excel cannot find OLAP cube"​

Ensure the user has the correct runtime permissions to interact with the catalogs.