This documentation supports the 23.3 version of BMC Helix Digital Workplace Basic and BMC Helix Digital Workplace Advanced. Icons distinguish capabilities available only for the Advanced and External license levels. For more information, see License types and features.To view an earlier version, select the version from the Product version menu.

Using Broadcast API endpoints in the BMC Helix Digital Workplace REST API

These endpoints of the BMC Helix Digital Workplace REST API manage broadcast notifications. These endpoints are intended to be used by a third-party script or program to interact with and control BMC Helix Digital Workplace, enabling you to automate broadcast notifications.

Select from the following for information about using the REST API for broadcast notifications:


Required license

DWP Advanced icon.pngBMC Helix Digital Workplace Advanced

Related topics

Sending-broadcasts-to-groups-services-and-locationsUsing the Digital Workplace Catalog API

Using the BMC Helix Digital Workplace REST API

The API follows the REST architectural style, so resources, HTTP verbs, and status codes are used. JSON is used for request and response bodies.

Transport scheme

You access the BMC Helix Digital Workplace REST API over the transport scheme that is configured for your application server, either HTTP or HTTPS. You can call API endpoints from any scripting or programming language that supports the configured transport scheme.

Base URI

The following base URI is used for calling the BMC Helix Digital Workplace  server: /dwp/rest/.

Call the API endpoint from the full application host URL. If the host URL includes a port number, include the port number in your requests. Preface the URL with the correct scheme (HTTP/HTTPS).

Examples of the base URI follow:

Base URI format type

Example

Local machine

http://localhost:9000/dwp/rest

HTTPS connection

https://calbroservices.com:8443/dwp/rest

HTTP connection

http://calbroservices.com:9000/dwp/rest

A server without a port assigned to it

http://calbroservices.com/dwp/rest

Default header 

Unless an API endpoint requires a different header, the following header is required for all requests:

Content-Type: application/json
X-Requested-By: <any_value>

To be able to make REST API calls, you need to log in to the application with a system-generated session token. Depending on your BMC system configuration, you might retrieve the token by using the users/login endpoint, or by obtaining a BMC Helix Single Sign-On token. A session token is valid for about 30 minutes, depending on your system configuration.

The session token must be included in all subsequent calls for the system to trust requests from the application or script that has been granted that token.

Broadcast API endpoints and actions

The following sections describe the actions you can perform using the Broadcast API endpoints.

To create and send a broadcast

You specify a list of user IDs, user email addresses, locations, groups, or services as recipients of the broadcast.

POST /dwp/rest/sendbroadcast

Parameters

Name

Required/Optional

Description

Type

Example

Notes

message

Optional

The message to be broadcast.

String

This is a test broadcast.

The maximum length is 4000 characters. This includes any HTML or other markup elements.

targets

Required

A list of the targets for the broadcast. Specify the type of target, and then the numeric IDs of the targets of that type, as demonstrated in the Example column.

Users: MYIT_BROADCAST_USER_IDS (list of user IDs)
User emails: MYIT_BROADCAST_USER_EMAILS (list of user email addresses)
User groups: MYIT_BROADCAST_USER_GROUPS (list of user groups)
Locations: MYIT_BROADCAST_LOCATIONS (list of location IDs)
Services: MYIT_BROADCAST_SERVICES (list of service IDs)

Note that a single API call can only send one type of target.

JSON object

{"MYIT_BROADCAST_USER_GROUPS": [ "45001" ]}

NA

title

Required

The title of the broadcast.

String

Broadcast Test

The maximum length is 256 characters.

url

Optional

The URL for the title.

String

http://www.bmc.com/

NA

broadcasttype

Optional

The type of broadcast. One of the following options:

INFORMATION, SUCCESS, WARNING, CRITICAL

String

CRITICAL

If this parameter is not specified, the default is INFORMATION.

startTime

Optional

The start time for the broadcast, in UNIX timestamp format.

Integer

1606747514

NA

endTime

Required if timeToLive is not specified

The end time for the broadcast when a start time is specified, in UNIX timestamp format.

integer

1606747514

At least one of endTime or timeToLive must be specified.

timeToLive

Required if endTime is not specified

The end time for the broadcast when it is intended to go live immediately.

String

Tue Jan 19, 2021 @ 12:16 PM +05:30

isServerURL

Optional

If the url parameter is specified, set this parameter to true if the URL is a server-side address, or false if the URL is a client-side address.

Boolean

true

NA

Example request body
{
   "parameters": {
       "message": "Test message",
       "targets": {
           "MYIT_BROADCAST_USER_GROUPS": [
               "45001"
            ]
        },
       "title": "Test title",
       "url": "",
       "broadcastType": "CRITICAL",
       "startTime": 1606747514,
       "endTime": 1606847514,
       "isServerUrl": ""
    }
}

Response

Response

Value

Notes

HTTP code

200

Successful response returns an object with each broadcast.

Example response body
{
   "SendBroadcast": [
        {
           "timeToLive": 1606847514000,
           "sentAsynchronously": "true",
           "timeOfOrigin": "Mon Nov 30, 2020 @ 04:45 PM +02:00"
        }
    ]
}

To retrieve all broadcasts

This endpoint provides administrators with a list of all broadcasts that match the search criteria specified in the query.

POST /dwp/rest/search

Parameters

Name

Required/Optional

Description

Type

Example

Notes

queryname

Required

To return information about all broadcast notifications, set this parameter to MYIT_ALL_BROADCAST_NOTIFICATIONS.

To return information about only the active broadcast notifications, set this parameter to MYIT_ACTIVE_BROADCAST_NOTIFICATIONS.

String

MYIT_ALL_BROADCAST_NOTIFICATIONS

Include this parameter in the query.

attributes

Required

This parameter consists of a list of the fields to return that include information about the broadcast notification. The following table lists the fields that can be included.

String

"attributes": { "BroadcastNotification": ["id"] }

Include this parameter in the query. BroadcastNotification must be included.

Broadcast notification attributes

Use the attributes parameter to specify which of these attributes to include. The search returns information about these attributes for each broadcast.

Name

Description

id

The broadcast ID.

title

The broadcast title.

message

The message to be broadcast.

url

The URL associated with the broadcast title.

broadcastStartDate

The start date for the broadcast, in UNIX timestamp format.

broadcastEndDate

The end date for the broadcast, in UNIX timestamp format.

createDate

The date that the broadcast was created, in UNIX timestamp format.

modifiedDate

The date that the broadcast was last modified, in UNIX timestamp format.

broadcastType

The type of broadcast.

0: INFORMATION
1: SUCCESS
2: WARNING
3: CRITICAL

broadcastGroupType

The type of group that the broadcast is sent to.

0: MYIT_BROADCAST_USER_GROUPS (list of user groups)
1: MYIT_BROADCAST_LOCATIONS (list of location IDs)
2: MYIT_BROADCAST_SERVICES (list of service IDs)
3: MYIT_BROADCAST_USER_IDS (list of user IDs)
4: MYIT_BROADCAST_USER_EMAILS (list of user email addresses)

groupList

A list of all members of the group that the broadcast is sent to.

isServerURL

Whether the broadcast title URL is server-side or client-side.

status

The status of the broadcast.

ACTIVE, INACTIVE, STARTING_SOON, SCHEDULED

externalBroadcast

true if the broadcast is sent from BMC Helix ITSM.

false if the broadcast is sent from BMC Helix Digital Workplace.

Example request body
{
 "queryName": "MYIT_ALL_BROADCAST_NOTIFICATIONS",
 "attributes": {
   "BroadcastNotification": [
     "id",
     "title",
     "message",
     "url",
     "broadcastStartDate",
     "broadcastEndDate",
     "createDate",
     "modifiedDate",
     "broadcastType",
     "broadcastGroupType",
     "groupList",
     "isServerUrl",
     "status",
     "externalBroadcast",
    ]
  }
}

Response

Response

Value

Notes

HTTP code

200

Returns a category list object array.

type

application/json

Not applicable.

Example response body
[
  {
   "items": [
      {
       "externalBroadcast": false,
       "groupList": [
          {
           "id": "Allen",
           "name": "Allen"
          },
          {
           "id": "dkramer",
           "name": "dkramer"
          }
        ],
       "title": "TEST HELLO NEW",
       "message": null,
       "url": null,
       "broadcastStartDate": 1664873901000,
       "broadcastType": 0,
       "broadcastGroupType": 3,
       "broadcastEndDate": 1669112477000,
       "modifiedDate": 1664873902,
       "isServerUrl": 0,
       "id": "AGGADGG8ECDC2AR9IAX0R9IAX05TWP",
       "createDate": null,
       "status": "INACTIVE"
      },
      {
       "externalBroadcast": false,
       "groupList": [
          {
           "id": "45001",
           "name": "MyIT Admin"
          }
        ],
       "title": "Yellow broadcast",
       "message": "<p><span style=\"color:#8e44ad;\"><u><em><strong><span style=\"background-color:#2ecc71;\">learn more broadcast</span></strong></em></u></span></p>",
       "url": null,
       "broadcastStartDate": 1664962101000,
       "broadcastType": 2,
       "broadcastGroupType": 0,
       "broadcastEndDate": 1665566843000,
       "modifiedDate": 1664962101,
       "isServerUrl": 0,
       "id": "AGGADGG8ECDC2AR9JWZJR9JWZJUAOZ",
       "createDate": null,
       "status": "ACTIVE"
      }
    ],
   "syncTime": 1672317277,
   "dataSourceName": "BroadcastNotification",
   "numMatch": 2
  }
]

To remove a broadcast

POST /dwp/rest/BroadcastNotification/{broadcastId}/delete

Parameters

Name

Required

Description

Type

Example

Notes

broadcastId

Required

The ID of the broadcast to delete.

String

1234

Locate this parameter in the request URL.

Response

Response

Value

Notes

HTTP code

204

No content.

To retrieve a broadcast

This endpoint retrieves information about a broadcast for an end user.

GET /dwp/rest/v2/activity_stream/notifications?type=broadcast

Parameters

None.

Response

Response

Value

Notes

HTTP code

200

Application returns the category array.

type

application/json

Not applicable.

    • ====
Example response body
{
               "createdByType": null,
               "createdById": null,
               "createdByLastName": null,
               "createdByFirstName": null,
               "createdByThumbnail": null,
               "feedObjectType": "broadcast",
               "feedText": "Critical",
               "feedData": "{\"feedId\":\"AGGADGG8ECDC0AQ9OTKCQ8Q9O4UHAM\",\"status\":\"ACTIVE\",\"title\":\"Test\",\"url\":\"http://ipshenyc.bmc.com:9000/dwp/admin/broadcasts/send.html\",\"style\":\"WARNING\",\"expirationDate\":1605789420000}",
               "commentCount": 0,
               "likeCount": 0,
               "selfLike": false,
               "sharedBy": null,
               "referencedBy": null,
               "onBehalf": null,
               "order": 1,
               "isAif": false,
               "disposition": "sticky",
               "attachmentMetadata": "[]",
               "attachmentCount": 0,
               "inlineCommentSubmitter": null,
               "inlineCommentText": null,
               "inlineCommentCreateDate": null,
               "inlineCommentAttachmentNames": null,
               "score": null,
               "availableActions": [],
               "id": "9aa52ab6-9fff-48c3-b944-959d121a1a87",
               "createDate": 1605191304666,
               "modifiedDate": 1605191304666
            } 

 

Tip: For faster searching, add an asterisk to the end of your partial query. Example: cert*