(Outdated) Data Import Dialog

The Import Wizard described in this article is outdated. We offer a new user interface for importing data called the Data Center.

There are two different ways to import your data into Soley Studio or Soley Desk. You can use…

  1. the data import dialog (Soley Desk and Soley Studio)
  2. different kinds of Import functions (Soley Studio only)

The data import dialog allows you to import data from Excel or CSV-files in an interactive way. However, the import process can only be partially automated. You can learn all about the data import dialog by watching this video, which is part of the Soley Desk Getting Started playlist. Below, you will find the same information in written form.

To use the data import dialog, you need to be on an open graph file. It does not matter whether the graph is empty or already contains data. In the latter case the imported elements will be added to the existing elements. To start the data import dialog, select the “Import from file” button at the top menu bar as shown in figure 1.

Open the Import Wizard by clicking on the "Import from file" button (red)
Figure 1: Open the data import dialog by clicking on the “Import from file” button (red)

You will then need to select an Excel or CSV file containing your import data. Next, the data import dialog starts. In the following we describe…

  • how to import nodes from a list using the data import dialog
  • how to import edges from a list using the data import dialog
  • how to import edges from a matrix using the data import dialog

How do I import nodes using the data import dialog?

In the following example, we want to import nodes of different classes (Part, Product and ProductFamily) with multiple attributes from an Excel file. The steps are visualized in the screenshot and described below.

Screenshot of the Import Wizard used to import a list of nodes
Figure 3 Importing a list of nodes with the data import dialog

First click on Import from file (see Figure 1) and select the Excel file. Then proceed as follows:

  1. Select what would like to import. You can choose between importing nodes or edges by clicking “Add a list of nodes”, “Add a list of edges” or “Add edges from an adjacency matrix”. After selecting “Add a list of nodes”, the window on the right-hand side opens automatically (see steps 2-4).
  2. Select the worksheet in which your data is stored using the drop-down menu. In the shown example, we want to import nodes of the node classes Part, Product and ProductFamily and map the columns to attributes. The classes and their attributes have to be defined in advance in the metamodel. After selecting the worksheet, the table with all its rows and columns is shown in the “Data Area” window.
  3. Pick a Node class. Every row of the selected data area (see step 5) will be imported as a node of the defined class. Only the classes defined in the metamodel of your graph file are available for selection. If the first selected column of the data area contains the node class name in the exact same writing as defined in the metamodel, you can simply pick the option Read from first selected column. The node class of each row is then automatically identified, allowing for the creation of nodes of different classes.
  4. (Optional) Manually map the columns to attributes of the node class using the dropdown menus on top of the data area. Note that you can only pick attributes of the selected node class which are defined in the metamodel. In the example, we map column A to the attribute id, column B to the attribute name and so on. Not every column has to be mapped to an attribute. If you select –None– in the dropdown menu, the values of this column will not be imported.
  5. Define the import data area. Only the marked selection (blue area) of the data area is imported. By default, the whole table is marked. You can also manually select the data area you want to import by dragging over the cells or you can mark a starting cell and use the Select all rows and/or Select all columns buttons.
  6. By clicking OK, the nodes will be imported to the graph file you are operating on. Instead of clicking OK right away you can also add further import steps by starting over with step 1 (see next section).

Carrying out several import steps in one go

With the data import dialog you can do several import steps in one go, e.g. to import several data areas from one worksheet or to import data from different worksheets. However, all data has to be part of the same data file. To add another import step simply start over with the steps 1-5. Select Add a list of nodes, Add a list of edges or Add edges from adjacency matrix. You can jump back and forth between import steps in the list on the left side of the data import dialog to change the import settings. By unchecking the checkbox in the list, you can exclude a defined import step.

Multiple Imports in one swoop
Figure 4 Carrying out multiple imports in one go using the data import dialog

In the example, the data for all three node classes (Product, Part, ProductFamily) is stored in the same table in the “Bill_of_Materials” sheet. Thus, we can add three lists of nodes (one per node class) and select the correct data area for each class. This can be eased by sorting the rows of the table according to the node class. Alternatively, we can split up the table and create one worksheet per node class. A third option would be to create a table column which contains the exact node class names and use the “Read from first selected column” option in the data import dialog window.

Note that the column containing the node class names does not have to be the first column of the table, but the first column (on the left-hand side) of the selected data area. In this way, we can import nodes of different classes from the same table without manually selecting the data area for each node class. If you import nodes and edges in one go, make sure that the tick for “Import all nodes first” is set (see figure 4). This ensures that all edges can be built, as no source or target nodes are missing.

Autodetect attribute mapping option

If the first row of your data area contains the attribute names in the exact same writing as in the metamodel, you can simply use the autodetect attribute mapping function by ticking the small checkbox at the bottom right side of the data import dialog window. This will automatically map the columns to your attributes, meaning that you do not have to carry out step 4.

Automatic Attribute Mapping Import Wizard
Figure 5 Using the “Autodetect attribute mapping” option of the data import dialog

The left side of figure 5 shows the settings in the data import dialog window. The right side shows the resulting properties of the imported node with the name “Shift Lever City”. The attribute names of the columns with the green ticks in the header row are equal to those defined in the metamodel, whereas the red crosses indicate that the row headers do not correspond exactly to the metamodel. As we can see from the imported attribute values in figure 4, the autodetect function requires an exact equivalence of the column headers of the worksheet and the attribute names defined in the metamodel. (in case you wonder: the quantity value of every node was set to 1 by default)

Transpose data option

Import Wizard Transpose Data Function
Figure 6: Using the “Transpose data” option of the data import dialog

The data import dialog imports every row of the data area (blue in figure 6) as one graph element. Figure 6 shows an example in which we would like to import each table column as a node and map the rows to attributes. The first column of the data area contains the attribute names. In this case, we can simply use the “Transpose data” option in the data import dialog window. Checking this box will transpose the data in the data area window and we can proceed as presented before.

Save the data import dialog settings for easy re-use

The data import dialog allows for saving the import settings for later reuse. Just select the tick box Save import settings to file as shown in Figure 2 when setting up the import for the first time. If you want to carry the same import out again open the import settings file (*.sldi file) from where you stored it and the data import dialog will open with the saved settings. You can then also change the import settings and, if wanted, save the import settings to a new file or overwrite the existing one.

Save Import Settings
Figure 2: Save Import Settings

How do I import edges using the data import dialog?

You can import edges from files or databases structured as (adjacency) matrix or table/list. Edges always need a source and a target node (which can be the same node). Thus, edges can only be created if nodes already exist in the graph or are imported in the same import process. To import edges, the importer has to know:

  1. (optionally) a class name of an edge to be created,
  2. a class name of a source node,
  3. an identifying attribute name of a source node,
  4. an identifying attribute value of a source node,
  5. a class name of a target node,
  6. an identifying attribute name of a target node,
  7. an identifying attribute value of a target node,
  8. (optionally) if any values have to be mapped to edge attribute values

The arguments 2-7 are called source/target identifiers and MUST be provided in some form. This form differs for an import of tables or matrices, as described in the following. In the subsequent examples, we want to import nodes of the node classes Part and Product (each with their “id” attribute) from a node list and edges of the class Contains with the attributes “label” and “quantity” – both in one swoop. All node and edge classes as well as their attributes have to be defined in advance in the metamodel. Therefore, we initially select “Add a list of nodes” in the data import dialog window (just as described above). We can import edges by either selecting …

  • “Add a list of edges” or
  • “Add edges from an adjacency matrix”.

Both options are explained and depicted subsequently.

Import edges from a list

When importing edges listed in a table, each row is imported as one edge. The steps we need to take in order to import edges from an Excel list are shown in figure 6. Having the edge data as list is rather rare due to the predefined data scheme required. It is more common to built edges using rules or by importing them from matrices.

Importing edges from a list
Figure 7 Importing edges from a list
  1. Select “Add a list of edges” in the drop-down menu. The window on the right-hand side opens automatically (see steps 2-6). Remember that edges can only be built if source and target nodes already exist in the graph or are imported in the same process.
  2. Select the worksheet in which your data is stored. After selecting the worksheet, the list with all its rows and columns is shown in the Data Area window.
  3. Pick an edge class. Every row of the data area (cells marked in blue in figure 7) will be imported as an edge of the selected class. Only the classes defined in the metamodel of your graph file are available for selection. If the first selected column of the data area contains the edge class name in the exact same writing as defined in the metamodel, you can simply pick the option “Read from first selected column”. Thus, the edge class of a row is automatically identified. This option is especially important when you want to import edges of multiple different classes from the same table. In case you chose the edge class from the dropdown menu, you can exclude the first column of the list in figure 6 from the data area (column A).
  4. Define the source and target node class and identifying property using the drop-down menus. Only if your table is structured exactly like in figure 6 (see black framed data area), you can simply select the “Read from worksheet” option for all four fields of the “Source and Target Nodes” definition section.
  5. Map the columns for the Source Identifier and the Target Identifier using the drop-down menus in the column headers. This sets the source node´s identifying attribute and the target node´s identifying attribute. Figure 8 shows the settings in case the Excel table contains only these identifying columns (red frame).

    Example of an edge import from a "minimum" content table
    Figure 8: Example of an edge import from a “minimum” content table
  6. (Optional) Manually map columns to attributes of the edge class. Note that you can only map to attributes of the selected edge class defined in the metamodel. If the headers of the columns containing the edge attributes have the exact same writing as the attributes defined in the metamodel, you can select the Autodetect attribute mapping option (see green frame in figure 7). If, however, the writing differs, the columns have to be mapped manually to the edge attributes using the drop-down menus in the column headers (see see green frame in figure 8). Not every column has to be mapped to an attribute. If you select –None– in the dropdown menu, the values of this column will not be imported.
  7. Define the import data area. Only the marked selection (blue area) of the data area is imported. By default, the whole table is marked. You can also manually select the data area you want to import by dragging over the cells or you can mark a starting cell and use the Select all rows and/or Select all columns buttons. If you are importing nodes and edges in the one go (e.g. the source and target nodes are not yet in the graph), make sure that the tick at Import all nodes first is set. Otherwise, the edges cannot be built. By clicking OK, the edges will be imported to the graph file you are operating in. The result is shown in figure 10.

Import edges from an adjacency matrix

When importing edges from a matrix, each matrix cell containing a value different from 0 (or empty) is imported as one edge between the source node (row of the matrix) to the target node (column of the matrix). The source/target node´s identifying attribute MUST be provided in the row/column header of the matrix. The steps we need to take in order to import edges from an adjacency matrix are shown in figure 9. However, to import the edges represented in the matrix you first need to create the source and target nodes. This can done by importing the header row and header column of your matrix as a list of nodes, as explained in the first part of this article. Only after that you create the edges by importing the matrix cells that represent the relation.

Import the header column as list of nodes

Step 1 of importing a matrix - Import header column as nodes

  1. Click on the “Add a list of nodes” button on the top left.
  2. This will activate the right part of the window where we can start with selecting the Worksheet to import from.
  3. To import the rows as nodes, which in our example represent part nodes, we select Part as Node class to be imported to. Note that you can only use node classes that have been defined in your metamodel!
  4. Next, we use the property drop-down menu in column A to tell the tool what property value the column contains. In our case name. Note that the drop-down menu will only show the properties available for the node class you selected.
  5. Then we select the data area that should be imported. In our case, this is A2 to A5. That was it for the Part nodes.

Import the header row as list of nodes

Note that if your matrix is diagonal, meaning the header row and header column contain the same data, you only need to import one list of nodes. In this case, you can directly go to the import the cells as edges.

Step 2 of importing a matrix - Import header row as nodes

  1. Click on the “Add a list of nodes” button on the top left again.
  2. Selecting the Worksheet to import from.
  3. To import the header row as nodes, which in our example represent product nodes, we select Product as Node class to be imported to.
  4. As the data import dialog always imports rows as nodes we need to transpose the matrix using the Transpose data checkbox.
  5. Next, we use the property drop-down menu in column A to tell the tool what property value the column contains. In our case we select name.
  6. Then we select the data area that should be imported. In our case, this is A2 to A4. That was it for the Product nodes.

Import the cells as edges

Step 3 of importing a matrix - Import cells as edges

  1. Select Add edges from an adjacency matrix. The window on the right-hand side opens automatically (see steps 2-5). Remember that edges can only be built if source and target nodes already exist in the graph or are imported in the same process.
  2. Select the worksheet in which your data is stored. After selecting the worksheet, the matrix with all its rows and columns is shown in the “Data Area” window.
  3. Pick an edge class. Only the classes defined in the metamodel of your graph file are available for selection. Per matrix, only edges of one class can be imported. The reading direction of the importer is “from row to column and from top to bottom”. In our example, each matrix cell containing a “1” will be imported as an “Contains” edge from a Product to a Part.
    Info: If you would like to build the edges vice versa, e.g. from the parts to the products, you can transpose the matrix by setting the tick in the “Transpose data” checkbox. Make sure to adjust the respective source and target node information correctly (see 4.)
  4. Define the Source and Target Nodes settings in the drop-down menus. In the drop-down Property mapping, you can define which edge attribute the values in the matrix cells shall be attached to. In the example shown in figure 8, the cell values will be imported as “quantity” of the Contains edges.
  5. Define the import data area. Only the marked selection (blue area) of the data area is imported. By default, the whole table is marked. You can also manually select the data area you want to import by dragging over the cells or you can mark a starting cell and use the Select all rows and/or Select all columns buttons. If you are importing nodes and edges in the one go (e.g. the source and target nodes are not yet in the graph), make sure that the tick at Import all nodes first is set. Otherwise, the edges cannot be built. Important: Your data area needs to include the header row and header column as first row and first column of the selection. This row and column will be used as source node identifying attribute value (header row) and target node identifying attribute value (header column).

We are now done with defining the import. Once we click on “OK” the data import dialog will create all Part nodes, all Product nodes and the Contains edges between them. The resulting graph could look like this:

Graph resulting from the import of a matrix.

To carry this process out automatically you can use library elements to import matrices with attributes.

Was this article helpful?

Related Articles