Free Support Forum -

Annotation serialization



recently you updated the XML schema, so the annotation serialized to XML is now more human readable. Thanks. But, I can see now some issues with the following parameters saved in the XML (part of IAnnotation interface):

1. id - it is an integer. In our case ID is a 16 char hex string and we cannot use it. We don’t want to save it in XML anyway, as annotation content(xml) is attached to an object id an ID and that annotation content can be migrated to another place where the ID is different. Thus, XML should not contain any ID. We could use some custom serializer, but that IAnnotation attribute should be String, not INT

2. userId - it is INT and in our case user name is the ID so we would have to somehow translate the ID to the user name. Can you change it to string?

3. annotationSessionId - what is session ID? how to understand it? And why is it saved in XML? Annotation is document-related and should not contain any session-specific data. We could use a custom serializer, but I still don’t know how to populate it after deserializing?

4. guid - what is it? how is it generated?

Thanks in advance for some help with that,


annotationId, userId, parentReplyId in replies should be also strings.


Hi Mariusz,

1. This id is an internal id of the annotation object. This id is used to connect annotation and applied comments (replies).

2. The userId is an id of the GroupDocs.Annotation user, not the user from your application.

3. For now serialization stores the GroupDocs.Annotation library state. As you could see from the entity diagram the user is connected with some document through the session and annotations are applied to that session. To preserve correct connections between entities and correct state of the GroupDocs.Annotation library all this info should be restored. That's why sessions also are serialized.

4. GUID is used as global unique identified of the entity, not only in the particular table. It is required on the creation stage also is used in the annotating workflow (somewhere in the internal processing and somewhere on the UI).

All data serialized with the XML serializer is appropriate to the internal structure of the GroupDocs.Annotation entities relations. If you want to store it differently you can create your own custom meta-data connector which will have to correctly deserialize data according to this structure (or according to Dao interfaces).


Hi Ihor,

that’s the whole problem. You’re using some internal structure that cannot be actually extended or customized. It’s designed for your internal usage. Normally if you take a look at your competition, e.g. Brava or IBM ViewOne Pro the integration is much simpler.

In a real world example, when we want to integrate it with Alfresco, Documentum, FileNet, Sharepoint, Oracle WebCenter or any existing db-based ECM system it seams to be impossible. That means 90% of the market.

In case of any ECM system, we can:

1. Get the document name and content by ID
2. Get the existing annotation by document ID
3. Add/Edit/Remove annotation by document ID and annotation ID

And that’s all we should implement.

Basically when the annotation tool is opened we pass to it the object ID and the user name. Then the annotation tool should have a way to read the document by this ID and then read the annotations by the the object ID. We don’t care about the user, session or anything but the annotations. We have integrated other mentioned viewers and it was just a matter of extending two connectors: one for getting the documents and the other for managing the annotations. User name was used just to identify the annotations authors and then permissions to them. In your scenario annotation and reply are the same from the user perspective and any reference between them should be maintained internally, the annotation ID should be unique only in a document context, not unique generally. That’s because there must be a way to migrate them between different installations.

Your data structure is something really strange to me, I have no idea why you save some session info which is temporary and should not be ever stored.

What I would like to know is whether there is any way that we can create our connectors with just the 3 API parts we have access to (get doc by id, get annotations by doc id,save user annotations). Without storing any info about users or sessions. Plus in our case user name, document ID and annotation ID is always a string.

So please let me know if we can do that, and if so how.

Thank you,


Anyway, that thread concerns only annotation serialization. The annotationSessionID should not be serialized as session is transient and volatile. Annotation is related to the document and doesn’t need session ID to be stored.

userId should be a string rather than int as we don’t want to use the groupdocs internal user ID when storing the annotation in an external system.

Thank you,

Hi Mariusz,

The fixed version of the InputDataHandler will be released in the 2.6.0 version of the GroupDocs.Viewer so at that point you’ll be able to open documents specifically for each user.

What about meta-data connector. Dao interfaces were made public to give an ability to create a custom data structure and fully store objects.
You mentioned fields that are not used - you are free to fill them with null values without any worries.

This situation was reported to our developers. We will think about it and try to provide some solution with available interfaces or plan some additional interfaces to be implemented in further releases.


It would be good to provide at least a one more level of abstraction. You already have IConnector and IDatabaseConnector, although it has methods in wrong class. That’s a good start anyway. Right now it’s a database design, it just cannot be used easily without it.

Hello Mariusz,

The IConnector interface represents not only serializer. It is designed to allow maintaining data and structure manually.

If you have a situation where you need to store annotations separately for each document, you can provide some mapping. I’m attaching a simple IAnnotationDao implementation example built on top of the sample code It can be used here but the variable holding the SimpleXmlAnnotationDao object should be created, i.e.:

private IAnnotationDao annotationDao = null;
public IAnnotationDao getAnnotationDao() throws AnnotationException {
if (annotationDao == null) {
annotationDao = new SimpleXmlAnnotationDao();
return annotationDao;

The same way you can easily create implementation specific for your environment.

Hello Mariusz,

Good news! We’ve already prepared the GroupDocs.Annotation for Java library v.1.8.0 beta. The link for downloading was mailed to you.
With the 1.8.0 version there is implemented the Environment variable, from which you can retrieve the file guid and store annotations per document more easily. Please, check out the 1.8.0 branch of the slim sample and the attached example file.
Please, note, for now use the DaoFactory.create() instead of the getDaoFactory() method when initializing DAOs.