Merge branch 'broadcast-messages-api/add-target-access-levels' into 'master'

Update API to accept BroadcastMessage target_access_levels attribute

See merge request gitlab-org/gitlab!79820

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: <your_access_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

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**.

lib/api/broadcast_messages.rb

@@ -36,6 +36,8 @@ module API
         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 @@ module API
         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'

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

spec/requests/api/broadcast_messages_spec.rb

@@ -17,7 +17,7 @@ RSpec.describe API::BroadcastMessages do
       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 @@ RSpec.describe API::BroadcastMessages do
       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 @@ RSpec.describe API::BroadcastMessages do
         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 @@ RSpec.describe API::BroadcastMessages do
         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' }