Supported collaboration features

The Import from Word converter supports Word’s collaboration features, namely the comments and track changes. The comments feature lets you add a notice about a selected part of the content, whereas track changes allows proposing a change inside the content, like deletion, insertion, or replacement of a selected part of the content.

Both features are also implemented by CKEditor 5, so make sure to read CKEditor 5 comments and CKEditor 5 track changes guides to learn more.

Note that despite producing compatible content with CKEditor 5 collaboration features, the Import from Word converter is technology-agnostic and can be used with custom integrations on your end - as long as it supports the same content format.

Learn how these are turned into HTML properties and supported by CKEditor 5 from this guide.

# Comments

Comments are an advanced feature of Word that is supported by the Import from Word feature with full compatibility with CKEditor 5 comments. You can add a comment to a Word document by selecting some content and choosing the New Comment option from the Insert tab in the ribbon, or just by using the context menu that can be opened by right-clicking the selected content.

Comments are fully preserved by Import From Word by producing HTML that is compatible with CKEditor 5 and returning comments definitions, that can be integrated both by using Import from Word CKEditor 5 plugin or implementing custom comments integration.

To enable comments conversion using REST API, pass information about user ID and collaboration_features.comments property in the request body:

const config = {
    collaboration_features: {
        user_id: 'user-id',
        comments: true
    }
};

An example payload that will be returned for a simple comment shown in the above screenshots looks like this:

{
  "html": "<p><comment-start name=\"thread-id\"></comment-start>Hello, World!<comment-end name=\"thread-id\"></comment-end></p>",
  "comment_threads": [
    {
      "thread_id": "thread-id",
      "is_resolved": false,
      "comments": [
        {
          "author": "John",
          "content": "<p>Comment 1</p>",
          "created_at": "2022-09-19T15:05:00Z",
          "is_resolved": false,
        },
        {
          "author": "Neil",
          "content": "<p>Comment 2</p>",
          "created_at": "2022-09-19T15:05:00Z",
          "is_resolved": false,
        }
      ]
    }
  ]
}

The comment_threads JSON property includes the full list of comments that were found in the document, grouped by the comment thread ID. Each comment includes the content of the comment in HTML format and information about the original author of the comment.

The comments feature is fully supported by CKEditor 5 and only requires enabling the CKEditor 5 comments and Import from Word plugins.

# Resolved comments

Resolving comments in Word is a way to indicate that a particular comment has been addressed and is no longer a concern. To resolve a comment, a user can simply right-click on it and select “Resolve Comment.” The comment will then be grayed out and a checkmark will appear next to it.

Import from Word returns information about resolved comments within the returned payload. The is_resolved property indicates whether a comment has been resolved by a user. This property can be found both on the comment thread and on a single comment. A comment thread will only be considered resolved when all comments within the thread have been marked as resolved.

Resolved comments are supported by the CKEditor 5 Comments feature.

# Comments styles

By default, all styling that was applied to comments will be preserved. If you would like to limit comments formatting applied during the conversion, formatting.comments will come in handy.

The option can use one of these values:

• full – default value, enables all comments styling,
• basic – preserves only bold, italic, underline and strikethrough styles,
• none – no styles will be preserved.

const config = {
    collaboration_features: {
        user_id: 'user-id',
        comments: true
    },
    formatting: {
        comments: 'basic'
    }
};

# Track changes

Track changes is another advanced feature that is also compatible with the CKEditor 5 track changes. To start tracking changes in Word, select the Review tab from the ribbon and then enable option Track Changes. After that, any changes applied to the document will be tracked.

At the moment, the Import from word supports text insertions and deletions, including changes within tables, lists and images.

Additionally, Word documents can include move suggestions when a part of the content is moved to a different location in the document. These suggestions are represented by a pair of corresponding deletion and insertion suggestions, simplifying their overall structure, without losing any information.

To enable track changes conversion using REST API, pass information about user ID and collaboration_features.track_changes property in the request body.

const config = {
    collaboration_features: {
        user_id: 'user-id',
        track_changes: true
    }
};

An example payload that will be returned for a simple suggestion:

{
  "html": "<p>Hello, <suggestion-start name=\"suggestion-id:user-id\"></suggestion-start>World!<suggestion-end name=\"suggestion-id:user-id\"></suggestion-end></p>",
  "suggestions": [
    {
        "id": "suggestion-id",
        "type": "insertion",
        "author": "John",
        "created_at": "2022-09-19T15:05:00Z"
    }
  ]
}

The suggestions JSON property includes the full list of suggestions that were found in the document. Each suggestion includes the unique ID of the suggestion that is both applied to the suggestion definition and HTML content, the type of the suggestion (insertion/deletion) and information about the original author of the suggestion.

The track changes feature is fully supported by CKEditor 5 and only requires enabling the CKEditor 5 track changes and Import from Word plugins.

# Timezone

The Word track changes feature does not support the UTC format for suggestions creation dates. To calculate them properly we use the timezone data supplied to the converter via config.timezone (read more about this configuration option in API documentation).

# Known limitations

• Limited support for tracking changes of HTML block elements like tables and lists to the text content of these elements.
• No support for formatting suggestions, like applying bold to the text or changing a paragraph to the list.

# Disabled Track Changes

If the document includes some suggestions but the Track Changes feature is disabled by the collaboration_features.track_changes configuration option, all track changes will be treated as applied. As an example, if a user has a document with a text insertion suggestion, that text will be applied to the HTML as a regular text. The deletion suggestions work the same way – if some content is suggested as deleted, it will be removed from the HTML.

That behavior ensures the least possible content loss during the conversion process, making sure that even if you do not enable the track changes feature, you will still get the most out of the Import from Word converter.

# Collaboration authors and users

Please notice that authors imported from Word, also visible in CKEditor 5 as users, are directly loaded from the .docx file. They are not the same as users created in Cloud Services.

The Word documents can be manipulated by 3rd party authors, posing a potential security threat should they be connected automatically with the Cloud Services users. Therefore, the CKEditor 5 Collaboration Features ensure that the author of the comment or suggestion is only used for display purposes. The actual user who is connected to the CKEditor 5 Collaboration Features is the one who is logged in to the Cloud Services.

Let’s consider such a situation: there is a document edited in CKE5 with a few comments. The document is exported to Word and then imported back to the CKEditor 5. In this case, the connection between comments’ authors and Cloud Services users is lost, as the CKEditor 5 can’t guess which user is the author of the comment only based on the provided Word file.