Retrieve user who completes curation

[Samuel Glowka]

Hi there,

I have yet another question and I couldn't find anything about it here in the mailing list and in the documentations - maybe I just don't know where to look for it...

For me it's quite unclear what the CURATION_USER actually is and why it exists. 

For our project it's essential to know which user (meaning which person) curated a document and I currently cannot find a way how to get this information.

I just set up the webhooks for ANNOTATION_STATE, DOCUMENT_STATE and PROJECT_STATE but user information is only provided by ANNOTATION_STATE events.

Is there any way for that up to this moment?

Best regards and many thanks for your help,

Samuel

[Richard Eckart de Castilho]

Hi Samuel,

> On 5. Nov 2025, at 16:41, Samuel Glowka <samuel...@gmail.com> wrote:
>
> For me it's quite unclear what the CURATION_USER actually is and why it exists.
> For our project it's essential to know which user (meaning which person) curated a document and I currently cannot find a way how to get this information.

When a curator works on merging annotations from multiple annotators, those merged annotations need to be stored somewhere.
The place where this is stored is a virtual "CURATION_USER" user.
From the perspective of INCEpTION, it does not distinguish who curated a document - all curators essentially act as the "CURATION_USER" when they curate.

It might be possible to include the user who triggered the state change in the event, but that would not necessarily be the user who curated.
E.g. in the case where curator A curated a document and then project manager B comes in and marks the document as curation-finished, it would be use B
who would trigger the state change.

Also, because all curators essentially act as the same virtual user when they are curating, it is essential that they coordinate that no two curators
work at the same document at the same time. And when they are using the integrated annotation view, it is also essential that they do not use
cross-document annotation features such as in particular bulk-annotation via the search sidebar.

Why do you need to know who has curated a document?

> I just set up the webhooks for ANNOTATION_STATE, DOCUMENT_STATE and PROJECT_STATE but user information is only provided by ANNOTATION_STATE events.

A document-state change will only be fired when:

- annotation-in-progress: the first annotators starts annotating
- annotation-finished: (depending on which workload management scheme you use, static or dynamic) either all or a sufficient number of annotators have marked their documents as finished
- curation-in-progress: the first document is opened on the curation page
- curation-finished: the document is marked as finished on the curation page

A project-state change is fired when:

- annotation-in-progress: the first annotators starts annotating
- annotation-finished: when all documents are finished
- curation-in-progress: the first document is opened on the curation page
- curation-finished: when all documents are curated

Cheers,

-- Richard

[Samuel Glowka]

Hi Richard,

first of all thanks for the explanation!

Our project HisQu (https://www.hisqu.de/) aims at making the digital research process in historical sciences fully comprehensible. For every step from annotation and ontology creation to conclusions about the contents of historical sources it is essential that it is known who did it. We integrate INCEpTION into the workflow only as an editor to curate/validate pre-annotations done by our LLM pipeline. By accepting the pre-annotations (and optionally making adjustments) the curator assumes responsibility of the annotations. When the curation of a document is finished it is automatically retrieved and saved into our database. 

For our purpose it might be sufficient, if you could include the user who triggered the state change in its metadata, despite its ambiguity as you described.

I thought, that this was already the case to be honest because in the Admin Guide (https://inception-project.github.io/releases/38.4/docs/admin-guide.html#_message_examples) it says:

"In the ANNOTATION_STATE message, we have two fields containing a user name: user and annotationUser. Usually, these two fields will be the same. They differ if a user changes the state of a document of another user. An example is when a curator marks the curation of a document as finished. In this case, the curator’s username is in the field user while the annotationUser field has the value CURATION_USER." 

Perhaps this paragraph is a bit misleading.

Thanks again for your work and best regards,

Samuel

[Richard Eckart de Castilho]

Hi Samuel,

> On 10. Nov 2025, at 10:57, Samuel Glowka <samuel...@gmail.com> wrote:
>
> Our project HisQu (https://www.hisqu.de/) aims at making the digital research process in historical sciences fully comprehensible. For every step from annotation and ontology creation to conclusions about the contents of historical sources it is essential that it is known who did it. We integrate INCEpTION into the workflow only as an editor to curate/validate pre-annotations done by our LLM pipeline. By accepting the pre-annotations (and optionally making adjustments) the curator assumes responsibility of the annotations. When the curation of a document is finished it is automatically retrieved and saved into our database.
>
> For our purpose it might be sufficient, if you could include the user who triggered the state change in its metadata, despite its ambiguity as you described.

For your case, there might be some alternatives.

Alternative 1)

Before we had the "integrated" curation view on the curation page, we had an experimental "curation sidebar" on the annotation page.
This sidebar had a feature to curate to the annotators own user instead of to the curation user.
You should be able to activate the curation sidebar and the "own curation" feature by adding this to your settings.properties:

```
curation.sidebar.enabled=true
curation.sidebar.own-user-curation-target-enabled=true
```

If the user opening the annotation page has both, the annotator and the curator roles, they can access the curation sidebar and set the annotation target to "my document".
The result is, that the user can accept annotations into their own document instead of into the shared "CURATION_USER" document - so they would *actually* own the annotations.
In this case, the annotation state events should also work as expected - i.e. when the user marks the document as finished, their own annotations should be marked as finished instead of the "CURATION_USER". However, the document-level CURATION_IN_PROGRESS and CURATION_FINISHED become meaningless in this mode.

Note this approach does not work via the split-view approach the traditional curation page uses - only via the "integrated view".

Alternative 2a)

Instead of requiring the your annotators to accept all annotations in curation mode, you could just upload pre-annotated documents and ask the annotators to correct them via the annotation page.
Once corrected, they could mark the annotation as finished.
Downside is that they might miss/forget annotations to be corrected.

Alternative 2b)

This downside could be mitigated by introducing a feature on each annotation that the users would have to set to indicate that they approved of the annotation.
Instead of a boolean feature, I would use a string feature with a non-editable tagset with only one tag (e.g "checked") and make that a mandatory feature.
Thus, users could not mark a document as finished unless all annotations would have that feature set to "checked" on all annotations.
It is a bit tedious though tbh - even more than having to click through all annotations.

In any case, I would advise to test these approaches before deciding for one.
If you run into problems, let me know.
Also, if you decide to use the curation sidebar, let me know because I need to know if I should transfer the option to "curate to own document" to the new integrated annotation page.
Otherwise, that feature might be removed at some point when the old deprecated experimental curation sidebar is dropped from the annotation page.

> I thought, that this was already the case to be honest because in the Admin Guide (https://inception-project.github.io/releases/38.4/docs/admin-guide.html#_message_examples) it says:
>
> "In the ANNOTATION_STATE message, we have two fields containing a user name: user and annotationUser. Usually, these two fields will be the same. They differ if a user changes the state of a document of another user. An example is when a curator marks the curation of a document as finished. In this case, the curator’s username is in the field user while the annotationUser field has the valueCURATION_USER."

The paragraph is right, but the example is wrong. A correct example would be if a manager changes the annotation state for an annotator/document through the workflow page. In that case, the annotator owning the annotations would be in the "annotationUser" field while the manager would be in the "user" field.

Since curation is a document-level state and not an annotation state, no annotation state change event is generated for curation-related state changes.

I'll have to fix this example.

-- Richard