Avoid changing updated_by for some API scenarios

[jaapert]

API Endpoint or Feature

Changes to a book/ chapter/ page via the API (i.e. PUT /books/{id}) result in an updated update_at and updated_by field. It would be beneficial to avoid this for some automated processes because this confuses users (a resource seems to be unintentionally changed without them knowing why).

For most API calls this is exactly what should happen, but it should be possible to avoid this in specific circumstances. I see three possible ways:

1. Disable this behavior with an extra argument to the PUT calls. This extra argument should only be accepted if the user has appropriate (admin) permissions, because regular users should not be able to avoid "audit logging" by disabling this for their own requests.
2. Add option to configure specific tokens as 'transparent' in the UI. Only admins should be able to mark a token as 'transparent'. When a token has this option enabled the updated_at and updated_by fields should be left unchanged for all PUT calls.
3. Add support for updating the updated_by and updated_at fields via the PUT endpoints; practically overriding the default behavior. We can then do a GET first and set the updated_at/ updated_by to the previous user/ date. Again, only users with appropriate permissions should be able to do this.

Use-Case

• Dynamic tags: when tags are dynamically created and/ or updated via the API, the updated_at and updated_by fields are, as expected, updated to the user who executed the call. This becomes confusing when for example a webhook triggered the PUT call: then the book gets a new updated_by, right after the user saves his changes.
• Automated processes might want to (in bulk) update books/ chapters/ pages 'transparently' to end users; keeping the updated_by to a real person instead of an API user, used for automation.

The current automatic updated_at and updated_by behavior prevents any process from doing its work transparently,

Additional context

No response

[ssddanbrown]

Thanks for the suggestion @jaapert.
This is a little related to #1777.

Personally, I'm not too keen on adding complexity to support edge cases where you want to hide activity/actions like this.

I'm not totally sure on your scenario, and the use of the "dynamic tags" referenced, but it may be possible to move your dynamic content to its own page, then make use of include tags to import that content into the original page. Then you can focus your API updates on the new "dynamic content" page, to allow that change to be reflected when viewing the original page, without that update affecting the activity of the original page at all.

[jaapert]

Thanks for your quick reply and I understand your point about being hesitant to adding complexity to support all kinds of minor edge cases.

You referenced #1777 already; and it also is a little related to #4416. Given the references I don't think this really is an edge case; since everybody using the API for any automation/ bulk related tasks would potentially benefit from this.

About my case of dynamic tags: I use this to keep track of book versions and I use the tag value in a custom PDF export theme. So every page edit fires a webhook, which checks the current version tag, increments it and pushes the incremented version tag back to the book. This is for my use case needed because I need version numbers for entire (exported) books instead of page specific revision ids. This is indeed a corner case, but I imagine many more use cases for generating dynamic tags (creating tags on the fly, based on automated content analysis for one example; I'm sure there are many more). I consider the tag system one of BookStacks powers; adding flexibility to it and creating opportunity to integrate with other (custom) tools as well. It is just a bummer that using it this way confuses the end user by changing the 'Updated by' field in the UI to something unexpected (from the end users perspective).

I explicitly tried to formulate my proposal to support not only my specific corner case; but to be usable for everybody who wants to use automation to interact with their books. I think this adds flexibility for the tool as a whole; much broader than just my specific case.

Hope this gives some context and a possibility for reconsideration ;)

Thanks again!

[ssddanbrown]

Ah, I thought we had a similar request (#4416) but could not find it earlier. I feel that has the same fundamental request as this thread so I'll likely close this off in favor of that existing issue.

To be honest, I don't really fully understand what you're doing, but since you're triggering upon BookStack activity, and wanting to write back into BookStack without activity, it sounds like something well suited for the logical theme system.
Using this you could hook into page edit events, then read/write back to books/pages however you want with full control.

Here's the closest kind of hack I have to-hand, but it does something completely different:
https://www.bookstackapp.com/hacks/autosort-tagged-books/

[hieste]

Hello Dan, have same issue. I have a user called translateengine, with an API Token. Everytime somebody change/update/create a page the translate engine translate text, index the result and put into tags. In the updatefiel_user then there is user translateengine. It would be nice if the old user wouldn't be changed.

Stefan

[zoryatix]

Just throwing in my 2 cents here. I'm usually using the API user to do bulk changes or automate certain process (like a review function for stale documentation). These things cause a lot of changes and pollutes the recent activity view. I don't think the process or reason really matters here. Recent activity is a visible to all and is great for changes done by actual users. But it loses it purpose when showing changes done by the API user. I as admin would usually look at the audit log in case I need to track changes done by the API account.

If it was possible to filter on recent activity, like we can with the audit log, then that would solve the problem for me at least.

[jaapert]

Hi!

All comments considered, I think it's safe to assume that more users would like to avoid bulk- or other API tasks to pollute the activity tab.

Maybe an easier fix would be to just exclude certain users completely from activity views. I think this fixes most cases, since those API use cases are probably mostly done by dedicated API users. I think a profile (or token) setting 'Hide from activity' would good enough.

What do you think, is this something that can be implemented?

Thanks in advance!