There are two types of PocketQuery Imports: JSON and XML. The format of the file depends on the Confluence that generated the file. If you are migrating from Confluence Server/DC, you will have an XML file. If you use an export file from Confluence Cloud, you will have a JSON file. During the import process, you should not note any differences between these file formats.
At first, we will describe how you can upload a file containing PocketQuery entities. Then, we will focus on conflicts that may occur and how we can resolve them.
How to Import PocketQuery Entities
You can find PocketQuery Import on the left side of the PocketQuery Import/Export section. At first, you need to provide a file you want to import. The file needs to be a valid PocketQuery export (all Server, DC, and Cloud origins are accepted).
You can either drag & drop your file into the highlighted area or browse files on your computer. Note that your file must have either a
.xml extension. Otherwise it is considered as an invalid file. When a file is accepted, you can see its name in the Drag & Drop area:
Once you are ready, you can hit the “Upload file” button. This action does not perform the import, it only uploads the file and analyzes it to ensure that it can be safely imported. Once the analysis is finished, a new dialog is opened where you can see the validation result.
Viewing Validation Result
In this case, we can see that there are no severe problems. If you see the green message, you can be sure that all your entities are safe to be imported.
In the ‘Warnings’ section, you can find a list of detected entities. The icon in the top-left corner denotes the entity type:
Magnifier represents Query,
Database icon denotes Datasource,
Cogwheel signifies Converter, and
Palette stands for Template.
The icon has one of the following four colors:
Green means there are no validation issues. The entity can be safely imported.
Blue means there are some minor issues that do not negatively affect the entity itself (it can still be completely imported) but it might cause some unexpected behavior. In this category, there are usually issues related to the entity configuration. The configuration corresponds to the minimum validation requirements but contains some deprecated features or the behavior might differ to your expectations. For example, you might use a PocketQuery API in your Template but this API is not available in Cloud. Another issue might be that you are trying to import an entity that already exists in your Confluence. In this case, the old entity is overwritten (and PocketQuery informs you using this ‘blue message’).
Orange means that the entity cannot be fully imported. This means there are some fields that do not correspond with the minimum validation requirements. An example of this problem is a Query referencing an invalid Converter or Template. In this case, the Query can be still imported but invalid references are replaced with the default Template or Converter.
Red means a critical validation problem that cannot be automatically fixed by PocketQuery. If you see this color, the entity cannot be imported. If you proceed with the import, PocketQuery ignores the entity. These problems are often related to Confluence Cloud vs. Server/DC compatibility. For example, you might have a Datasource of a type that is not supported in Cloud. As “Datasource Type” is an essential property of every Datasource, the new Datasource cannot be created and therefore is marked as ‘skipped’.
Keep in mind: despite that you might see the green message saying “No critical problems found, all entities will be imported.”, we still highly recommend to expand all non-green entities and make sure the conflicts are not critical to you.
Once you have viewed all the import-related issues, you can decide whether you want to continue with the import. If you want to proceed and save all the listed entities (considering all the mentioned effects), you can perform the import by clicking on the “Perform import” button.
Once you do so, the import begins. While the import is in progress, you can see a progress spinner in the center of the dialog. The whole process might last up to a minute based on your Confluence size and the import file size. Once it is finished, you will see the following message:
At this point, there are no other required actions. Click on the “Close & Reload” button to refresh the Confluence administration (so the changes are reflected in the UI) and the import is finished.
As we mentioned in the previous section, you might be facing some issues with importing PocketQuery entities. For example, some of the entities may be marked as ‘skipped’. If they are essential to you, you can usually solve the problem with a few simple adjustments. In the PocketQuery Entity/File cannot be imported section, we will guide you through the process.