> For the complete documentation index, see [llms.txt](https://documentation.ardoq.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://documentation.ardoq.com/integrations/out-of-the-box-integrations/excel.md).

# Excel

Learn how to use the Excel integration to import .xls, .xlsx, .xslm, or .csv files and quickly add or update data in Ardoq.

## Pre-requisites <a href="#h_9a32bcfdb9" id="h_9a32bcfdb9"></a>

1. Get familiar with the [basic concepts](/integrations/integrations/introduction-to-ardoq-data-imports.md) in Ardoq
2. Download the [Excel sample file](https://cdn2.hubspot.net/hubfs/4022333/Intercom%20Knowledge%20Base%20Assets/Applications.xlsx) used in this article

{% hint style="info" %}
**Video Tutorial**\
You can watch a short guided tutorial on importing an Excel file on [our YouTube channel](https://www.youtube.com/embed/y-BmFCHTZ-w?rel=0).
{% endhint %}

## Overview

The Excel integration enables you to translate a tabular dataset such as an Excel spreadsheet to a graph representation in Ardoq. This is done by mapping your tabular data so that it fits into your Ardoq metamodel.

**Mapping allows you to**:

* Flexibly generate Ardoq metamodels based on your Excel data
* Define the workspaces that data will be imported into
* Map columns in Excel to provide additional details like descriptions, tags, fields,and component types
* Create references between the components defined in your worksheets
* Test your import and verify that your Excel data is consistent with your mappings (i.e. check that the data type is correct with your field mapping)

You can also use the Excel integration to update existing data in Ardoq. This is a great option for doing bulk updates or changes.

## Setting Up Your Worksheet

The [Excel sample file](https://cdn2.hubspot.net/hubfs/4022333/Intercom%20Knowledge%20Base%20Assets/Applications.xlsx) provides an example of how your should structure your Excel spreadsheet for import into Ardoq.

Each worksheet should represent either a set of components or a set of references between components. Ardoq requires each worksheet to be configured separately.

{% hint style="info" %}
**Leaving Sheets and Columns Unmapped**\
Unmapped sheets and columns will be skipped during the import process and will not be imported into Ardoq.
{% endhint %}

In our sample Excel file, we have the following structure:

* **Components**:
  * Applications
  * Business-units
  * Capabilities
* **References**:
  * BU → Applications
  * Capabilities → Applications

**Note**: The `→` symbol is a short-hand to symbolize a reference between components. It has no functional impact on the importing or mapping process.

### Workspaces

Workspaces define the repositories where components will live. Each worksheet can have its components imported into a unique workspace or you can use a single workspace to store all your components.

You'll have the option to create or re-use workspaces for each worksheet in your Excel import.

References, unlike components, can connect a source and a target workspace together. This allows you to create references between components in different workspaces. You can also have the source and target workspace be the same workspace and make connections between components in the same place.

### Components

Each row in a sheet — excluding the first header row — will be mapped to create a component in Ardoq.

Components are given more details by mapping each column in the sheet to a different type. For example, some common types include:

* Component name: The name of the component in Ardoq.
* Description: The main content providing text details about a component.
* Tags: Additional information to allow you to filter your components in Ardoq
* Import ID: We recommend adding an ID column for the items you wish to import. Using IDs reduces the likelihood of mixing up components with similar names.
* Custom field: Ardoq supports custom fields with types like Date, Number, Lists, Select Multi, Checkboxes and Tags. These values
  * Use commas to separate multiple values in Tags and Select Multi lists.

#### Hierarchy of Components <a href="#h_fd2caf4fbb" id="h_fd2caf4fbb"></a>

You can indicate a hierarchy in your import by assigning multiple Component name types to your columns.

For example, if you have a parent application column, setting that column to be of Component name type will automatically give it a hierarchy level of 1. If you have a child application column related to the parent, you can also set it to be of the Component name type, and its hierarchy level will be set to 2, indicating that it is a child component.

<div data-with-frame="true"><figure><img src="https://2484004798-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FnlnB7uZ29iLVLzqGbCym%2Fuploads%2F1MwnjTUIIwlUZVq5w2xN%2Fimage.png?alt=media&amp;token=03c5ee3b-8ac1-4c50-aaf6-3241210ab719" alt=""><figcaption></figcaption></figure></div>

When creating this import, Ardoq will create two components from a single row: one component from the parent and one component from the child.

### References

References express how components relate to each other and can take many forms. Some common references include:

* Business Unit A owns Application B
* Alice manages Bob
* X licenses Y

When importing references, you need to define a source workspace and a target workspace. The source and target workspace can be the same workspace.

With that defined, you can establish the sort of relationships exist between the components in those workspaces. This is done by specifying columns as Source and Target types, as well as adding a Type column type to specify the relationship name.

You can do this in two ways:

1. Specify source and target components using Custom IDs defined in other worksheets.
2. Using a fully-qualified path using the `::` notation to denote a level. For example, `SaaS::Intercom`.

## Importing Your Data <a href="#h_8a649c9c34" id="h_8a649c9c34"></a>

1. From the main menu, navigate to Imports & Integrations
2. Click on **Create new** in the top-right corner and select **Excel**
3. Upload your Excel or CSV file
4. Begin mapping your components and references in the **Configure Data** step

### Configure Data Step <a href="#h_ab93268ba2" id="h_ab93268ba2"></a>

In the next steps, we'll use the sample Excel file as the basis for creating our components and references.

{% hint style="info" %}
**Navigating Tabs during Import**

Every step of your configuration process is saved as you perform your mapping. Feel free to navigate between tabs if you need to recall field names or to reconfigure data elsewhere.
{% endhint %}

#### Mapping Components <a href="#h_7fd4cadb18" id="h_7fd4cadb18"></a>

**Applications Tab**

1. Set your worksheet to **Components**
2. Create a new workspace called **New Applications**
3. Configure the **Name** column as a **Component name** column type
4. Configure the **Application ID** column as a **Custom ID**

**Business Units Tab**

1. Set your worksheet to **Components**
2. Create a new workspace called **New Business Units**
3. Configure the **Name** column as a **Component name** column type
4. Configure the **ID** column as a **Custom ID** and set the field name to **BU-ID**

#### Mapping References <a href="#h_2e53c65a05" id="h_2e53c65a05"></a>

**BU → Applications Tab**

1. Set your worksheet to **References**
2. Set your **Source component** workspace to the previously-created **New Business Units**
3. Set your **Destination** component workspace to the previously-created **New Applications workspace**
4. Set the **BU** column to the **Source** column type, set the Format to **Custom ID**, and set the Field name to the **BU-ID** field we created earlier
5. Set the **Application** column to the **Target** column type, set the **Format** to **Custom ID**, and set the Field name to **Application ID**
6. Set the **Reference** type column to the **Type** column type
7. Finally, click the **Next: Review import** button to proceed

### Review Import Step <a href="#h_7c730d1e26" id="h_7c730d1e26"></a>

This step will perform validation on your column mapping and warn you if there are any problems that make the data import impossible.

In our case, our mapping is correct, and we should be able to execute our data import.

<figure><img src="https://2484004798-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FnlnB7uZ29iLVLzqGbCym%2Fuploads%2FkMbDl8FopMu1vXf9EkLY%2Fimage.png?alt=media&amp;token=81cfc0fc-ddef-49e8-ad66-0b50d47aa359" alt=""><figcaption></figcaption></figure>

We can also double-check our metamodel structure by using the **Metamodel** tab:

<figure><img src="https://2484004798-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FnlnB7uZ29iLVLzqGbCym%2Fuploads%2FpNb7MAsONsHpF904I6nZ%2Fimage.png?alt=media&amp;token=56f514a7-6b1d-411b-b054-d0352b4605d4" alt=""><figcaption></figcaption></figure>

Click **Next: Import my data** to complete importing your Excel data into Ardoq.

### Saving Your Configuration <a href="#h_200e0bc672" id="h_200e0bc672"></a>

You can save your column mapping for use later by clicking the Save configuration button in the top-right corner of the import flow. You can think of saved configurations as templates for your data.

Saved configurations are useful if you're going to be importing new data using Excel sheets with the same structure. Returning to a saved configuration will automatically set the mapping of the Excel import to your last saved mapping.

## Considerations And Constraints <a href="#h_cd310974c2" id="h_cd310974c2"></a>

### Excel Mapping Limitations <a href="#h_6d378e45c8" id="h_6d378e45c8"></a>

Be aware that if you add or rearrange the order of worksheets in your Excel file, Ardoq will not preserve your structure or mapping.

In addition, the first row in your Excel sheet is considered to be a column header and will be ignored by the importer.

### Text paragraph fields <a href="#h_7c89662e9f" id="h_7c89662e9f"></a>

Text paragraph fields in Ardoq are rendered as Markdown. As a result, values imported into Text paragraph fields, especially line breaks, can look different than in Excel. In Ardoq's Markdown formatting, a line break is indicated by " \n" (two spaces followed by a newline). A new paragraph is indicated by "\n\n" (two consecutive newlines), as per standard Markdown practices, largely in line with the [CommonMark ](https://spec.commonmark.org/0.17/#hard-line-breaks)specification.

### Reserved Field Labels <a href="#h_39fce4b591" id="h_39fce4b591"></a>

Some field names are reserved for internal systems in Ardoq. If you are trying to map a field using a reserved field name, you'll get a warning and will have to choose a different name for the field.

### Workspace Permission Issues <a href="#h_43b1e35b9f" id="h_43b1e35b9f"></a>

The Excel importer is subject to permissions checks. This means that you cannot import into workspaces where you only have read permissions.

### Importing Multiple References using Commas <a href="#h_a7c472b9c6" id="h_a7c472b9c6"></a>

Using commas to import several references at once is currently possible for outgoing references from a Components sheet only. To create them: separate the components you wish to turn into multiple references by using commas.

<figure><img src="https://2484004798-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FnlnB7uZ29iLVLzqGbCym%2Fuploads%2F6W54BxU0J9VifeAMg7v2%2Fimage.png?alt=media&amp;token=7011a7c8-f338-47e0-bd8c-4c2cb238d914" alt=""><figcaption></figcaption></figure>

When mapping, you will see the **Item separator** field, which can be adjusted to fit your specific delimiters.

<figure><img src="https://2484004798-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FnlnB7uZ29iLVLzqGbCym%2Fuploads%2FRwMk2iGsnLg7zLsyq18L%2Fimage.png?alt=media&amp;token=7de6e331-4932-46f2-a7c1-7001b61c0458" alt=""><figcaption></figcaption></figure>