The chatbot designer uses a number of different file types to accomplish different tasks. Here’s a short overview of all possible files (and sometimes directories):
Projects
A project contains the entire neural network (in binary form) together with a bunch of configuration files in a directory. This directory is accompanied by the main project file. Both have the same name. When moving around a project, make certain you have both file and directory. When opening and saving projects, you only need to worry about the file, the directory will be created/managed automatically (done in such a way that extra directories like for version control systems, will remain functioning).
The project files themselves (extension ‘.dpl’), are simple xml files which contain various configuration data for the designer. In general though, you don’t need to edit this file manually, all settings can be managed from within the designer.
The most important files in the project directory are binary and should never be manually edited. Some files are xml based, but apart from the test-cases, should be left ‘as-is’ since they contain vital configurations for the internal network.
Topic files
Topics form a major component of a chatbot designer project. They define what the bot can do. Internally, topics are stored as neurons, but in order to share a topic across multiple projects and users, Topic files were introduced. This is an xml file (extension ‘topic.xml’) that contains all the rules defined in the project.
The designer provides functionality to import and export topics one by one or in bulk from the File menu or the context menu on the Project tool-window. So ideally, you should never be confronted with the internals of these files. For the die-hard text-editor fans, here’s a little more details on the structure:
A minimal topic file should contain a topic, name, rules and questions sections. Like:
<Topic>
<Name>Who has</Name>
<Rules />
<Questions />
</Topic>
And a bit more challenging, containing a single rule with 1 input and output pattern pattern:
<Topic>
<Name>Time</Name>
<Rules>
<Rule>
<Name>new rule 1</Name>
<Patterns>
<Pattern>
<Expression>What time is it [?]</Expression>
</Pattern>
</Patterns>
<Conditionals />
<Outputs>
<Output>
<Expression>It is $time:hour\:$time:minute\.</Expression>
<QuestionCanFollow>True</QuestionCanFollow>
</Output>
</Outputs>
<IsOutputSequenced />
<DoPatterns />
<Calculate />
</Rules>
<Questions />
</Topic>
For the curious, the expression: $time:hour\:$time:minute\. is used to render something like 17:30. The expression has to be split up in 4 parts:
| time:hour | returns the hour |
| \: | we need to escape the : cause it is just after a variable path. If we don’t do this, the parser thinks that we will specify another function call. |
| time:minute | returns the minute part of the time value. |
| \. | The . also needs to be escaped, otherwise the parser thinks we are trying to further specify the path. |
Global patterns
In the ‘chatbot properties’ view (From the menu: View/chatbot properties), you can specify a bunch of global patterns like the opening statements, fallback values, ‘do-patterns’ that need to be executed at startup, just after each statement,… This also includes all the OS function-mappings that were declared in the ‘OS channel’. All these can be exported/imported using 1 file, with the extension ‘global.xml’. Import/export can be done from the menu: ‘file/import/global patterns’ or ‘file/export/global patterns’.
As you probably already guessed, this is also in xml format, but like with the topics, the content can be fully managed from within the designer, so there is no need to edit it manually.
Thesaurus files
Thesaurus files are used to share, exchange or replace part of, or the entire thesaurus that is used in a single project (thesauri are project specific and not shared across different projects within the designer). It’s the same routine again as for the previous file types: the extension is ‘thesaurus.xml’, yes, it’s an xml file format and can be fully managed from within the designer. In fact, for the thesaurus, it is more than advised to use the designer and not edit it manually since a thesaurus node can be hard to define as there are multiple levels at which words are stored. The only scenario where you might have to do some manual editing, is when you create a new thesaurus, completely from scratch when all the functionality needs to be preserved and you don’t have access to a network-designer version of the chatbot designer. In that case, the ‘bindings’ section on certain words (numbers, pronouns like I, me, myself,.. needs to be done manually. Here’s a small example of a binding for the object ‘myself’:
<Object Name="myself">
<Text Value="myself" Index="0" POSGRP="false" />
<Bindings>
<ref>I</ref>
<ref>Singular</ref>
</Bindings>
</Object>
Importing/exporting is done from the context menu on the thesaurus. If no node is selected, the entire thesaurus will be exported, or the content of the imported file will be added to the root. If a node is selected during an import operation, all items will be added as a child of the selected node. For export, only the selected item and all it’s children will be exported recursively.
It’s also possible to import or export just a single level of children of a selected node, in the form of comma-separated-value (csv) files. For imports, you don’t even need to get the data from a file, but you can just as easily use the clipboard: just copy a csv list to the clipboard, go to the context menu of the parent node and select ‘Import\wordlist from clipboard’. This feature allows you to quickly build up trees of related words.
Asset files
Assets store concrete information like ‘you are reading this now’ and ‘I have written this text’. By now, the theme should have become clear to you: asset files are stored in the xml format, they have the extension ‘asset.xml’. But here’s where we stray a little from the path: currently asset import/export is only supported in the pro version (that is, it’s still a little bit under construction, so it will soon be available). The same for editing: the pro will have an asset editor, but not the basic version. The latter only has the chatbot window for adding input statements.
Test cases
Test case files aren’t independent files like ‘topic thesaurus, asset or global patterns’ files, but are rather part of the project directory. As such, you can’t currently export or import them automatically from within the designer (though you can fully manage them as in copy, delete, edit,.. from within the designer). That said, they do deserve a special mention since it could sometimes be useful to extract some test-cases and copy them to other projects. And, because a test-case file is actually a stand-alone xml file, this is certainly possible.
Test case files are located at {project directory}\DesignerData\ and have the extension ‘TESTCASE’. If you copy a test-case from one project to another, or you want to delete some manually, make certain that the project is closed.
CCS files (characters)
As a final file format, I’d like to talk a little about characters and their files. A character is stored as an xml file (extension ccs) together with a bunch of images. These images can be located in a subdirectory of the ccs file, as long as the path can be described, relative to the ccs file.
For the chatbot designer to be able to use a character, the files (and possibly directory structure) of the char need to be copied to the directory: {My documents}\NND\Characters\CharName, where ‘Charname’ is the name of the character. Best to do this when the chatbot designer isn’t running.
Unfortunately, ccs files can’t yet be edited in the designer (or any other UI tool). They need to be created manually. Luckily, the structure is relatively simple and allows for lots of copy/paste. More info on the file structure will come shortly.
