Skip to main content
ExpertExpert

On October 21, we applied a security patch across all NiCE KM production environments to address a recently disclosed PHP vulnerability. The update was completed without service disruption, and our team continues to monitor the platform closely. No action is required on your part.

NiCE Knowledge Success Center

Preserve source page group grants when importing content

Applies to:
CXone Mpower Expert (current)
Role required:
Admin

When you import content from one NiCE Knowledge site into another, you can ask the import to make each imported page's group permissions an exact copy of the group permissions on the source page. This is controlled by the preservesourcepagegrants query parameter on the import request.

This option is available starting with the September 24, 2026 release. It is available through the API only; there is no checkbox for it in the Special:ImportExport page yet.

This option overwrites permissions every time you import. Any permission on a destination page that is not also on the source page is removed, including permissions an administrator added directly on the destination site. Read Limitations before turning it on.

What changes with and without the parameter

Situation Without the parameter (default) With preservesourcepagegrants=true
Permissions on the imported page Import only adds permissions. It never removes any. The page's group permissions become an exact copy of the source page's group permissions.
A new page created under a parent page The new page starts with a copy of its destination parent's permissions, and those stay even if the source page does not have them. Permissions copied from the destination parent are removed unless the source page also has them.
A permission was removed from the page on the source site It stays on the destination page after re-import. It is removed from the destination page on the next import.
A permission was added directly on the destination page It is kept, including across re-imports. It is removed on the next import, because it is not on the source page.
Permissions granted directly to individual users User permissions already on the destination page are kept. User permissions on the destination page are removed, because individual user permissions are not included in an export.
A group in the source permissions cannot be matched on the destination (for example, a different group with the same name already exists there) The permission is skipped. The import log reports the group conflict, but does not say which pages lost a permission. The permission is skipped, and the import log also names the group and each affected page.
Page restriction level (for example Public or Private) Not affected by this option. The page's restriction level is set from the source page in the same way either way.
Page content Not affected by this option. Content is imported the same way either way.

Example

On the source site, a Guide grants the group Marketing access, and a child page under it has the Marketing permission removed.

  • Default import: the child page on the destination shows the Marketing permission, copied from its parent, even though the source child page does not have it.
  • Import with preservesourcepagegrants=true: the child page on the destination does not have the Marketing permission. The Guide itself keeps it, because the source Guide has it.

Before you begin

  • You need a source site and a destination site, both with Import/Export enabled, and administrator access to both.
  • You need an API token for an administrator account on the destination site. See Authorization Tokens for how to get one and send it with your request.
  • If your sites use the advanced export and import options, see Advanced export and import options for how those change export and import requests. Permissions are handled the same way when those options are enabled.
  • Groups that appear in the export are created on the destination during the import if they do not already exist there. Permissions are matched by each group's stable identity, not only by its name. A group that was created separately on the destination with the same name is a different group and will not receive the permission. Groups created by a previous import are matched correctly.
  • Permissions granted directly to individual users are not included in exports, so they are not carried to the destination. With this option, any user permission on an imported destination page is removed.
  • Decide whether you want the destination to always match the source. If administrators set permissions directly on the destination, do not use this option.

Step-by-step

1. Export the content from the source site

  1. On the source site, open the Control Panel and select Import/Export.
  2. Choose Export, select the pages to export (include sub-pages if you want them), and submit.
  3. When the export finishes, copy the URL of the resulting archive from the completion notification or the job status.

2. Start the import with the parameter

The Control Panel import does not include this option, so start the import with an API request to the destination site. Add preservesourcepagegrants=true to the request:

POST https://<destination-site>/@api/deki/site/jobs/import?preservesourcepagegrants=true
Content-Type: application/xml

<job>
  <notification>
    <email>you@yourcompany.com</email>
  </notification>
  <archive>
    <url>https://<archive-url-from-step-1></url>
  </archive>
</job>

The request body is the same as for any other import job; the only difference is the preservesourcepagegrants=true query parameter. To import without the option, omit the parameter or set it to false. See POST:site/jobs/import for the full request reference.

3. Wait for the import to finish

Check the job with GET https://<destination-site>/@api/deki/site/jobs/status, or wait for the completion email.

4. Review the import log

Open the import log (a CSV file linked from the job status and the completion email) and look for warnings. A clean-looking completion email does not guarantee that every permission was applied.

5. Check the permissions on the destination

Open a few imported pages on the destination site and review their permissions. They should match the corresponding source pages.

Expected results

  • Each imported page has the same user and group permissions as the source page. Extra permissions, including ones copied from the destination parent page, are removed.
  • The import does not fail if a permission cannot be applied. The job completes, applies every permission it could, and records the ones it could not.
  • Each permission that could not be applied is listed in the import log with the page and the group involved. For example, when a different group named Legal already exists on the destination:
DataId,PagePath,WarningType,Message
1b42778b641b2f3b7ca16998c13390f0,Groups:,FailedToImportItem,There was an error importing group 'Legal': 'The requested group changes could not be performed due to a naming conflict'
f5971e3213567c8041a8d8773b3b67df,//SomeGuide/SomePage,PageGrantsPartiallyResolved,1 of 1 grants in the import manifest could not be resolved to a real user or group and were not applied: group 'Legal'.
  • The FailedToImportItem row for the group appears with or without the option. The PageGrantsPartiallyResolved row is added by this option and names each affected page.
  • PageGrantsPartiallyResolved means some permissions were applied and the ones named in the message were not. The group named usually could not be matched because a different group with the same name already exists on the destination.
  • PageGrantsReplaceFailed means the permission data for that page was invalid (for example, the same group listed twice). The page's existing permissions are left unchanged (and its restriction level is not updated), and running the import again after the problem is fixed retries that page.

Limitations

  • Every import overwrites. Permissions added directly on the destination, including by administrators, are removed on the next import with this option.
  • Conflicting groups are skipped. If a group with the same name but a different identity already exists on the destination, it is not matched, its permission is not applied, and the import log reports it. Resolve the conflict (for example, rename or remove the unrelated group on the destination), then import again.
  • User permissions are not transferred. Exports do not include permissions granted directly to individual users (the export log notes this), and this option removes user permissions from the destination pages it imports. Use group permissions for access you want to keep in sync.
  • Dry runs do not show permission results. A dry run (dryrun=true) does not apply permissions and does not report permission warnings, with or without this option. Permission problems appear only in the log of a real import.
  • A temporary lookup failure can remove access. On a re-import, if a group or user cannot be found at that moment, its existing permission on the destination page is removed. Check the import log and run the import again once the group or user is available.
  • Changing only an expiration date may not update it. If the only difference for a permission is its expiration date, the destination page keeps its existing expiration.
  • New pages briefly carry the parent's permissions. A page created by the import has its parent's permissions for a short time, until the same import applies the page's own permissions moments later.
  • Each page is handled on its own. The option does not cascade from a page to its children. Only pages included in the import archive are updated, so pages you do not import keep their existing permissions.
  • API only. The Special:ImportExport screen does not offer this option yet.

Troubleshooting: a page's permissions look wrong after an import

  1. Confirm the option was used. Imports started from the Control Panel use the default behavior, which only adds permissions.
  2. Find the page in the import log. Search the CSV for the page path.
  3. Read the warning. A PageGrantsPartiallyResolved or PageGrantsReplaceFailed row names the group or user involved. Check whether a group with that name on the destination is actually a different group.
  4. If the log has nothing for that page, the permissions were applied as an exact copy of the source. Check the source page's permissions first.
  • Was this article helpful?