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.

Note

To obtain the AtScale add-in for Excel, reach out to AtScale Support.

Prerequisites​

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

  • The Store Tokens option must be configured 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. Extract the .zip file that corresponds to your OS architecture (x64, x86).
  2. Right click the Installer.Containers.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. Extract the .zip file that corresponds to your OS/processor (x64, x86).
  2. Double click the Installer.Containers.msi file.
  3. Click Next, then 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. Note that this requires the MDX connection string for the model, which can be obtained on the Connect tab for the deployed catalog.

  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, then click Next. The AtScale login screen opens in your browser.
  5. Enter your login credentials and sign in. The login screen closes, and the Select Data Model dialog appears.
  6. Select a catalog and model, then click Next.
  7. (Optional) Enter a name and description for the connection.
  8. Click OK.

Authenticate with AtScale from Excel​

Users can then authenticate with AtScale from Excel to run queries:

  1. In Excel, click on the Login with AtScale tab in the ribbon.
  2. Click Refresh All in the ribbon.
  3. Sign in with the appropriate IdP.

If everything worked, all connections with the configured servers update to use the newly signed in user and automatically refresh.

Troubleshooting​

An ExcelPluginSSO\Logs\ExcelPluginLog.txt file with logs from the add-in is kept updated in the My Documents folder. The log can be used to debug issues, and can be shared with AtScale Support.

Below are a few common issues you may encounter, with instructions for resolving them.

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

Possible solutions:

  • 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​

Possible solutions:

  • 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. This issue is usually associated with 400 Bad Request errors reported in the log file.

    • Ensure the Store Tokens option is enabled in the IdP settings.

  • Ensure the client is correctly configured.

    • Ensure the atscale-excel-plugin client has the offline_access scope.

  • Ensure the user has the correct roles assigned in the Identity Broker, and has runtime permissions to interact with the catalogs. This is usually associated with 401 Unauthorized errors reported in the log file.

    • Ensure the user has the offline_access and query_user roles.
    • Ensure the user has runtime permissions to interact with the catalog.

  • 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"​

Possible solutions:

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