If you do a setVariable(<name>, <value>, <token>) on a token, but the variable does not exist, the token parameter is ignored and the setVariable is done on the root token. This is confusing.

On the other hand createVariable(<name>, <value>, <token>) on a token works as one would expect setVariable to: a variable is created and updated with this call.

The documentation only mentions setVariable, but the Javadoc does describe the setVariable behavior, so it is intentional.

I still would suggest to make a more natural behavior:

• createVariable truly only creates, if the variable exists it should thrown an exception.
• setVariable, creates and/or updates the variable

I'm fully aware that breaking the API's behavior is unwanted, which is why the following may come in handy. The only way AFAIK to set a variable starting at a token is by executing the code below:

token.getProcessInstance().getContextInstance().setVariable("var","value", token);

It would be more logical to be able to do it like this:

token.setVariable("var","value");

So I would suggest adding a setVariable method to Token that behaves like the createVariable of ContextInstance.