1. Home
  2. Other Releases
  3. On-premises 5.1
  4. Guides
  5. Tours
  6. Concepts
  7. Tools
  8. References
  9. Integrations
    1. Microsoft Excel Add-in
    2. Microsoft Power BI
    3. Tableau
  10. Data applications
  11. Releases

Integrations → Excel Add-in

About the Excel Add-in

With the Incorta Excel Add-in, you can extract data from Incorta to Excel into a Table or Pivot Table. You can save a query for later use, and refresh the data when you reopen your spreadsheet. You can also use the Excel built-in charts to create meaningful insights into your data.

Note

Your worksheet must be unprotected in order to use the Incorta Excel Add-in.

Install the Incorta Excel Add-in

To install the Incorta Excel Add-in, you will need to:

  • Install the Excel Add-in on your Incorta Server
  • Use Centralized Deployment or Sideloading to install the Incorta Excel Add-in on your local machine

Install the Excel Add-in on your Incorta Server

Your system administrator can install the Incorta Excel Add-in core on your server. The server installation requires an Incorta Excel Add-in ZIP file.

  • IncortaExcelAddin-<VERSION>.zip

Here are the installation steps:

  • Download the latest Incorta Excel Add-in ZIP file.
  • Secure copy the IncortaExcelAddin-<VERSION>.zip file to the installation path of the Incorta host: <INCORTA_INSTALLATION_PATH>/IncortaNode/runtime/webapps/incorta/external-add-ins/. If it does not yet exist, create the external-add-ins directory.
  • Unzip the IncortaExcelAddin-<VERSION>.zip file.

Refer to the Additional Information section for more information on the following Incorta Excel Add-In server advanced topics:

Note

To host the Excel Add-in on your server, you must have Incorta version 4.3.19, 4.9.5, 5.0 or later with an HTTPS connection.

Install the Incorta Excel Add-in on your Local Machine

There are two options for installing the Incorta Excel Add-in on your local machine: Centralized Deployment or Sideloading. Both options require an Incorta Excel Add-in manifest XML file:

  • incorta-manifest.xml

After the system administrator installs the Excel Add-in on the Incorta server, you can get the manifest file via the following URL: https://<INCORTA_HOST>/incorta/external-add-ins/excel/#/download-manifest

Centralized Deployment

Use Centralized Deployment to make the Incorta Excel Add-in available to users in their Office applications right away, with no client configuration required. To publish the Incorta Excel Add-in, your system administrator can reference Publish Office Add-ins using Centralized Deployment via the Microsoft 365 admin center. Microsoft recommends Centralized Deployment for add-in deployment in a production environment.

After the system administrator deploys the add-in, you can access it with the following steps, which apply to both Windows and macOS:

  • Open Microsoft Excel.
  • Create a new Excel workbook or open an existing workbook.
  • In the ribbon, select the Insert tab.
  • In the Add-ins group, select My Add-ins.
  • In the Office Add-ins dialog, select Admin Managed.
  • If Incorta is not listed in the dialog, select Refresh in the upper right corner.
  • Select Incorta.
  • Select Add.
  • If a dialog says that the Incorta Add-in loaded successfully, select Got It.
  • In the ribbon, select the Home tab.
  • In the Home ribbon, in the Incorta group, select Show to open the Incorta Excel Add-in Login panel.

Sideloading

If Centralized Deployment is not applicable in your organization, you can use a method called Sideloading to install the Incorta Excel add-in on your Windows or macOS local machine.

Use Sideloading to Install the Incorta Excel Add-in on Windows
  • Open Windows Explorer.
  • Navigate to your user folder.
  • In your user folder, create a folder with any name you choose (e.g. ExcelAddin).
  • Copy the Incorta Excel Add-in manifest file to your folder.
  • Right-click on the folder and choose Properties.
  • In the Properties dialog, select the Sharing tab and then select Share…
  • Within the Network access dialog
    • Add yourself and any other users or groups you want to share the Incorta Excel Add-in with. The minimum permission level is Read/Write .
    • Select Share.
  • When you see confirmation that Your folder is shared, copy the full folder network path that is displayed below the folder name.
  • Select Done.
  • Open a blank workbook in Excel
  • In the Excel Menu bar, select File → Options.
    • Select Trust Center.
    • Select Trust Center Settings....
    • Select Trusted Add-in Catalogs.
    • In Catalog Url, paste the full folder network path you copied earlier and select Add catalog.
    • Select Show in Menu, and then select OK to close the Trust Center dialog.
    • Select OK to close the Excel Options dialog.
  • Restart Excel.
  • Create a new Excel workbook or open an existing workbook.
  • In the ribbon, select the Insert tab.
  • In the Add-ins group, select My Add-ins → Incorta.
  • In the Office Add-ins dialog
    • Select Shared Folder. If Incorta is not listed in the dialog, select Refresh in the upper right corner.
    • Select Incorta.
    • Select Add.
  • If a dialog says that the Incorta Add-in loaded successfully, select Got It.
  • In the ribbon, select the Home tab.
  • In the Home ribbon, in the Incorta group, select Show to open the Incorta Excel Add-in Login panel.
Note
  • To use the Incorta Excel Add-in on Windows, you must have Microsoft 365 16.0.13530.20424 on Windows 10 version 1903 or later. You must also have Microsoft Edge with WebView2 (Chromium-based).
  • If you would like to simplify the installation process for multiple users, you can host the manifest file in a shared folder. For more details, refer to Sideload Office Add-ins for testing from a network share.
Migrate Worksheets from an Older Incorta Excel Add-in for Windows Version

If you have been using Incorta Excel Add-in for Windows version 16.6 or earlier, you will need to migrate your workbooks. Migration ensures that data queries saved in workbooks using version 16.6 or earlier will be read by version 16.7 or later.

There are two installers available for the Migration Tool for Windows: 32-bit and 64-bit. To know which installer to use, you must first identify the version of Excel that you are using.

Identify the Version of Microsoft Excel

  • Open Microsoft Excel.
  • In the Home menu, in the Sidebar, select Account.
  • In Account, in Product Information, select About Excel.
  • In the About Microsoft Excel dialog, the product name contains the Build version that indicates 32-bit or 64-bit.

Download the Migration Tool

Run the Installer

To run the Installer for the Incorta Excel Add-in for Windows, follow these steps:

  • If Excel is open, close Excel.
  • Run Incorta_Excel_AddInSetup_16.6.1_<BIT_SIZE>.msi.
  • In the installer wizard, select Next>.
  • In Select Installation Folder, the default installation path is: C:\Users<YOUR_USER_NAME>\AppData\Local\Incorta Inc\IncortaExcelAddin\.
    • To accept the default folder for the Migration Tool installation, select Next >.
    • To specify a specific directory, select Browse. In Browse for folder, first select a folder, then select OK.
    • Select Next >.
  • In Confirm Installation, select Next >.
  • In Installation Complete, select Close.

Verify the installation

  • Open an old workbook in Microsoft Excel.
  • The following message will be displayed: Migration done successfully, please save the workbook and restart Excel.
  • Close and reopen the workbook.
  • Select Show in the Home ribbon. It should open the query that was previously saved in the workbook.
Use Sideloading to Install the Incorta Excel Add-in on macOS
  • Open Finder.
  • In the Finder Menu bar, select Go → Go to Folder....
  • Enter ~/Library/Containers/Microsoft Excel/Data/Documents/ and select Go.
  • If it does not yet exist, create the wef directory in the Documents directory.
  • Copy the Incorta Excel Add-in manifest file to the following directory: /Users/<YOUR USERNAME>/Library/Containers/Microsoft Excel/Data/Documents/wef.
  • Create a new Excel workbook or open an existing workbook.
  • In the ribbon, select the Insert tab.
  • In the Add-ins group, select the down arrow to the right of My Add-ins.
  • Select Incorta under the Developer Add-ins heading.
  • If a dialog says that the Incorta Add-in loaded successfully, select Got It.
  • In the ribbon, select the Home tab.
  • In the Home ribbon, in the Incorta group, select Show to open the Incorta Excel Add-in Login panel.
Note

To use the Incorta Excel Add-in on macOS, you must have Excel for Mac version 16.46 on macOS Catalina or later.

Excel Add-in Anatomy

The Excel Add-in consists of the following:

  • Header bar
  • Login panel
  • Schemas and Tables panel
  • Pivot/Table panel
  • Search bar
  • Footer bar

Header bar

The header bar is used to:

  • Navigate from one panel to the next (forward arrow), or navigate back to a previous panel (back arrow).
  • Configure the Excel Add-in settings that appear on two tabs: General Options and Pivot Layout.

Here are the properties on the General Options tab:

PropertyControlDescription
Max Rowstext boxEnter the maximum number of rows that will be populated in Excel with data from Incorta. The default is 1048575.
Max Uniques to show in filter drop downtext boxSelect the maximum number of unique values that will appear in a filter drop down. The default is 100.
Cells per Pagetext boxEnter the number cells per page. The default is 1000000.
Enable Sheet ProtectiontoggleEnable this property to make the data in the Excel sheet read-only
Enable Cancel While LoadingtoggleEnable this property to allow the user to cancel the data load from Incorta to Excel while it is in progress
Reset WarningsbuttonSelect this property to reset warnings
ClosebuttonSelect this property to close the settings properties

Here are the setting properties on the Pivot Layout tab:

PropertyControlDescription
Row TotaltoggleEnable this property to include a row total in all pivot tables
Row Total Atdrop down listSelect the location of the Row Total. The options are:
  • Top
  • Bottom
Column TotaltoggleEnable this property to include a column total in all pivot tables
Column Total Atdrop down listSelect the location of the Column Total. The options are:
  • Left
  • Right
Hide ColumnstoggleSelect this option to hide the pivot table columns
Merge ColumnstoggleEnable this property to merge pivot table columns
Merge RowstoggleEnable this property to merge pivot table rows
ClosebuttonSelect this property to close the settings panel

Login panel

The login panel is used to connect to Incorta from Excel. Here are the properties for the Login panel:

PropertyControlDescription
Incorta URLtext boxEnter the URL of your Incorta instance in the format https://<Incorta Host>:<Incorta HTTPS
Port>/Incorta
Select Continue to enter the remaining login properties.
Tenanttext boxEnter the name of the Incorta tenant you would like to connect to
Usernametext boxEnter the username for the Incorta tenant
Passwordtext boxEnter the password for the Incorta tenant
Single Sign OncheckboxSelect this property to login with Single Sign On
ClearbuttonSelect this property to clear the login credentials
ConnectbuttonSelect this property to connect to the Incorta tenant with the login credentials

Schemas and Tables panel

The Schemas and Tables panel is used to select the Incorta schemas and tables you would like to analyze within Excel. Here are the properties of the Schemas and Tables panel:

PropertyControlDescription
Schemas and Tables Data paneltree viewSelect the Incorta schemas and tables you would like to analyze within Excel
ClearbuttonSelect this property to clear the schema and table selections
AnalyzebuttonSelect this property to confirm the schema and table selections, and to open the Pivot/Table panel

Pivot/Table panel

The Pivot/Table panel is used to select the type of table you would like to use to view your data, and to select the Incorta data fields. Here are the properties of the Pivot/Table panel:

PropertyControlDescription
Pivot/Table Data paneltree viewSelect the Incorta data fields you would like to add to your table
Filtersdrag and dropDrag and drop a data field to this panel to create a filter for your table
Columnsdrag and dropDrag and drop a data field or select it in the data panel to add a column to your table
Rowsdrag and dropSelect Pivot as the Table type to configure this property. Drag and drop a data field to this panel to add a pivot table row.
Valuesdrag and dropSelect Pivot as the Table type to configure this property. Drag and drop a data field to this panel to add a pivot table value.
Table typeradio buttonSelect the type of table you would like to use to view your data. The options are:
  • Table
  • Pivot
Exclude from Refresh AlltoggleEnable this property to prevent a refresh of your table data when you select Refresh All in the Home ribbon
ClearbuttonSelect this property to clear the field, filter and column selections
SavebuttonSelect this property to save the field, filter and column selections
RefreshbuttonSelect this property to refresh the Pivot/Table Data panel

The Footer bar can be used to view information about the Incorta Excel Add-in. Select About to view the following details: Incorta URL, Tenant, User Name, Excel API Version, and Build Number.

Connect to Incorta with the Excel Add-in

Here are the steps to connect to Incorta with the Excel Add-in:

  • Open the Incorta Excel Add-in Login panel.
  • Enter the Login panel properties.
  • Select Connect. When you connect to Incorta successfully, the Schemas and Tables panel will open and a Connection Successful message will be displayed in the panel.

Access Schemas and Tables in Excel

After you successfully connect to Incorta, you can access your tenant schemas and tables in the Schemas and Tables panel with the following steps:

  • Navigate the directory tree as necessary to select the desired schemas and tables. You can enter a string in the Search text box above the directory tree to filter the directory tree to the schemas and tables matching your search string.
  • Select Analyze.

Create a Table or Pivot Table in Excel

After you select the schema(s) and/or table(s), the Pivot/Table panel appears. Here are the steps to create a table or pivot table:

  • Choose the fields to add to your report. You can either drag and drop fields to the appropriate panel, or highlight the panel and select the field to add from the tree above:
    • Use the Columns panel to add a column to your table.
    • Use the Filters panel to add a filter to your table.
    • For pivot tables only, use the Rows panel to add a row to your pivot table.
    • For pivot tables only, use the Values panel to add a value to your pivot table.
  • You can switch between tables and pivot tables by selecting the associated radio button near the bottom of the Pivot/Table panel.
  • Select Save to save the query to the current worksheet.
  • Select Refresh to fill the active Excel worksheet with the query results.
Important

To retain the query in Excel, you must save the Excel file before you close it.

Drill Down in a Pivot Table

You can drill down from a value in a pivot table to view the underlying data that comprises the aggregated value. Here are the steps to drill down in a pivot table:

  • Open an Excel workbook that contains a pivot table you created with the Incorta Excel Add-in.
  • Select a cell in the pivot table.
  • Right-click and select Incorta → Drill Down.
  • Another worksheet will open with the underlying data details.

Additional Information

Upgrade the Incorta Excel Add-in Server

Your system administrator can upgrade the Incorta Excel Add-in on the server. Update the following directory with the new add-in ZIP file: <INCORTA_INSTALLATION_PATH>/IncortaNode/runtime/webapps/incorta/external-add-ins/excel

Note

You may need to restart Excel for the upgrade to take effect.

On occasion, a new Incorta Excel Add-in may require an upgrade to the manifest file. In this situation, you will need to download the manifest file and update it on your local machine.

If you upgrade your Incorta instance, you will need to reinstall the Incorta Excel Add-in on your server.

Support Several Incorta Instances with One Add-in

By default, the Incorta server Excel Add-in is designed to work on the Incorta instance you install it on. For the Excel Add-in to work on several other instances of Incorta, the system administrator can follow these steps:

  • Install the Incorta Excel Add-in on all other instances that you want to support.
  • Edit the manifest.prod.xml file on the main Incorta instance. The file is located in the following directory: <INCORTA_INSTALLATION_PATH>/IncortaNode/runtime/webapps/incorta/external-add-ins/excel/
  • After the SupportUrl element and before the Hosts element, add an AppDomains element and an AppDomain element for each domain you need to add. Refer to the AppDomain element document for further information. For example, if you would like to support two additional domains, you would add the following:
<AppDomains>
<AppDomain>https://myappdomain.com:9999</AppDomain>
<AppDomain>https://subdomain1.myappdomain2.com</AppDomain>
</AppDomains>

If you have deployed the Add-in before, increment the least significant part of the Version element. For example, if the version is 16.7.0.0, change it to 16.7.0.1.

  • In order to connect to the new domains from the client Incorta Excel Add-in, you will need to download the manifest file and update it on your local machine.
  • An upgrade to the Incorta Excel Add-in server may also upgrade the manifest.prod.xml file. In this situation, you will need to add the AppDomains again, download the manifest file, and update it on your local machine.