Bug? "categoryValueRef" not serialized to XML

Hello everyone,

I want to create a plugin in bpmn-js that enables people to provide additional information on acitivties.
I identified the “categoryValueRef” of activities as the perfect spot to do so.
Following the example for editing bpmn-js-properties (bpmn-js-examples/bpmn-properties at master · bpmn-io/bpmn-js-examples · GitHub), I tried to set the property “categoryValueRef” to my desired value. This seems to be possible if you take a look at the moddle-descriptor (GitHub - bpmn-io/moddle: Meta-model based data structures for those who need it):
“name”: “FlowElement”,
“isAbstract”: true,
“superClass”: [
“properties”: [
“name”: “name”,
“isAttr”: true,
“type”: “String”
“name”: “auditing”,
“type”: “Auditing”
“name”: “monitoring”,
“type”: “Monitoring”
“name”: “categoryValueRef”,
“type”: “CategoryValue”,
“isMany”: true,
“isReference”: true
Objects of the type “FlowElement” have this property and activities/tasks/subprocesses etc. are FlowElements.

So I tried the following:

modeling.updateProperties(myFlowElement, {
categoryValueRef: ‘test’

Which leads to the following XML-output:

<bpmn:task id=“Activity_1lwkpt3”>
<bpmn: categoryValueRef>test</bpmn:categoryValueRef>
<bpmn: incoming>Flow_0fs5gfk</bpmn:incoming>
<bpmn: outgoing>Flow_1xd86cr</bpmn:outgoing>

Trying to import the XML-File to a bpmn-js based modeler, I get this warning:

unknown attribute ‘categoryValueRef’ [ warning ]
unresolved reference ‘test’ [ warning ]

For me, it seems like the serialization of FlowElements with the additional property “categoryValueRef” does not work.

What am I doing wrong?

Any help would be appreciated.



I could solve my problem, but encountered a new one.
As you can see, the “categoryValueRef” is now set properly to the desired value:
I did so using this code:
“this.#modeling” and “this.#moddle” are just private class fields that contain “moddle” and “modeling” injected with “didi”.
The problem now:
When I want to save this diagram/serialize it to XML, all the information on the “categoryValueRef” just does not show up in the XML-File.
Interestingly, if I set the “categoryValueRef” to just a string and not to the object “categoryValueElement”,
you can see that this is serialized to the XML-snipped I provided in my post above.

Still, any help is appreciated.


@the_categorizer As you can see from the meta-model categoryValueRef is a reference to a CategoryValue, defined through a Category element and attached to the root Definitions object.

Because of that this is the wrong way of doing things:

modeling.updateProperties(myFlowElement, {
  categoryValueRef: "test"

What you’d do instead is to retrieve (or create) a CategoryValue -> Category -> Definitions and then update it:

const categoryValue = createOrSetCategoryValue('test');

modeling.updateProperties(myFlowElement, {
  categoryValueRef: categoryValue

Hi nikku,

thanks a lot for your detailed answer. In the meantime, I was able to get rid of my confusion concerning the category values and their references. So I went down a path similar to the one you proposed: I created a group programmatically, which triggers the creation of a category object with the definitions object as parent. When I added the group label, a category value also appeared.
Your solution includes this call: “createOrSetCategoryValue(‘test’);”. What does that mean? I was unable to find it in the documentation. Maybe this can enable me to get rid of this experimental creation of a group (with the element factory and bpmn factory and adding the shape via the modeling api).

Once again, your detailed answer is very much appreciated and I would be very happy if you could explain the call “createOrSetCategoryValue()” to me.


We do not offer a pre-built way to add a category value. My createOrSetCategoryValue('test') call refers to nothing else but the function you craft to add the respective elements to the diagram, using the modeling and elementFactory services.

Ok, I get it.
Thank you very much.

This topic was automatically closed 7 days after the last reply. New replies are no longer allowed.