diff --git a/doc/api/broadcast_messages.md b/doc/api/broadcast_messages.md index 5aca0667f319a39cff61d7813dbbcc4fb826aa29..a14de8dadd32daecc749f10208e8e5744e75a450 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 987d7444ae011e7ea7078bf9a588a2dec3b3ccd2..69cb2f04c4d7e0102dcf1f8fc70981749c5400bf 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**. diff --git a/lib/api/broadcast_messages.rb b/lib/api/broadcast_messages.rb index 0762c276aad1d7562562e2ece6394515324b9107..e081265b4181c23ce5ef9be46ceb51c33dabbb3a 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 e42b110adbeac7c24204ca00812f10386670d11c..5a31d64fd868c5d3835bb8004b4b585d636e5ab0 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 b023ec398a20ef184ee0ae4669a14a30d07b20b8..76412c80f4c8c35ec9fd6548ad6885d07e4ad113 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' }