Create and update components using a CSV file

Use a CSV file to quickly create and update many components at once.

What you can add to the CSV file

You can add a lot of component data to the CSV file. Some data are required; most are optional.

Required data

Optional data

How to format the CSV file

There are a few things to consider when you add and format component data in the CSV file.

Header row

Each cell in the header row represents the field name on a Compass component’s Overview page. These can be built-in or custom fields.

Spacing

If field names or field values have more than one word, add a space between each word.

Comma separation

If you’re not using an application that separates data by cells (like Microsoft Excel or Google Sheets), separate each piece of data with a comma.

For example:

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

Case-sensitivity

Built-in field names

Built-in field names, such as Name or Type, must be lowercase.

For example:

1
2
name,type,description
Component 1,SERVICE,Description 1
Component 2,LIBRARY, Description 2
Component 3,APPLICATION, Description 3

Custom field names

Custom field names are case-sensitive, and must match exactly how you’ve formatted them in the Compass settings.

For example:

1
2
name,type,custom:Audience size,custom:Platform
Component 1,SERVICE,Large,Facebook
Component 2,LIBRARY,Medium,Twitter

Field values

All field values are case-sensitive – except for component type values, which must be uppercase.

For example:

1
2
name,type,description,lifecycle stage
Component 1,SERVICE,Description 1,Active
Component 2,LIBRARY,Description 2,Pre-release
Component 3,APPLICATION,Description 3,Deprecated

Owner team

Owner team field values must include a prefix and a team ID: ari:cloud:teams::team/ID

To get an owner team prefix and ID:

1. In Compass, select Teams in the top navigation.
2. Select the team you want to get the ID for.
3. On the team page, select More actions > Copy owner ID.
4. Paste the owner team prefix and ID into the CSV file.

You should end up with something like ari:cloud:teams::team/781c0b6b-5167-4515-8517-d18563e0399e (with your trailing ID being different).

Custom fields

You can add all custom field types to the CSV file, but they need to be formatted in a particular way.

Prefixing custom fields

Prefix custom fields with custom:, and don’t include a space between the prefix and the custom field value – for example, custom:Platform.

Text custom fields

Text custom fields can be freely formatted, and can include numbers, symbols, and special characters.

Checkbox custom fields

Checkbox custom fields must have a value of either True or False.

Number custom fields

Number custom fields can only contain numbers.

User custom fields

User custom field values must include a prefix and a user ID: ari:cloud:identity::user/ID

Get a user ID if you're an admin

1. Go to admin.atlassian.com and select the organization that includes the user you want to get the ID for.
2. In the product row, select More actions > Manage users.
3. Select a user.
4. In the browser URL, copy the alphanumerical ID that appears after /users/, and paste it after the prefix in the CSV file (ari:cloud:identity::user/).

Get a user ID if you're not an admin

1. In Compass, select the quick-search field in the main navigation.
2. Type and select the user you want to get the ID for.
3. In the browser URL, copy the alphanumerical ID that appears after /people/, and paste it after the prefix in the CSV file (ari:cloud:identity::user/).

Whether you’re an admin or not, you should end up with something like ari:cloud:identity::user/5c527cd0cc3a1d3d8a2c015d (with your trailing ID being different).

Single-select custom fields

Single-select custom fields can only contain one value.

Multi-select custom fields

Multi-select custom fields can include multiple values, which must be separated by double pipes (see below).

Multiple field values

For fields where you can add more than one value (such as labels, links, or multi-select custom fields) separate each data point with a double pipe.

For example:

1
2
name,type,description,label
Component 1,SERVICE,Description 1,label1||label2
Component 2,LIBRARY,Description 2,label1||label3
Component 3,APPLICATION,Description 3,label1||label4

Create components using a CSV file

Get started

1. In the top navigation bar, select Create > Import components.
2. In the modal that appears, find the CSV file row and select Import.

Upload

1. Select the drop-zone, and choose a populated CSV file from your computer that includes up to 500 components. We’ll check that all the information is valid.
   • If the file contains more than 500 components, split the CSV file into two, and move any extra components to the second file.
   • If the CSV file doesn’t include required data – component name and type – you’ll have to go back and upload a file that includes that data.
   • If you include data in the CSV file that isn’t in Compass, or can’t be added from a CSV file, that data will be ignored.
2. Once you’ve confirmed the data that will be added to the components you’re creating, select Review.

Review and create

1. At the Review step, review how many components will be created or updated.
2. Select Create. It can take a few minutes for your components to be created.

Finish

1. At the Finish step, you’ll see how many components were created. If any errors occurred during creation, you can download an error log to get more details and help you fix the errors.
2. Select View components to see your new components on the Components page. They’ll include a csv-import label so you can easily find them later.

Update components using a CSV file

You can update existing components using the same steps as creating new components – but you’ll need to know how to update existing components, and when existing components will be ignored.

• If the component name and type in the CSV file matches a component in Compass with the same name and type, any other data you change about that component will be updated.

  • If you keep a field name in the header row, but remove any corresponding field values, those values will be removed from any existing components.

• If you remove a field name and its corresponding values from any component, that information won’t change on the existing component – because it hasn’t been included in the CSV file.

• If the component name is the same in the CSV file, but the type is different, any existing component with the same name will not be updated; that row in the CSV file will be skipped.

• If the component name and type in the CSV file matches multiple existing components in Compass with the same name and type, those components will not be updated; that row in the CSV file will be skipped.