Import components from a CSV file

CSV file import is a quick way to add many components in bulk to Compass.

CSV files contain delimited text that represents tabulated data. Each line in the file is a record and a comma separates each field in that record. Most applications that support tabulated data, for example, Microsoft Excel, OpenOffice, and databases, support CSV files.

The CSV file import process involves:

1. downloading a sample CSV file from Compass
2. preparing your data in the CSV file for import
3. importing the CSV file into Compass

The import process adds new components to Compass and updates existing components that have changed.

Download a sample CSV file

Compass provides a sample CSV file to help you prepare your data for import.

To download a sample CSV file:

1. In the top navigation bar in Compass, select Create > Import components.
2. On the Import components dialog, select Import next to the CSV file option.
3. While you are on the Upload step in the import process, select Download example CSV.

The file downloads to your computer.

Prepare data in the CSV file

To prepare data in the CSV file, use the sample CSV file from Compass. Alternately, prepare your CSV file manually. The CSV file uses a predefined structure and formatting requirements. Learn more about the CSV file requirements

1. Open the CSV file.
2. Add the details of all your components in the CSV file. If you are using the sample CSV file from Compass, be sure to remove the sample data from the file.
3. Give the file a name you prefer and save it with a .csv extension to your computer.

Import the CSV files into Compass

Once you've prepared your data in the CSV file, you can import the file into Compass. The CSV import process guides you through file upload, validation, preview, and import. Once the import finishes, you can download an import log for your reference.

Before you begin

Ensure that your CSV file is well-formed and free of any errors. Learn more about the CSV file requirements

Import the CSV file

To import the CSV file:

1. In the top navigation bar in Compass, select Create > Import components.
2. On the Import components dialog, select Import next to the CSV file option.
3. Select and upload the CSV file from your computer.
   • The import process validates your file’s format. If there are any errors, fix those errors, and upload the file again.
4. Select Preview CSV import.
   • The preview shows how many components the process will create and update. It also shows how many components will remain unchanged.
5. Select Start import.
6. Once the import completes, select Download import logs to download the log file for your reference.
7. Select the close icon () from the top left corner to return to the component catalog.

After the import finishes, view your component's details to verify the information. It is a good idea to furnish all other details of the components. Add information such as the owner team, contacts, dependencies, links to resources, and more. Learn more about how to add or update a component's details

CSV file requirements

Header row

Each CSV file must have a header row, which must be the first row in the file. The CSV import process uses the header row to map data from the second row and beyond to a component’s details in Compass.

The column headings of the header row must be:

• name – a mandatory field that indicates the name of the component
• type – a mandatory field that indicates the component’s type
• description – an optional field that describes the component

The order of these columns is not fixed. You can interchange the sequence of the columns, but make sure you align the field values to the corresponding column headers.

Do not use any punctuations in the header row, apart from the commas separating each column.

For example, this is a valid header row:

1
2
name,type,description

Second row and onwards

The second row and onwards contain the field values that represent the component’s details.

Use one row per component. Make sure the field values follow the order of the header fields.

Commas as field separators

Separate each field with a comma, without any spaces between them.

Do not omit commas, even if you omit a value for an optional field, such as description.

For example, this is valid:

1
2
name,type,description
Component 1,SERVICE,

...but this is not valid:

1
2
name,type,description
Component 1,SERVICE

Treatment for special characters

Use double-quote marks (") around a section of text to treat any special characters in that section literally. Special characters include:

• double-quote marks
• commas
• carriage return/enter characters.

For example, if you want to use double-quote marks in your component’s description to say:

1
2
This is my "first" service.

...then the field value would look like this:

1
2
name,type,description
Component 1,SERVICE,"This is my ""first"" service.",

Notice the two pairs of double quotes here. You need them both to achieve the result you want.

Another example is for adding commas in your description to say:

1
2
This is my first, functional, and awesome service.

...then the field value would look like this:

1
2
name,type,description
Component 1,SERVICE,"This is my first, functional, and awesome service."

Or, if you want the description to span many lines and look like this:

1
2
This is my first service,
it's functional,
and it's awesome!

...then the field values should look like this:

1
2
name,type,description
Component 1,SERVICE,"This is my first service,
it's functional,
and it's awesome!"

Filename and extension

You can name the file as you like, but the file extension must be .csv, for example, component_import.csv.

Example of a well-formed CSV

Here’s an example of a well-formed CSV file that will create four components.

1
2
name,type,description
Component 1,SERVICE,My first component.
Component 2,LIBRARY,"My ""second"" component."
Component 3,APPLICATION,"This is my third component,
it's functional,
and its awesome!"
Component 4,OTHER,