From ebde9bd680b0644f3177aa62f078a3bf9d3b95bf Mon Sep 17 00:00:00 2001 From: eugielimpin Date: Thu, 3 Feb 2022 15:44:30 +0800 Subject: [PATCH 1/2] Update API to accept BroadcastMessage target_access_levels attribute --- lib/api/broadcast_messages.rb | 4 ++++ lib/api/entities/broadcast_message.rb | 2 +- spec/requests/api/broadcast_messages_spec.rb | 23 ++++++++++++++++++-- 3 files changed, 26 insertions(+), 3 deletions(-) diff --git a/lib/api/broadcast_messages.rb b/lib/api/broadcast_messages.rb index 0762c276aad1d7..e081265b4181c2 100644 --- a/lib/api/broadcast_messages.rb +++ b/lib/api/broadcast_messages.rb @@ -36,6 +36,8 @@ def find_message optional :ends_at, type: DateTime, desc: 'Ending time', default: -> { 1.hour.from_now } optional :color, type: String, desc: 'Background color' optional :font, type: String, desc: 'Foreground color' + optional :target_access_levels, type: Array[Integer], coerce_with: Validations::Types::CommaSeparatedToIntegerArray.coerce, + values: BroadcastMessage::ALLOWED_TARGET_ACCESS_LEVELS, desc: 'Target user roles' optional :target_path, type: String, desc: 'Target path' optional :broadcast_type, type: String, values: BroadcastMessage.broadcast_types.keys, desc: 'Broadcast type. Defaults to banner', default: -> { 'banner' } optional :dismissable, type: Boolean, desc: 'Is dismissable' @@ -76,6 +78,8 @@ def find_message optional :ends_at, type: DateTime, desc: 'Ending time' optional :color, type: String, desc: 'Background color' optional :font, type: String, desc: 'Foreground color' + optional :target_access_levels, type: Array[Integer], coerce_with: Validations::Types::CommaSeparatedToIntegerArray.coerce, + values: BroadcastMessage::ALLOWED_TARGET_ACCESS_LEVELS, desc: 'Target user roles' optional :target_path, type: String, desc: 'Target path' optional :broadcast_type, type: String, values: BroadcastMessage.broadcast_types.keys, desc: 'Broadcast Type' optional :dismissable, type: Boolean, desc: 'Is dismissable' diff --git a/lib/api/entities/broadcast_message.rb b/lib/api/entities/broadcast_message.rb index e42b110adbeac7..5a31d64fd868c5 100644 --- a/lib/api/entities/broadcast_message.rb +++ b/lib/api/entities/broadcast_message.rb @@ -3,7 +3,7 @@ module API module Entities class BroadcastMessage < Grape::Entity - expose :id, :message, :starts_at, :ends_at, :color, :font, :target_path, :broadcast_type, :dismissable + expose :id, :message, :starts_at, :ends_at, :color, :font, :target_access_levels, :target_path, :broadcast_type, :dismissable expose :active?, as: :active end end diff --git a/spec/requests/api/broadcast_messages_spec.rb b/spec/requests/api/broadcast_messages_spec.rb index b023ec398a20ef..76412c80f4c8c3 100644 --- a/spec/requests/api/broadcast_messages_spec.rb +++ b/spec/requests/api/broadcast_messages_spec.rb @@ -17,7 +17,7 @@ expect(response).to include_pagination_headers expect(json_response).to be_kind_of(Array) expect(json_response.first.keys) - .to match_array(%w(id message starts_at ends_at color font active target_path broadcast_type dismissable)) + .to match_array(%w(id message starts_at ends_at color font active target_access_levels target_path broadcast_type dismissable)) end end @@ -28,7 +28,7 @@ expect(response).to have_gitlab_http_status(:ok) expect(json_response['id']).to eq message.id expect(json_response.keys) - .to match_array(%w(id message starts_at ends_at color font active target_path broadcast_type dismissable)) + .to match_array(%w(id message starts_at ends_at color font active target_access_levels target_path broadcast_type dismissable)) end end @@ -77,6 +77,16 @@ expect(json_response['font']).to eq attrs[:font] end + it 'accepts target access levels' do + target_access_levels = [Gitlab::Access::GUEST, Gitlab::Access::DEVELOPER] + attrs = attributes_for(:broadcast_message, target_access_levels: target_access_levels) + + post api('/broadcast_messages', admin), params: attrs + + expect(response).to have_gitlab_http_status(:created) + expect(json_response['target_access_levels']).to eq attrs[:target_access_levels] + end + it 'accepts a target path' do attrs = attributes_for(:broadcast_message, target_path: "*/welcome") @@ -171,6 +181,15 @@ expect { message.reload }.to change { message.message }.to('new message') end + it 'accepts a new target_access_levels' do + attrs = { target_access_levels: [Gitlab::Access::MAINTAINER] } + + put api("/broadcast_messages/#{message.id}", admin), params: attrs + + expect(response).to have_gitlab_http_status(:ok) + expect(json_response['target_access_levels']).to eq attrs[:target_access_levels] + end + it 'accepts a new target_path' do attrs = { target_path: '*/welcome' } -- GitLab From 607bcecdbf8a6098081b42d2cbd1baee7c5df44f Mon Sep 17 00:00:00 2001 From: eugielimpin Date: Tue, 8 Feb 2022 10:23:10 +0800 Subject: [PATCH 2/2] Update broadcast messages docs --- doc/api/broadcast_messages.md | 70 ++++++++++++++++------- doc/user/admin_area/broadcast_messages.md | 5 +- 2 files changed, 52 insertions(+), 23 deletions(-) diff --git a/doc/api/broadcast_messages.md b/doc/api/broadcast_messages.md index 5aca0667f319a3..a14de8dadd32da 100644 --- a/doc/api/broadcast_messages.md +++ b/doc/api/broadcast_messages.md @@ -6,6 +6,8 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Broadcast Messages API **(FREE SELF)** +> 'target_access_levels' [introduced](https://gitlab.com/gitlab-org/growth/team-tasks/-/issues/461) in GitLab 14.8 [with a flag](../administration/feature_flags.md) named `role_targeted_broadcast_messages`. Disabled by default. + Broadcast messages API operates on [broadcast messages](../user/admin_area/broadcast_messages.md). As of GitLab 12.8, GET requests do not require authentication. All other broadcast message API endpoints are accessible only to administrators. Non-GET requests by: @@ -39,6 +41,7 @@ Example response: "font":"#FFFFFF", "id":1, "active": false, + "target_access_levels": [10,30], "target_path": "*/welcome", "broadcast_type": "banner", "dismissable": false @@ -77,6 +80,7 @@ Example response: "font":"#FFFFFF", "id":1, "active":false, + "target_access_levels": [10,30], "target_path": "*/welcome", "broadcast_type": "banner", "dismissable": false @@ -93,21 +97,31 @@ POST /broadcast_messages Parameters: -| Attribute | Type | Required | Description | -|:----------------|:---------|:---------|:------------------------------------------------------| -| `message` | string | yes | Message to display. | -| `starts_at` | datetime | no | Starting time (defaults to current time). Expected in ISO 8601 format (`2019-03-15T08:00:00Z`) | -| `ends_at` | datetime | no | Ending time (defaults to one hour from current time). Expected in ISO 8601 format (`2019-03-15T08:00:00Z`) | -| `color` | string | no | Background color hex code. | -| `font` | string | no | Foreground color hex code. | -| `target_path` | string | no | Target path of the broadcast message. | -| `broadcast_type`| string | no | Appearance type (defaults to banner) | -| `dismissable` | boolean | no | Can the user dismiss the message? | +| Attribute | Type | Required | Description | +|:-----------------------|:------------------|:---------|:------------------------------------------------------| +| `message` | string | yes | Message to display. | +| `starts_at` | datetime | no | Starting time (defaults to current time). Expected in ISO 8601 format (`2019-03-15T08:00:00Z`) | +| `ends_at` | datetime | no | Ending time (defaults to one hour from current time). Expected in ISO 8601 format (`2019-03-15T08:00:00Z`) | +| `color` | string | no | Background color hex code. | +| `font` | string | no | Foreground color hex code. | +| `target_access_levels` | array of integers | no | Target access levels (roles) of the broadcast message.| +| `target_path` | string | no | Target path of the broadcast message. | +| `broadcast_type` | string | no | Appearance type (defaults to banner) | +| `dismissable` | boolean | no | Can the user dismiss the message? | + +The `target_access_levels` are defined in the `Gitlab::Access` module. The +following levels are valid: + +- Guest (`10`) +- Reporter (`20`) +- Developer (`30`) +- Maintainer (`40`) +- Owner (`50`) Example request: ```shell -curl --data "message=Deploy in progress&color=#cecece" \ +curl --data "message=Deploy in progress&color=#cecece&target_access_levels[]=10&target_access_levels[]=30" \ --header "PRIVATE-TOKEN: " \ "https://gitlab.example.com/api/v4/broadcast_messages" ``` @@ -123,6 +137,7 @@ Example response: "font":"#FFFFFF", "id":1, "active": true, + "target_access_levels": [10,30], "target_path": "*/welcome", "broadcast_type": "notification", "dismissable": false @@ -139,17 +154,27 @@ PUT /broadcast_messages/:id Parameters: -| Attribute | Type | Required | Description | -|:----------------|:---------|:---------|:--------------------------------------| -| `id` | integer | yes | ID of broadcast message to update. | -| `message` | string | no | Message to display. | -| `starts_at` | datetime | no | Starting time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`) | -| `ends_at` | datetime | no | Ending time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`) | -| `color` | string | no | Background color hex code. | -| `font` | string | no | Foreground color hex code. | -| `target_path` | string | no | Target path of the broadcast message. | -| `broadcast_type`| string | no | Appearance type (defaults to banner) | -| `dismissable` | boolean | no | Can the user dismiss the message? | +| Attribute | Type | Required | Description | +|:-----------------------|:------------------|:---------|:------------------------------------------------------| +| `id` | integer | yes | ID of broadcast message to update. | +| `message` | string | no | Message to display. | +| `starts_at` | datetime | no | Starting time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`) | +| `ends_at` | datetime | no | Ending time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`) | +| `color` | string | no | Background color hex code. | +| `font` | string | no | Foreground color hex code. | +| `target_access_levels` | array of integers | no | Target access levels (roles) of the broadcast message.| +| `target_path` | string | no | Target path of the broadcast message. | +| `broadcast_type` | string | no | Appearance type (defaults to banner) | +| `dismissable` | boolean | no | Can the user dismiss the message? | + +The `target_access_levels` are defined in the `Gitlab::Access` module. The +following levels are valid: + +- Guest (`10`) +- Reporter (`20`) +- Developer (`30`) +- Maintainer (`40`) +- Owner (`50`) Example request: @@ -169,6 +194,7 @@ Example response: "font":"#FFFFFF", "id":1, "active": true, + "target_access_levels": [10,30], "target_path": "*/welcome", "broadcast_type": "notification", "dismissable": false diff --git a/doc/user/admin_area/broadcast_messages.md b/doc/user/admin_area/broadcast_messages.md index 987d7444ae011e..69cb2f04c4d7e0 100644 --- a/doc/user/admin_area/broadcast_messages.md +++ b/doc/user/admin_area/broadcast_messages.md @@ -7,7 +7,9 @@ type: reference, howto # Broadcast messages **(FREE SELF)** -GitLab can display broadcast messages to all users of a GitLab instance. There are two types of broadcast messages: +> Target roles [introduced](https://gitlab.com/gitlab-org/growth/team-tasks/-/issues/461) in GitLab 14.8 [with a flag](../../administration/feature_flags.md) named `role_targeted_broadcast_messages`. Disabled by default. + +GitLab can display broadcast messages to users of a GitLab instance. There are two types of broadcast messages: - Banners - Notifications @@ -66,6 +68,7 @@ To add a broadcast message: - `text-decoration` 1. Select one of the suggested background colors, or add the hex code of a different color. The default color is orange. 1. Select the **Dismissable** checkbox to enable users to dismiss the broadcast message. +1. Optional. Select **Target roles** to only show the broadcast message to users with the selected roles. The message displays on group, subgroup, and project pages, and does not display in Git remote responses. 1. If required, add a **Target Path** to only show the broadcast message on URLs matching that path. You can use the wildcard character `*` to match multiple URLs, for example `mygroup/myproject*`. 1. Select a date for the message to start and end. 1. Select **Add broadcast message**. -- GitLab