This documentation supports the 22.1 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.

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:


Related topics

Sending broadcasts to groups, services, and locations

Using the Digital Workplace Catalog API Open link

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. The token is typically sent back and forth as an AR-JWT cookie, although it can also be included inside the header.

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

NameRequired/OptionalDescriptionTypeExampleNotes
messageOptional

The message to be broadcast.

StringThis is a test broadcast.The maximum length is 4000 characters. This includes any HTML or other markup elements.
targetsRequired

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.

String"MYIT_BROADCAST_USER_GROUPS": [ "45001" ]NA
titleRequiredThe title of the broadcast.StringBroadcast TestThe maximum length is 256 characters.
urlOptionalThe URL for the title.Stringhttp://www.bmc.com/NA
broadcasttypeOptional

The type of broadcast. One of the following options:

INFORMATION, SUCCESS, WARNING, CRITICAL

StringCRITICALIf this parameter is not specified, the default is INFORMATION.
startTimeOptional

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

String1606747514NA
endTimeRequired if timeToLive is not specified

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

String1606747514At least one of endTime or timeToLive must be specified.
timeToLiveRequired if endTime is not specified

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

StringTue Jan 19, 2021 @ 12:16 PM +05:30
isServerURLOptionalIf 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.BooleantrueNA
{
    "parameters": {
        "message": "Test message",
        "targets": {
            "MYIT_BROADCAST_USER_GROUPS": [
                "45001"
            ]
        },
        "title": "Test title",
        "url": "",
        "broadcastType": "CRITICAL",
        "startTime": 1606747514,
        "endTime": 1606847514,
        "isServerUrl": ""
    }
}

Response

ResponseValueNotes
HTTP code200Successful response returns an object with each broadcast.
{
    "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 

NameRequired/OptionalDescriptionTypeExampleNotes
querynameRequired

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.

StringMYIT_ALL_BROADCAST_NOTIFICATIONSInclude this parameter in the query.
attributesRequired

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.

NameDescription
id

The broadcast ID.

titleThe broadcast title.
message

The message to be broadcast.

urlThe 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)

groupListA list of all members of the group that the broadcast is sent to.
isServerURLWhether 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.

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

Response

ResponseValueNotes
HTTP code200Returns a category list object array.
typeapplication/jsonNot applicable.
[
  {
    "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
broadcastIdRequiredThe ID of the broadcast to delete.String1234Locate this parameter in the request URL.

Response

Response

Value

Notes

HTTP code204No 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 code200Application returns the category array.
typeapplication/jsonNot applicable.


{
                "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
            } 
Was this page helpful? Yes No Submitting... Thank you

Comments

  1. Hrishikesh Limaye

    Hello, RSSO token retrieval / generation step to be added after base URI section, as suggested one is not woking using /dwp/rest/user/login Working: /dwp/restapi/users/sessions/login

    Regards, Hrishi

    Feb 26, 2024 07:30
  2. Hrishikesh Limaye

    Also it need additional parameters to be passed like apiVersion that also should be mentioned based on what tool customers are using

    Feb 26, 2024 07:31