Import an old project

Use this procedure when you have a project created with legacy product Cogito Studio version 14.6 or later and want to turn it into a new project.

1. In the Welcome to Studio screen select Open.

   

2. In Open File or Project select the folder containing the old project files and select OK.

If instead you are already working on a project:

1. Select File > New > Project from Existing Sources.
2. In Select File or Directory to Import select the folder containing the old project files and select OK. The Import Project dialog will appear.
3. Select Import project from external model and select Next.

4. In the Destination project section, set the location for the migrated project and the project name.

   Note

   With this procedure, a new folder containing the migrated project will be created.

5. Use the Libraries section to manage your libraries. Select:

   • Add to add libraries.
   • One or more libraries (multiple selection with Ctrl-click is allowed) and select Remove to remove libraries from the list.
   • Remove all to remove all libraries.

   Note

   You can't select single documents but only folders.

6. In the Options section, choose the migration strategy between:

   • Update Knowledge Graph format to update the old project knowledge graph format to UTF8. This operation will make the Studio project compatible with the latest technology, while keeping the exact same contents of the knowledge graph, including any patches or extensions that may have been applied to the original old project. The only thing that will change will be the disambiguator, which will be updated to the latest version.
     This option is recommended if the original project has an extended and/or patched knowledge graph, but the customization source files (CSV or XML) are not available anymore.

   • Replace Knowledge Graph libraries and edit rule files accordingly to update the knowledge graph to its latest version and perform a remap of syncons and lemmas between the two versions. Consequently, rule and list files are edited based on this remap. This option is the best practice. If the original knowledge graph was extended and/or patched and the customization source files are available, the best course of action is to choose this option to have a brand new knowledge graph and then extend and/or patch it using the source files, to re-create the customization of the old knowledge graph.

   If neither option is checked, the new project will have the old knowledge graph. Studio can use an old knowledge graph, but it's not possible to:

   • Deploy the project as a CPK.
   • Transfer the project to Platform.
   • Extend and/or patch the knowledge graph without converting it to UTF-8

   Thus it's recommended to choose one of the above options to take advantage of the latest NLU technology.

7. Select Create.

At the end of the procedure, if you chose one of the options above, two MarkDown files will be generated:

• README.md, containing the report of the operation, including automatically applied changes and changes to perform manually plus any errors. Learn more about it below. This file will be located in the project folder.
• README_details.md, containing details about the original encoding of the project files, as all files are converted to UTF-8.

In case of the second option, a README_knowledge_graph.md file will also appear. This file reports all changes applied to the knowledge graph in terms of lemmas and syncons.

The README_details.md and README_knowledge_graph.md will be stored in the migration sub-folder of the reports folder.

Also, Studio automatically builds the new project. The result is documented in the Console and in the Notifications tool windows.

Report details

The README.md file contains comprehensive details on the procedure steps across the following sections.

Tasks

This section gives details on the tasks that have been carried out. For instance, if any libraries has been imported, this section lists how many documents and annotations have been processed.

Errors

This section lists critical errors captured during the import process. Build errors related to the rule language, for example missing files, are not listed here.

Warnings

This section provides the user with any general information about the project. For instance, it warns about any plugin that has not been imported and points to documentation articles to explain how syntax has changed.

TODO

This section suggests any intervention that needs a double check by the end user. For instance, some specific configuration options may be suggested in this section without being automatically added, leaving the final decision to the user.

In the case of scripting instructions, which in certain cases replace syntax that has been deprecated, all instructions are already included in the main.jr file, but are left commented so the user can review them and become aware of their effects.

Applied changes

This section lists in detail every single automatic change that has been carried out in the original source files. These changes have been made so that the new project is one step closer to a successful build or, in the best case, is successfully built at the first attempt. Changes can have been applied to comply with syntax changes or regular expression shortcuts no longer accepted.

The list of edits can be very long, depending on the project, but it is not meant to be reviewed: it can come handy in case the user is unsure about something that does not look right and wants to check if any automatic changes have been made, that possibly lead to undesired behavior.

Tackling migration and knowledge graph customization

If the old project has an extended and/or patched knowledge graph, or knowledge graph customization may be in sight immediately after the import, the following aspects must be considered.

Original sources available

If the original XML or CSV files containing the changes are available—so it is possible to repeat the customization—, the recommended option for step 6 of the import procedure (see above) is Replace KG and edit source files accordingly, so to get the latest technology with the added benefit of syncon and lemma mapping.

This action will probably result in build errors if, as it is likely, the rule files make use of custom syncons.
Any original source file should be revised to ensure that the edit operations still make sense with the latest knowledge graph; for instance, it may be that the original patch deleted a syncon that has been removed also in the latest knowledge graph. The extend and patch procedure raises warnings and errors if it catches such problematic situations.

The last step is to import and build the revised sources, so to get the customization needed to make the project build.

Original sources are not available

In this case, in order to preserve the changes to the project, the choice at step 6 of the import procedure is Update to UTF8.

Tip

Contact expert.ai support if you think you have special knowledge graph customization needs that are not covered by the import procedure.