6.8 Import/export

You can import or export lists of FAQ articles (knowledge articles in Ops I) and categories as CSV files.
You can save lists of FAQ articles and categories at a given point in time to files, or create and edit multiple FAQ articles or categories at once.

In an environment where you perform import/export, use a template according to your purpose. You can either use a preprepared template or create a new one. The ITSM application provides the following three templates.

This section describes the following items.

• Creating a template
• Export FAQ articles and categories
• Import FAQ articles and categories
• Use case

(1) Creating a template

A template is a set of rules that defines the types of objects in OTOBO and the mapping of their fields to information in input and output files, as well as the format of the files. If you use prepared templates ① to ③, you do not need to create a new template. If necessary, you can edit templates ① to ③ for use.
Create a template by using the following procedure.

Select [Admin] from the main menu, and then click [Administration] - [Import/Export]. On the [Import/Export Management] screen, click the [Add template] button. Follow the transition display and fill in the following fields.

(2) Export FAQ articles and categories

Select [Admin] from the main menu, and then click [Administration] - [Import/Export] to go to the [Import/Export Management] screen, where a list of templates will be displayed.
Click [Export] in the [START EXPORT] column of the template to be exported to download a CSV file based on the template settings.

CSV file size limits and handling

• File size:
  The size of a CSV file that can be imported is up to 500 MB. If you want to import the exported CSV file as is, adjust the file size to be within 500 MB. For FAQ articles that include attachments, the limit is 700 entries. The approximate number of categories or FAQ articles is within 700 for each.
• Timeout:
  If the CSV file size is large, import or export processing might take 30 minutes or longer and time out.
• Handling timeouts:
  • Export: Set the search conditions, and split the file to export it.
  • Import: Even if a timeout occurs, internal processing might continue. Wait a moment, and then check the FAQ articles and categories. If any items are missing, import them by using provided templates ① and ③.




Note


• If you export data, a UTF-8 encoded file (CSV format) with no BOM is downloaded. If you open this file in a text editor, it will be displayed normally. However, if you open the file in Excel, character corruption will occur, so encode the file to UTF-8 with BOM and save it again.
• If you use the search information settings to filter categories, only those categories will be subject to export. Parent categories and subcategories will not be exported.





(3) Import FAQ articles and categories

Select [Admin] from the main menu, and then click [Administration] - [Import/Export] to go to the [Import/Export Management] screen, where a list of templates will be displayed.
Click [Import] in the [START IMPORT] column of the template to be imported and select the CSV files to be imported to retrieve and import the FAQ articles and category information from the CSV files based on the template settings.

Categories are structured hierarchically, so in the CSV file, list the higher-level categories in rows above the lower-level categories. In addition, FAQ articles that have no categories will result in an error and will not be imported. For this reason, import categories before importing FAQ articles.

If one or more imports are successful, the import summary for FAQ articles and categories will display the number of successful imports and the number of failed imports. If the import itself fails, the cause of the error will be displayed.
You can check the details of partial import failures and import failures themselves by selecting [Admin] from the main menu, and then selecting [Administration] - [System Log]. However, the number of entries that can be displayed is around 200, so check the log immediately after the import. Also, if data is missing from the imported file due to incorrect character encoding in a CSV file, this fact will be displayed in the log. Therefore, we recommend that you check the log even if the import was successful.
If there are any failed FAQ articles or categories, identify the objects and causes, make corrections, and import them again.

To create new FAQ articles or categories in a CSV file, write the following items.

• Ensure that appropriate values are written in the corresponding columns of the CSV file.
• If there are fields that are required due to creating a new class or editing a class, the CSV file must contain the appropriate values, including the mapping elements for those fields.



Note


• Importing CSV files does not allow the deletion of FAQ articles and categories.
• The voting information for imported FAQs will be reset.
• You can import CSV files up to 500 MB at a time. The approximate number of FAQ articles or categories in a CSV file is within 700. A timeout occurs if the import takes 30 minutes or longer. For details on the procedure in such cases, see "CSV file size limits and handling".
• If images are attached to the [Symptom], [Problem], [Solution], [Comment] of the FAQ article, also select the "Import/Export attachments (as the last entries per line)" checkbox. If the checkbox is not selected, the attached images will not be imported. Instead of the attached images, corrupted image icons will be displayed.
• Note the following when updating entries:
  • CreatedOn will not be imported regardless of whether it is mapped.
  • If the "Empty fields indicate that the current values are kept" checkbox is not selected and UpdatedOn is not mapped, the import time will be used for UpdatedOn.
• Note the following when creating new entries:
  • Selection of the "Empty fields indicate that the current values are kept" checkbox will have no effect.
  • If you map CreatedOn and UpdatedOn, the time described in the CSV file is used for CreatedOn and UpdatedOn respectively.
  • If you do not map CreatedOn and UpdatedOn, the import time is used for CreatedOn and UpdatedOn respectively.





(4) Use cases

The following are examples of prepared template use. ① to ③ indicate the following templates:

① Overwrite FAQ articles (Built-in template)
② Add FAQ articles (Built-in template)
③ Add categories (Built-in template)

For details, see “Create a template”.

a. When importing general FAQ articles (such as those on usage or frequently asked questions) prepared in the sandbox environment into the production environment
To register FAQ articles prepared in advance in the sandbox environment to the production environment where no FAQ articles are registered, perform the following procedure.
1. Use ① to export all FAQ articles from the sandbox environment.
2. Use ① to import the FAQ articles into the production environment.


b. When importing general FAQ articles for new customers (such as those on usage or frequently asked questions) prepared in the sandbox environment into the production environment
To register FAQ articles for new customers prepared in advance in the sandbox environment to the production environment where no FAQ articles for new customers are registered, perform the following procedure. Note that, if you individually registered FAQ articles in the production environment, the "FaqNumber" values might overlap between the sandbox environment and the production environment. For this reason, make sure that the "FaqNumber" values do not conflict.
1. Use ② to export only the FAQ articles you want to migrate from the sandbox environment.
2. Use ② to import the FAQ articles into the production environment.


c. When applying FAQ articles updated in the sandbox environment to the production environment
If you want to update in the sandbox environment FAQ articles that were imported from the sandbox to the production environment, and apply the updates to the production environment, perform the following procedure. In this case, the same FAQ articles are already registered in the production environment, so specify the same "FaqNumber" values to update them.
If you individually created FAQ articles in the production environment and the "FaqNumber" values do not match between the sandbox environment and the production environment, manually change the "FaqNumber" value to match those of the production environment, and then import them.
1. Use ① to export only the FAQ articles you want to migrate from the sandbox environment.
2. Change the "FaqNumber" values in the exported CSV file to match those of the production environment.
3. Use ① to import the FAQ articles into the production environment.


d. When importing FAQ articles created in the production environment (such as FAQ articles created from incident tickets) into the sandbox environment
To register FAQ articles individually created in the production environment to the sandbox environment, perform the following procedure.
1. Use ② to export only the FAQ articles you want to migrate from the production environment.
2. Use ② to import the FAQ articles into the sandbox environment.


e. When applying FAQ articles updated in the production environment (such as FAQ articles created from incident tickets) to the sandbox environment
If you want to update in the production environment FAQ articles that were imported from the production environment to the sandbox environment, and apply the updates to the sandbox environment, perform the following procedure. In this case, the same FAQ articles are already registered in the sandbox environment, so specify the same "FaqNumber" values to update them.
Note that, if you individually created FAQ articles in the sandbox environment and the "FaqNumber" values do not match between the sandbox environment and the production environment, manually change the "FaqNumber" value to match those of the sandbox environment, and then import them.
1. Use ① to export only the FAQ articles you want to migrate from the production environment.
2. Change the "FaqNumber" values in the exported CSV file to match those of the sandbox environment.
3. Use ① to import the FAQ articles into the sandbox environment.


f. When registering FAQ articles prepared in an environment other than Ops I to Ops I
To register FAQ articles prepared in an environment other than Ops I to Ops I where no FAQ articles are registered, such as when migrating FAQ articles from a customer's existing environment to Ops I, perform the following procedure.
1. Export the FAQ articles from the environment other than Ops I, and convert them into a format that can be imported into Ops I.
At this time, encode the file paths of the attachments in Base64.
2. Use ① to import the FAQ articles into the sandbox environment and the production environment.


g. When importing categories prepared in the sandbox environment into the production environment
To register categories prepared in advance in the sandbox environment to the production environment where no categories are registered, perform the following procedure.
1. Use ③ to export all categories from the sandbox environment.
2. Use ③ to import the categories into the production environment.


h. When importing categories prepared in the production environment into the sandbox environment
To register categories individually created in the production environment to the sandbox environment, perform the following procedure.
1. Use ③ to export only the categories you want to migrate from the production environment.
2. Edit the exported CSV file to include only the categories you want to migrate.
3. Use ③ to export the categories from the sandbox environment.