Import/Export a model

Both the importation and exportation processes are batch operations which are carried out throughout the model. Exportation allows you to extract all elements from a model, while the importation process allows you to create or update in batch, as opposed to one-by-one as the console allows. You can access both operations by clicking on the corresponding buttons in the sidebar. The importation process can also be carried out during creation.

The format for both operations is the same - a TSV (tab-separated values) file with UTF-8 encoding. This means that it will be very easy to carry out massive edits in the categories. The export process extracts the categories, alongside their corresponding rules and macros from the model, so that you can modify the necessary information, and then imported back into the model.

The file does not need to have a specific extension; the only conditions that it must fulfill are that:

  • Each element is defined in a different line.
  • The different elements have the following formats:

    category\tCode\tLabel\tDefault (y/n)\tComments

    rule\tID\tLabel\tCategory code\tDefinition\tWeight\tPriority\tComments


    The symbol \t is a tabulation.

The format of the fields specified is the same as in the viewing panels used when working on the console, except for the rules' weight. In this case, Exclude category should be marked with a minus sign -, Always include category with a plus sign, +, and any other weight with the numeric value. You can read more about it in the rules section.

Did you notice...?

The way the different weight options are represented in the import file is the same that appears in the rule table included in the category view.

This is an example of a possible file:





rule\t17db6c81cefa0ea0d54b15ad1ce1a42a\tNetworkSecurity\t002\t(computer|PC|network|internet|cyber AND hack|security|administrator|authentication) OR firewall|hacking|cybersecurity|hacker|L@hack\t+\t1\t

rule\t5ac93cfadf87b386b1e67eb9de5570f7\tBig Data\t001\t"big data" OR "Google Glass"\t+\t1\t

rule\t49b0ca079768c070dde74248964add75\tmanagement\t003\t"his|her|their|your management|conduct|guidance|operation|control|command|supervision|direction"\t+\t1\t


As you can see, each category can have a different format, and if a field is not included, you still need to maintain its position.

This is the result of importing the file used as an example:

Import result

For every importation process a report will be generated that will detail how many and which items were created; how many and which items were updated (those with identifier that already exists in the model); and which ones failed, for which an error message stating the reason will be produced.

Initially, all the items will appear grouped by their result; they can each be expanded to see their details by clicking on the plus sign next to them.

If any of the categories, rules or macros in the file were not imported, an alert informing you that the process was incomplete; after which, you will be redirected to the report to look at the error in detail.

Import result with errors alert

Errors in the import process can be related either to the format of the data in the file (incorrect number of fields), or its contents (not valid or unsupported values).

There can be errors in the importation process, mainly of three types:

  • Format errors: Errors in the format of the import file, such as when a line does not have the right number of fields.
  • Model coherence errors: When we try to insert an element refering to an ID that does not exist.
  • Incorrect field errors: When any of the basic fields does not comply with the limits or the syntax set, for example, a code with more than 64 characters or a rule with a definition with incorrect syntax.

When a line in the file displays any of these errors, it will be ignored. The result of the importation process will be specified in the report, detailing the result of each of the lines in the import file.

Below you can see the results of a report summarizing the results of the importation of an exemplary file with various distinct errors.

Import errors

In the report above, we can see:

  • A category was created when we specify a category code that does not yet exist (line 3)
  • A macro was updated when it was found that the label already existed in the model (line 4)
  • We receive an error if the line does not contain the necessary fields, or the keyword that defines the element is incorrect (line 2, line 7 and line 1, respectively)
  • We receive an error if the syntax of a rule’s definition is incorrect (line 5)
  • We receive an error if the value input for the weight is invalid (line 6)
  • We receive an error if we assign a rule to a category code that does not exist in the model (line 8)

Did you notice...?

In the errors related to fields of the rule element, they are not referred to by their name, but by the field name preceded by 'entry_'. For instance, in line 8, when it talks about entry_code, it's refering to the category code the rule belongs to.

Additionally, an error will be produced if an importation process causes you to exceed the amount of categories established by your plan limit. If this error is produced, any other error generated will not be shown.

Plan limit error

To export a model's categories to a file, you only have to click on the sidebar's Export button. It will create a file with the same format required to import a model, featuring all the categories, rules and macros that exist in the model.

It's important to note that this action does not create an exact backup of the model. It only exports categories, rules and macros. The name, description and settings of the model are not saved in the export file.