Skip to main content

Formatting a CSV for import

Prepare your data!​

To ensure Alloy can understand and process your import data, check that your CSV file is formatted correctly before uploading it.

The data can be spread across multiple CSV files if necessary, which can all be selected for a single import. Their combined data will be used to create, update, or replace items of the destination design.

Headers​

The first row in a CSV file is the header row. Like the top row of a table, each value acts as a title for its respective column. There should be a column, and therefore a header value, for each of the attributes you want to import.

AttributeHeader1AttributeHeader2AttributeHeader3AttributeHeader4

Where possible, the header values should match the attribute names on the destination design. This gives Alloy the best chance to automatically associate the headers in your CSV file with the correct attributes on the design.

For attributes with similar names, you can use their unique attribute code instead:

attributes_myDesignMyAttribute_668ff0552a2b558794880c28

Attribute values​

The data values in each column will be used to populate the corresponding attribute on items of the destination design. Therefore, make sure those values are valid for that attribute and meet any of its configured constraints.

For example, a Date attribute won't accept a date and time value. A Text attribute may only accept text under a certain length. A Number attribute may only accept numbers within a min/max range or with two decimal places.

Required attributes​

If an attribute has its Required property enabled, it must have a value. Therefore, make sure each row in the CSV file contains a value in that attribute's column. If this isn't the case, you can edit the attribute and set a Default Value that it can fall back to.

Optional attributes​

If an attribute isn't required, it's fine for rows to not contain a value in that attribute's column. If a row lacks a value, and the attribute doesn't have a Default Value set, the attribute will be empty on the corresponding item.

Dates and Times​

Alloy only accepts date and time values written in ISO-8601 format. This means:

Geometry​

A geometry value can be supplied in three formats. Make sure it only contains geometry types that are allowed by the destination design (or by a custom geometry attribute).

X1, Y1

Supply Point geometry by splitting its coordinate values into two columns.

x1y1
-3.64201150.901943
X1, Y1, X2, Y2

Supply simple LineString geometry by splitting the start (X1, Y1) and end (X2, Y2) coordinate values into four columns.

x1y1x2x2
-0.49630452.653144-0.493272,52.651342
GeoJSON or WKT

Supply complex geometry values in GeoJSON or WKT format. The code must be written as a single line.

GeoJSON
{"type":"Polygon","coordinates":[[[-0.496427,52.651486],[-0.495687,52.651675],[-0.495486,52.651392],[-0.49622,52.651197],[-0.496427,52.651486]]]}
WKT
POLYGON ((-0.496427 52.651486, -0.495687 52.651675, -0.495486 52.651392, -0.49622 52.651197, -0.496427 52.651486))

Link attributes store references to items, so make sure the values in the relevant header column are Item IDs. If a Link attribute supports multiple items, a value can include multiple Item IDs separated by a | symbol:

617685a3b0b6f4dda85d0b5a|617685a3b0b6f4dda85d0b5b|617685a3b0b6f4dda85d0b5e

Alternatively, you can populate a Link attribute with compatible items according to the value they hold in a specific attribute. When you configure the import, you can specify the Attribute to match in the 2 Attributes step of the process.

If an imported item needs linking to an existing parent item (e.g. a component for a parent asset), include the parent's Item ID in the corresponding row of a separate column in the CSV file. Alternatively, you can match an imported item to one or more parents, according to the value they hold in a specific attribute.

When you configure the import, you can select this column in the 5 Parents step of the process and set Match link by to Item id or Attribute.

Update specific items​

To apply a row of import data to a specific existing item, include its Item ID in a separate column in the CSV file. When you configure the import, you can select this column in the 1 Destination step of the process (if Mode is set to Update or Merge).

Example CSV​

Click below to download a basic example CSV file. It contains a column for each attribute type, plus columns for storing parent IDs and Item IDs as described above. Geometry values are in GeoJSON format. The file demonstrates how data should be formatted.

While it can be used as is, the IDs will need replacing as they don't exist on your customer project! We recommend creating a practise design containing the relevant attributes, so you can easily bulk delete imported items when you're done.