mirror of
https://github.com/BookStackApp/BookStack.git
synced 2026-02-13 11:19:37 +03:00
Allow setting meta information when creating/updating an object using the API #3795
Reference in New Issue
Block a user
Delete Branch "%!s()"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
Originally created by @zedidas on GitHub (May 10, 2023).
API Endpoint or Feature
Add a new API endpoint or modify the existing ones to support setting meta information on shelves, books, chapters, pages, etc. Using this feature should be allowed only to application administrators. As an example, the current /books endpoint could support creating or editing a book while allowing to explicitly set the following:
Additionally, when changing or setting this information, it would be good to be able to set a flag in the request body so that one can set if the "Recent Activity" is updated or not.
Use-Case
There are organizations that are using other knowledge base applications and may be compeled to move to BookStack. Organizations may want to bulk export pages from the source system and import them in BookStack, while maintaining the creation time, creator, modification time, etc.
This would allow for building scripts to replicate the entire existing knowledge base into BookStack, while keeping all the previous meta information in the system. For instance, although I may use the API to create a book with an admin account, in the end, what I need is that the book creator is set to the original creator and to the original creation time that was in the source system (Of course, this assumes that the corresponding users exist also in BookStack).
Our current use case is that we are exploring the possibility to move from another Knowledge Base/Wiki into BookStack and we have 2000+ pages to move. We have been doing some scripting, and we are able to export contents from the source system and map them into BookStack. What we miss is precisely the ability to set the meta information of the imported contents, so that it matches the source system.
Additional context
No response
@ssddanbrown commented on GitHub (May 10, 2023):
In regards to setting an owner, the recently added PUT "content-permissions" API endpoint allows setting of a new owner.
In regards to all other properties, I'm not too sure this is something I'd think would be worth supporting. I would not want to allow editing of these via the API by default, so it'd have to be via a flag or different endpoints, and I'm not sure the added complexity is really worth the, what essentially is, one time demand in this specific use-case.
For some of this (IDs specifically) you could use an intermediary mapping of ids in your migration scripts to map old system IDs to new system IDs as the content is created in the new system.
You also have the option of tags if you just need a record of the metadata after migration.
You also have the option of interacting with the database directly.
You could do most of the import via the APIs, mapping ID changes, then do a late pass on the database, setting IDs and dates as required directly there.
@zedidas commented on GitHub (May 12, 2023):
Hello and thank you for the answer. I really appreciate it!
Good to know it is possible to set the owner through the "content-permissions" API endpoint. I was not aware.
Let me, respetfully, add few more arguments in having the possibility to set meta information through the API (either with the same endpoints or with new ones - I don't have a clear opinion on that).
Using tags:
I understand that the tags will allow to save meta information and legacy information from the source system. We were considering using it for some "unmapable" attributes from the source system. Still, it would be preferable to have the creation and modification dates set on the object in BookStack, instead of having them in tags.
One shot migration
We are looking to do a one shot migration. This means that, after the migration, all the Books and Pages will have the same creation time. Thus, all books will have the same relevance (for instance in the "New Books" section, regardless of it being created 2 years ago or yesterday, in the source system).
Sorting and Recent Activity
Sorting by creation date or by modification date will be meaningless (at least until de object is modified again in BookStack). Likewise, the "Recent Activity" list will not show anything useful.
Keeping IDs from the source system
I understand that this can be done with a map of IDs between the source and the target system. Still this increases a lot any script to sinchronize 2 systems (we need to handle all sorts of references between books, chapters, pages, etc.). The way I see it is if there is no hard rule to force a specific ID in a bookstack object, then the API could support a lazy ID. I mean, if the ID is specified in the API request, then the object is created with that ID. Otherwise, the ID is generated automatically by BookStack upon creation as it is right now (I may be oversimplifying the requirement...).
Achieving synchronization
Having the possibility to set meta information and IDs may allow for use cases where you want to have 2 or more systems synchronized (without having to copy the entire databse). I can imagine situations where it could be usefull to synchronize even 2 BookStack instances. This may be useful for having a staging and a production environment and then move contents from one to another. In this situation, keeping the ID is a must, so that the same content can be correctly matched.
Facilitating the move to BookStack
For organizations considering moving to BookStack, keeping audit on the Enterprise Contents is a must (every content author and metadata must be kept, during whatever retention period). Loosing this information in a possible migration will at least make it harder for and organization to decide to move to BookStack.
Updating information in the database
I appreciate that this is a valid option. Still, changing data in the database directly is always a big risk, especially in organizations, and I would prefer to avoid it.
In conclusion, I understand that my initial requirements can be meet with some compromises and added complexity. Still I think that enhacing this kind of support in the API could be a big deciding factor for organizations thinking on adopting to BookStack. The cost of migration is often the reason why an organization will not switch to another system.
Let me finish with a word of appreciation for what is BookStack right now! It is very good in doing what it is set to do! Congratulations!
Thank you again.
@ssddanbrown commented on GitHub (May 30, 2023):
Thank for the further information. I respect your points and position but none of that really changes my viewpoint on this being worthwhile.
It may seem irregular, but when it comes to assessing additions/changes I lean very much pragmatically to current possible value, and primarily its benefit to existing users. I try to avoid considering any imagined considerations or anything designed to help adoption. Over the last 8 years I've learnt these aren't healthy things to chase since they often have a real upfront impact for an unknown potential benefit. The project is not a VC-startup chasing growth, I am not trying to make the project a market leader, I instead want to ensure a continuously improving yet stable and sustainable platform for the existing users it serves, which in turn usually brings healthier natural growth in itself.
Eh, sure it's not ideal, but it depends on the data and context. Applying it as a one-shot thing upon dates seems pretty safe to me. If you really don't want to touch the database, as an alternative you could add some custom API endpoints using our logical theme system to allowing settings dates or other data.
Can't advise either of these routes for IDs though.
Thank you very much!
Since I don't see this moving forward any further I'm going to close this off, but feel free to still comment for any guidance/info if/where needed.