[Reading time: 6 minutes]
Overview
This functionality allows you to bring your own data into INO CX, in order to analyse it in the Reporter alongside the data produced by the platform. This functionality is designed for supervisors, data analysts or administrators.
Unlike the other data sources, an external data source is not built on an existing element of INO CX. You define its columns yourself, then you fill it in, either by importing a CSV file or by adding the rows one by one.
1. Prerequisites
For an overview of the Reporter, please consult this article.
Prepare your data as a CSV file, with a header row whose headers are all different, and a size not exceeding 10 MB.
You also need the following permissions:
- Access to the Reporter, and the right to read data sources, in order to see the module.
- The rights to create and modify data sources, in order to create the data source, define its columns and manage its rows.
- The right to import, in order to import a file and to download the template file.
- The right to export, in order to generate an export.
Note: three limits apply per platform: the number of data sources, the number of columns per data source, and the number of rows imported into an external data source. The corresponding limits are ‘Number of data sources’ and ‘Amount of data imported into an external data source’.
2. Creating an external data source
2.1 Access this feature
To access this feature, go to the Reporter, click on the ‘Data sources‘ module and then select the ‘External data sources‘ category.
2.2 Create the data source
Click on ‘Create‘ to create a data source, then fill in the form:
- Name: required, 255 characters maximum.
- Description: optional.
- Data source type: select ‘External‘, which creates a data source from the data imported in INO CX.
Nothing else is required. Click on ‘Add the data source‘ to finish.
Note: the type cannot be changed after creation. Only the name and the description remain editable.
Open the data source you have just created. It is empty, and it already contains the three columns managed by the platform, described in the Columns section below.
2.3 Create a column
Click on the cogwheel at the top right, then ‘Create a new column‘, and fill in the form:
- Name: the name displayed in the interface. Required, 255 characters maximum.
- API name: required, 45 characters maximum, different from the other columns of the data source. This is the header expected in your CSV file, so choose it carefully.
- Type: the kind of value the column accepts, see the list below.
- Required: indicates that the column must be filled in.
- Unique: refuses a value already present in another row of the column.
Click to confirm. Repeat for each column you need.
The available types are:
- Short text: free text, 255 characters maximum.
- Long text: free text, 10 000 characters maximum.
- URL: a valid web address.
- Phone number: an international number, in the form +indicator followed by the number.
- Email address: a valid email address.
- Numeric: a number, decimals allowed.
- Date: a date in the YYYY-MM-DD format.
- Date + Time: a date and a time, in the YYYY-MM-DD hh:mm:ss format.
- Time: a time, in the hh:mm:ss format.
- Yes/No: a yes or no value.
Creating a column
‘Required’ is not available on ‘Yes/No’ columns. ‘Unique’ is not available on the ‘Yes/No’, ‘Date’, ‘Date + Time’ and ‘Long text’ types.
The type, ‘Required’ and ‘Unique’ are set once and cannot be changed afterwards. To change them, delete the column and create it again.
Modifying or deleting a column
To modify or delete a column, hover over its header, then use the pencil or the bin. Only the name and the API name can be modified.
If you change the API name of a column, remember to update the header of the files you import afterwards.
A column used by a key performance indicator, by a partitioning or as an active filter can be neither deleted nor hidden. The interface indicates the reason.
Note: deleting a column also deletes its values in every row, and this cannot be undone.
3. Filling in the data source
3.1 Download the template file
Click on the cogwheel, then ‘Download a CSV template‘. You obtain a file containing only the header row, built from the API names of your columns. This entry is available as soon as the data source has at least one column.
3.2 Import a CSV file
Click on the cogwheel, then ‘Import data‘:
- Choose the file. The origin is set to ‘File‘, the only option available. Select your CSV file, 10 MB maximum.
- Define the options. Choose the ‘Delimiter‘ used in your file, the semicolon or the comma. Then set ‘Import the data in case of errors‘: with ‘Yes‘, the valid rows are imported and the incorrect rows are returned in a CSV file. With ‘No‘, nothing is imported if a single row is incorrect. Check that the selected delimiter matches your file. The form proposes the comma by default, while the downloaded template file uses the semicolon.
- Define the correspondence. For each column of your data source, identified by its API name, select which column of your file fills it in.
- Define the filters, if you want to import only part of the file. Ten filters maximum.
- Click on ‘Save‘ to keep this configuration for your next imports, then on ‘Import the data‘ to start.
The data of the date type is set to the time zone of your platform settings.
Note: an import always adds rows. It never replaces the existing rows and never updates them. Importing the same file twice creates the rows twice, unless a column declared ‘Unique‘ refuses them. To replace the contents of the data source, empty it before importing.
3.3 import management
Once the import is started, a message indicates the number of rows being imported. The rows appear progressively in the interface.
To follow the progress and the result, go to ‘My Account‘, then to the ‘My imports‘ sub-tab. Each import displays its status, ‘In progress‘, ‘Error‘ or ‘Finished‘, and four counters: ‘Total lines‘, ‘Analyzed lines‘, ‘Lines excluded by filtering‘ and ‘Imported lines‘.
When rows have been rejected, click on ‘Download the report‘ to obtain the CSV file of the rows in error.
3.4 Add or modify a row manually
Click on the cogwheel, then ‘Add a row‘, and fill in the form, which is built from the columns you created. This entry is available as soon as the data source has at least one column.
To modify or delete rows, click on the rows concerned in the table. A counter indicates the number of rows selected, and the buttons above the table allow you to modify a row, when exactly one is selected, or to delete the selected rows.
To delete every row at once, click on the cogwheel, then ‘Empty data source‘.
4. Using the data
4.1 Select the period
When you open the data source, only the rows added during the current day are displayed. To see the rest, change the filter on the ‘Date added‘ column in the side panel, which opens automatically.
Note: for this type of data source, the filter on the addition date is always applied. It can be changed, but not removed.
4.2 Filter and adjust the columns
Click on ‘Add filter‘ to restrict the rows displayed. The number of results is updated accordingly.
On each column header, you can also filter, hide and, for the columns you created, modify or delete. Columns can be reordered by drag and drop. To display a column you had hidden, click on the cogwheel, then ‘Add columns‘.
Note: on the data source interface, hiding and reordering are not kept. To save your presentation, save the data source as an exploration.
4.3 Use the data
You have several options:
- Export the data (on the cogwheel): choose the decimal separator, a point or a comma, then confirm. The export is generated in the background. It becomes available on the ‘Exports‘ module after a few moments and remains available for 7 days. Only one export can be generated at a time.
- Save as an exploration (on the diskette): your current filters and columns are saved as a new exploration, which you can then use in the ‘Exploration‘ module and on your dashboards.
Note: on an exploration built on an external data source, the key performance indicators must be created from scratch, since no indicator template is offered for this type of data source. The partitioning tab is not available either.
4.4 Modify or delete the data source
From the tile of a data source, in the ‘Data sources‘ module:
- ‘Modify‘ allows you to change the name and the description.
- ‘History‘ displays the creations and modifications recorded on the data source and on its columns.
- ‘Delete‘ removes the data source permanently.
Note: deleting the data source also deletes all the rows it contains, and this cannot be reversed. A data source used by an exploration cannot be deleted. Delete the explorations built on it first.
4.5 Columns
Three columns are managed by the platform and cannot be modified.
- ID: the identifier of the row, generated at its creation.
- Date added: the date and time the row was added.
- Last modification: the date and time of the last modification of the row.
Every other column is one you created, and carries the name you gave it. A ‘Yes/No‘ column displays ‘Yes‘ or ‘No‘.