BookStack Code Mirror - website/blob - content/blog/bookstack-release-v21-12.md

 1 +++
 2 categories = ["Releases"]
 3 tags = ["Releases"]
 4 title = "BookStack Release v21.12"
 5 date = 2021-12-22T18:00:00Z
 6 author = "Dan Brown"
 7 image = "/images/blog-cover-images/reindeer-joe-green.jpg"
 8 slug = "bookstack-release-v21-12"
 9 draft = false
 10 +++
 11
 12 To end 2021 I'm pleased to announce BookStack v21.12 has now been released.
 13 Upon a bunch of fixes & improvements, this release features outgoing webhooks in
 14 addition to new abilities which allow copying entire chapters and books.
 15
 16 * [Update instructions](https://www.bookstackapp.com/docs/admin/updates)
 17 * [GitHub release page](https://github.com/BookStackApp/BookStack/releases/tag/v21.12)
 18
 19
 20 **Upgrade Notices**
 21
 22 - **Security Releases** - There were a couple of security vulnerabilities found during the life of
 23   v21.11. See the [v21.11.2](/blog/bookstack-release-v21-11-2/) and [v21.11.3](/blog/bookstack-release-v21-11-3/) posts for more details.
 24
 25
 26 ### Outgoing Webhooks
 27
 28 BookStack can now emit webhooks! These are web requests that are emitted by BookStack
 29 when someone performs an action in the system (Updates page, Creates book etc..).
 30 Webhooks can be found by an administrator in the application settings.
 31
 32 ![Webhook list in settings](/images/2021/12/webhooks_list.png)
 33
 34 Webhooks can be triggered by any event that's tracked in the audit log. You can choose
 35 specific events to trigger your webhooks or you can trigger upon any event.
 36
 37 ![Webhook from view](/images/2021/12/webhook_form.png)
 38
 39 When triggered, BookStack will send a HTTP POST JSON request to the provided endpoint
 40 with a common set of details regarding the event. The general data format is shown when creating
 41 or editing a webhook, but the below is an example of a "page_update" event:
 42
 43 ```json
 44 {
 45     "event": "page_update",
 46     "text": "Benny updated page \"My wonderful updated page\"",
 47     "triggered_at": "2021-12-11T22:25:10.000000Z",
 48     "triggered_by": {
 49         "id": 1,
 50         "name": "Benny",
 51         "slug": "benny"
 52     },
 53     "triggered_by_profile_url": "https://bookstack.local/user/benny",
 54     "webhook_id": 2,
 55     "webhook_name": "My page update webhook",
 56     "url": "https://bookstack.local/books/my-awesome-book/page/my-wonderful-updated-page",
 57     "related_item": {
 58         "id": 2432,
 59         "book_id": 13,
 60         "chapter_id": 554,
 61         "name": "My wonderful updated page",
 62         "slug": "my-wonderful-updated-page",
 63         "priority": 2,
 64         "created_at": "2021-12-11T21:53:24.000000Z",
 65         "updated_at": "2021-12-11T22:25:10.000000Z",
 66         "created_by": 1,
 67         "updated_by": 1,
 68         "draft": false,
 69         "revision_count": 9,
 70         "template": false,
 71         "owned_by": 1
 72     }
 73 }
 74 ```
 75
 76 Webhooks have a `text` property (Populated where possible, depending on event) which allows them to
 77 be used directly in slack or slack-compatible services. If you wanted to get more advanced
 78 you could build your own middleware or use a service like [Zapier](https://zapier.com/) or [n8n](https://n8n.io/)
 79 to build more advanced event based integrations. For example:
 80
 81 - Email an admin when application settings are changed.
 82 - Post in slack when a book is deleted.
 83 - Log page changes to a Google doc.
 84 - Update a BookStack page via the REST API when new users register.
 85
 86 The possibilities are pretty endless.
 87
 88 Since webhooks need to make external HTTP requests, they have potential to slow down a system.
 89 If you're introducing webhooks that'd be triggered we have a way to run these in the background to
 90 prevent user experience slowdowns. [Details about this can be found here](/docs/admin/email-webhooks/#async-action-handling).
 91
 92 ### Copy Entire Chapters & Books
 93
 94 It's been possible to copy a page for a while now. With v21.12 it's now possible to
 95 copy entire chapters or even books. Performing this action will also copy all child chapters
 96 and/or pages in a single smooth action. Copy views will now show warnings to confirm
 97 copy behavior within BookStack so the necessary considerations can be made.
 98
 99 ![Book copy view](/images/2021/12/copy_book.png)
 100
 101 These new abilities bring some great potential new workflow advancements, such as being
 102 able to create "templated" books pre-configured with the right chapter & page structure
 103 ready to be copied out.
 104
 105 ### Copy Roles
 106
 107 When creating or updating a role there are a lot of permissions to configure.
 108 Creating a set of similar roles could be a time consuming experience.
 109 As of v21.12 there's now a "Copy" action when viewing an existing role which
 110 will take you to the role create view with all fields filled as per the copied role.
 111
 112 ![Role copy button](/images/2021/12/copy_role.png)
 113
 114 ### Audit Log IP Address Search
 115
 116 The audit log has received another update thanks to [@johnroyer](https://github.com/BookStackApp/BookStack/pull/3081).
 117 It's now possible to search the audit log by IP address.
 118 The search is a prefix-match so you can search using just the starting
 119 portion if needing to search a range.
 120
 121 ![IP address search in audit log](/images/2021/12/audit_log_search.png)
 122
 123 ### Search API Updates
 124
 125 In v21.11 we added the new search API endpoint. Within v21.11.3 a few extra useful properties
 126 were added to item response data:
 127
 128 ```json
 129 {
 130    ...
 131     "url": "https://example.com/books/my-book/page/how-advanced-are-cats",
 132     "preview_html": {
 133       "name": "How advanced are <strong>cats</strong>?",
 134       "content": "<strong>cats</strong> are some of the most advanced animals in the world."
 135     },
 136    ...
 137 }
 138 ```
 139
 140 These additions save you from needing to do extra work to formulate the full
 141 item URL or preview content.
 142
 143 ### Logical Theme System Custom Commands
 144
 145 The [logical theme system](https://github.com/BookStackApp/BookStack/blob/master/dev/docs/logical-theme-system.md)
 146 has been extended to allow registration of custom commands. These are actions you'd typically
 147 run on command line via `php artisan bookstack:<command>`.
 148
 149 I recently produced a getting started guide for the local theme system which includes
 150 registering custom commands:
 151
 152 <iframe width="100%" height="360" src="https://www.youtube.com/embed/YVbpm_35crQ" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>
 153
 154
 155 ### Translations
 156
 157 As always our awesome translators have been doing their work to keep language
 158 content up-to-date. The below are the great contributions since v21.11:
 159
 160
 161 ### Full List of Changes
 162
 163 **Released in v21.12**
 164
 165 * Added webhooks. ([#147](https://github.com/BookStackApp/BookStack/pull/147), [#3099](https://github.com/BookStackApp/BookStack/pull/3099))
 166 * Added ability to copy books, chapters & roles. ([#3118](https://github.com/BookStackApp/BookStack/pull/3118), [#1123](https://github.com/BookStackApp/BookStack/issues/1123))
 167 * Added audit log IP address search. Thanks to [@johnroyer](https://github.com/BookStackApp/BookStack/pull/3081). ([#3081](https://github.com/BookStackApp/BookStack/pull/3081))
 168 * Updated translations with latest Crowdin changes. ([#3117](https://github.com/BookStackApp/BookStack/pull/3117))
 169 * Fixed issue where non-ascii content could break search result previews. Thanks to [@Kristian-Krastev](https://github.com/BookStackApp/BookStack/pull/3113). ([#3113](https://github.com/BookStackApp/BookStack/pull/3113))
 170 * Fixed mismatched password validation rules across the application. ([#2237](https://github.com/BookStackApp/BookStack/issues/2237))
 171
 172 **Released in v21.11.1 through v21.11.3**
 173
 174 * Added custom command support to the logical theme system. ([#3072](https://github.com/BookStackApp/BookStack/pull/3072))
 175 * Added support for `prefers-contrast` media setting to increase contrast in faded areas when active. ([#2634](https://github.com/BookStackApp/BookStack/issues/2634))
 176 * Updated user search to help prevent discovery and harvesting of user information. Thanks @haxatron for reporting. ([#3108](https://github.com/BookStackApp/BookStack/issues/3108))
 177 * Updated search API results to include the highlighted preview content. ([#3096](https://github.com/BookStackApp/BookStack/issues/3096))
 178 * Updated search API results to include item URL. ([#3080](https://github.com/BookStackApp/BookStack/issues/3080))
 179 * Updated translations with latest Crowdin changes. ([#3093](https://github.com/BookStackApp/BookStack/pull/3093), [#3076](https://github.com/BookStackApp/BookStack/pull/3076), [#3057](https://github.com/BookStackApp/BookStack/pull/3057))
 180 * Updated TOTP confirmation view to autofocus on code input. Thanks to [@raccettura](https://github.com/BookStackApp/BookStack/pull/3068). ([#3068](https://github.com/BookStackApp/BookStack/pull/3068))
 181 * Updated any links on homepage lists to be more obvious & accessible. ([#3046](https://github.com/BookStackApp/BookStack/issues/3046))
 182 * Fixed issue with greater-than-expected visibility on page-draft-related items. Thanks @haxatron for reporting. ([#3086](https://github.com/BookStackApp/BookStack/issues/3086))
 183 * Fixed issue where public API access was not limited by system public control in certain conditions. ([#3091](https://github.com/BookStackApp/BookStack/issues/3091))
 184 * Fixed faulty page navigation links when headers are nested within other content. Thanks to [@Julesdevops](https://github.com/BookStackApp/BookStack/pull/3069). ([#3069](https://github.com/BookStackApp/BookStack/pull/3069), [#3058](https://github.com/BookStackApp/BookStack/issues/3058))
 185
 186 ### Next Steps
 187
 188 Focus going into next year will be on the editor. I've started assessing new options but found it difficult to focus
 189 the time needed this year, so it will be my priority going into 2022.
 190
 191 I have continued to produce more videos on the [BookStack YouTube channel](https://www.youtube.com/channel/UCH66RFWfw6CSm2T1EM4ik1g).
 192 I'll look to continue this when wanting to get away from code-level work for a bit.
 193
 194 ----
 195
 196 <span style="font-size: 0.8em;opacity:0.9;">Header Image Credits: <span>Photo by <a href="https://unsplash.com/@jg?utm_source=unsplash&amp;utm_medium=referral&amp;utm_content=creditCopyText">Joe Green</a> on <a href="https://unsplash.com/?utm_source=unsplash&amp;utm_medium=referral&amp;utm_content=creditCopyText">Unsplash</a></span></span>