Is it possible to update a Note to tag and notify users when no one is tagged?

I played around but was only partially successful.  I was able to update the tags for an existing note using a Custom API Call module.  It did notify the two users with the update via email (and I can verify that the users are tagged  by checking with another API call).  However, the tags are not visible when refreshing the actual note in Workfront, and when I reply to the note, the added tags do not carry over.

API call to update the note tags (the query value is pulling in the note ID from an earlier module):

Confirming that the tags were added:

The UI showing no tags on the note or reply:

Short answer: yes, you can add tags to the existing note. You don't have to create a new one.

The call is a PUT to /attask/api/v17.0/note/<note ID>, passing an updates parameter that contains a tags array. Each entry in that array needs three keys: objObjCode set to USER, objID set to the user ID, and userID set to that same user ID.

The objObjCode is the part that usually gets missed. A bare userID is not enough, and leaving objObjCode out returns an objCode cannot be null error that refers to the tag record rather than to the note, which sends people looking in the wrong place.

Now the part that explains what Kristen saw, because it isn't a bug and it's worth knowing before you build on it. That call creates the tag record, and the tag record is what drives the notification, which is why the emails went out. What it does not do is change noteText. The visible @Name in a Workfront update is literal text sitting in the note body; the tag collection is a separate thing that handles who gets notified. Adding a tag after the fact gives you the notification with nothing new appearing on screen. You're watching those two halves come apart.

I checked the obvious workaround and it's a dead end, so you can skip it. The tag record carries startIdx and length fields that look like character offsets into the note body, which would be the natural mechanism for making a mention render. They read zero on every tag record I sampled, including notes written in the UI whose mentions display correctly. They aren't driving the rendering, and setting them won't help.

On tags not carrying over to replies: that one is structural rather than a bug. A reply is its own note record with its own tags collection, so nothing inherits downward. If the reply is what should notify someone, the reply needs its own tag.

Two more things worth knowing while you're in here. The tags collection replaces rather than merges, so sending an empty tags array clears every tag on the note, and that is the only way to remove one, because there is no delete endpoint for tag records. And because the visible mention has to live in noteText, if what you need is for people to see they were tagged, posting a reply that tags them is more reliable than editing the original. If you only need them notified, updating the original is fine and genuinely works.

One caveat on my end: I confirmed the tag persists and the note body stays untouched against v17 on a sandbox. I didn't test the email delivery itself, so that part I'm taking from Kristen's report above.

The NOTE payload shape and the objObjCode trap are written up in the API knowledge base I keep open-sourced: github.com/Thousand-Cuts/wf-toolkit

Thank you both! The visuals are super helpful I’m not that familiar how to do this (to me) complex work and more comfortable with the visual guidance. Which brings me to my question for seanabar I’ve tried to do what you have explained above but I get an invalid ID every time. Also, it sounds like the tag will never show on the update/note unless I create a new one or reply so if this is all just send a notification I’m there with a previous scenario.

Again, thank you so much for your guidance it is very much appreciated.

=D