Announcement API

This article describes API calls available for configuring Announcements in Metric Insights:

  • /api/announcement: Retrieve, create, update, delete, or perform user actions (Accept, Decline, Dismiss, Clear Dismiss) on Announcements.
  • /api/announcement_group: Retrieve, create, delete Group associations for an Announcement.
  • /api/announcement_category: Retrieve, create, delete Category associations for an Announcement.
  • /api/announcement_datasource: Retrieve, create, delete Data Source associations for an Announcement.
  • /api/announcement_element: Retrieve, create, delete Element associations for an Announcement.
  • /api/announcement_folder: Retrieve, create, delete Folder associations for an Announcement.

Prerequisites:

  • Set up API access
  • Verify that you have API access, and obtain a token via get_token call or generate a personal API Token
  • The user executing the API call must be assigned the following privileges:
    • 'Create Announcements'
    • 'Show Announcements on Homepage'
  • The user executing the API call must have edit access to the Announcements and Groups, Categories, Data Sources, Elements, Folders that are affected by the corresponding API call.

Table of contents:

  1. Access Admin > System > API Toolkit
  2. Configure Announcements
    1. Get Announcements
    2. Create Announcement
    3. Update Announcement
    4. Delete Announcement
    5. Announcement Actions: Accept, Decline, Dismiss, Clear Dismiss
  3. Configure Announcement Groups
    1. Get Announcement Groups
    2. Add Announcement Group
    3. Delete Announcement Group
  4. Configure Announcement Categories
    1. Get Announcement Categories
    2. Add Announcement Category
    3. Delete Announcement Category
  5. Configure Announcement Data Sources
    1. Get Announcement Data Sources
    2. Add Announcement Data Source
    3. Delete Announcement Data Source
  6. Configure Announcement Elements
    1. Get Announcement Elements
    2. Add Announcement Element
    3. Delete Announcement Element
  7. Configure Announcement Folders
    1. Get Announcement Folders
    2. Add Announcement Folder
    3. Delete Announcement Folder

NOTES:

1. Access Admin > System > API Toolkit

2. Configure Announcements

2.1. Get Announcements

The GET request to api/announcement returns all Announcements available to User.

  1. Item: announcement
  2. Method: GET
  3. Optionally, use filters for Announcements:
    • show_on_viewer: Whether to display Announcements that are shown on Element Viewers ("Y"/"N")
    • show_on_homepage: Whether to display Announcements that are shown on homepage ("Y"/"N")
    • show_on_apps: Whether to display Announcements that are shown on Apps ("Y"/"N")
    • category: Specify the ID of the Category to retrieve Announcements that are displayed on it.
    • folder: Specify the ID of the Folder to retrieve Announcements that are displayed on it.
    • datasource: Specify the ID of the Data Source to retrieve Announcements that are displayed on it.
    • element: Specify the ID of the Element to retrieve Announcements that are displayed on it.
    • group: Specify the ID of the Group to retrieve Announcements that are displayed on it.
    • all: Select whether to return all Announcements that are available to the user including the dismissed ones ("Y") or to return only active Announcements that are displayed on the user's homepage ("N")
  4. Enter an API Token
  5. [Run request]
  6. The returned object contains an array of objects each of which contains Announcement's data.

Example Response 

{    
   "announcements":  [       
      {            
         "id": 25,
         "enabled": "Y",
         "show_on_viewer": "N",
         "show_on_viewer_scope": "all",
         "border_color": "",
         "show_on_homepage": "Y",
         "show_on_apps": "N",
         "subject": "Special Announcement",
         "visible_to": "all",
         "time_window": "N",
         "start_time": "2023-08-09 15:40:41",
         "end_time": "2023-08-10 15:40:41",
         "updated_time": "2023-08-10 15:45:27",
         "created_by": "Robert Isaenko",
         "requires_approval": "N",
         "allow_to_dismiss": "Y",
         "html_code": "<p>Hello! This is a <strong>special</strong> announcement</p>",
         "rank": 1
      }
   ]
}

Fields Description

Field Name Value Type Description
id int The ID of the announcement.
enabled string Whether or not the announcement is enabled.
show_on_viewer string Whether or not the announcement is displayed on viewer.
show_on_viewer_scope string Whether the announcement is displayed on all elements' viewers (all) or only on selected elements' viewers (selected).
border_color string The hex value of the announcement's border color.
show_on_homepage string Whether or not the announcement is displayed on the homepage.
show_on_apps string Whether or not the announcement is displayed on Apps.
subject string The announcement's name.
visible_to string Whether the announcement is visible for everyone (all) or for defined user groups (groups).
time_window string The time interval in which the announcement is active
start_time string The time from which the announcement is displayed.
end_time string The time until which the announcement is displayed.
updated_time string The time until when the announcement was last updated.
created_by string The name of the user who created the announcement.
requires_approval string Whether or not the users who see the announcement will see the “Accept” button instead of “Dismiss”.
allow_to_dismiss string Whether or not the users who see the announcement are able to remove it from the homepage or element viewer.
html_code string The HTML code of the announcement message.
rank int The rank of the announcement.

2.2. Create Announcement

The POST request to api/announcement creates a new Announcement.

  1. Item: announcement
  2. Method: POST
  3. Enter an ID of an existing Announcement
  4. Select JSON request and enter JSON providing the needed values for your Announcement:
    • The value of id parameter is assigned automatically and does not need to be provided manually
    • All parameters that were not provided manually will be assigned default values
    • See Example Response for details on Announcement's data structure
  5. Enter an API Token
  6. [Run request]
  7. The returned object contains an array with an object with the created Announcement's data.

2.3. Update Announcement

The PUT request to api/announcement/id/<ID> updates an Announcement.

  1. Item: announcement
  2. Method: PUT
  3. Enter ID of the Announcement that needs to be updated
  4. Select JSON request and enter JSON with the updated Announcement's data
  5. Enter an API Token
  6. [Run request]
  7. The returned object contains an array with an object with the updated Announcement's data.

2.4. Delete Announcement

The DELETE request to api/announcement/id/<ID> deletes an Announcement.

  1. Item: announcement
  2. Methods: DELETE
  3. Enter ID of the Announcement that needs to be deleted
  4. Enter an API Token
  5. [Run request]

2.5. Announcement Actions: Accept, Decline, Dismiss, Clear Dismiss

  • The PUT request to api/announcement/id/<ID>  with the request body {"call": "<accept/dismiss/clear>"} accepts/dismissed/clears dismiss for an Announcement.
  • The PUT request to api/announcement/id/<ID>  with the request body {"call": "clear_user_dismiss", "user_id": <User ID>} clears dismiss for an Announcement for the selected User.
  1. Item: announcement
  2. Method: PUT
  3. Enter ID of the Announcement that needs to be updated
  4. Actions: Select an action that needs to be performed with an Announcement
  5. Enter an API Token
  6. [Run request]

3. Configure Announcement Groups

Note: In order to create or delete Announcement Groups you need to execute GET request first to obtain the value of the id property of the Announcement Group's data entry.

3.1. Get Announcement Groups

The GET request to api/announcement_group returns all Announcements' Group associations available to User.

  1. Item: announcement_group
  2. Methods: GET
  3. Optionally, use filters for Announcements' Group associations:
    • ID: Enter ID of the Announcement's Group association
    • announcement_id: Enter ID of the Announcement
    • group_id: Enter ID of the Group
  4. Enter an API Token
  5. [Run request]
  6. The returned object contains an array of objects with announcement Group data.

Example Response 

{
    "announcement_groups": [
        {
            "id": 10,
            "announcement_id": 22,
            "group_id": 53
        },
        {
            "id": 11,
            "announcement_id": 22,
            "group_id": 60
        }
    ]
}

3.2. Add Announcement Group

The POST request to api/announcement_group  with body {"announcement_id": <ID>, "group_id": <ID>} creates a new Group association for the Announcement.

  1. Item: announcement_group
  2. Methods: POST
  3. Enter ID of the existing Announcement Group's data entry
  4. Enter JSON replacing the value of the group_id  with a new Group's ID
  5. Enter an API Token
  6. [Run request]

Delete Announcement Group

The DELETE request to api/announcement_group/id/<ID> deletes an Announcement's Group association.

  1. Item: announcement_group
  2. Methods: DELETE
  3. Enter ID of the Announcement's Group association that needs to be deleted
  4. Enter an API Token
  5. [Run request]

4. Configure Announcement Categories

Note: In order to add or delete Announcement Categories you need to execute GET request first to obtain the value of the id property of the Announcement Category's data entry.

4.1. Get Announcement Categories

The GET request to api/announcement_category returns all Announcements' Category associations available to User.

  1. Item: announcement_category
  2. Methods: GET
  3. Optionally, use filters for Announcements' Category associations:
    • ID: Enter ID of the Announcement's Category association
    • announcement_id: Enter ID of the Announcement
    • category_id: Enter ID of the Category
  4. Enter an API Token
  5. [Run request]
  6. The returned object contains an array of objects with Announcement Categories' data.

Example Response 

{
    "announcement_categories": [
        {
            "announcement_id": 22,
            "category_id": 123,
            "id": 5
        },
        {
            "announcement_id": 22,
            "category_id": 86,
            "id": 6
        },
        {
            "announcement_id": 22,
            "category_id": 25,
            "id": 7
        }
    ]
}

4.2. Add Announcement Category

The POST request to api/announcement_category  with body {"announcement_id": <ID>, "category_id": <ID>} creates a new Category association for the Announcement.

  1. Item: announcement_category
  2. Methods: POST
  3. announcement_id: Enter ID of the existing Announcement Category's data entry
  4. Select JSON request and replace the value of the category_id with ID of the Category that needs to be added to the Announcement
  5. Enter an API Token
  6. [Run request]

4.3. Delete Announcement Category

The DELETE request to api/announcement_category/id/<ID> deletes an Announcement's Category association.

  1. Item: announcement_category
  2. Methods: DELETE
  3. announcement_id: Enter ID of the Announcement's Category association that needs to be deleted
  4. Enter an API Token
  5. [Run request]

5. Configure Announcement Data Sources

Note: In order to add or delete Announcement Data Sources you need to execute GET request first to obtain the value of the id property of the Announcement Data Source data entry.

5.1. Get Announcement Data Sources

The GET request to api/announcement_datasource returns all Announcements' Data Source associations available to User.

  1. Item: announcement_datasource
  2. Methods: GET
  3. Optionally, use filters for Announcements' Data Source associations:
    • ID: Enter ID of the Announcement's Category association
    • announcement_id: Enter ID of the Announcement
    • datasource_id: Enter ID of the Category
  4. Enter an API Token
  5. [Run request]
  6. The returned object contains an array of objects with Announcement's Data Source associations.

Example Response 

{
    "announcement_datasources": [
        {
            "announcement_id": 22,
            "datasource_id": "171_plugin",
            "id": 4
        },
        {
            "announcement_id": 22,
            "datasource_id": "138_sql",
            "id": 8
        },
        {
            "announcement_id": 22,
            "datasource_id": "1_sql",
            "id": 11
        }
    ]
}

5.2. Add Announcement Data Source

The POST request to api/announcement_datasource  with body {"datasource_id": "<ID>", "announcement_id": <ID>} creates a new Data Source association for the Announcement.

  1. Item: announcement_datasource
  2. Methods: POST
  3. ID: Enter ID of the existing Announcement's Data Source association
  4. Select JSON request and replace the value of the datasource_id depending on the Data Source type:
    • Plugin Data Source: <Data Source ID>_plugin
    • SQL Data Source: <Data Source ID>_sql
  5. Enter an API Token
  6. [Run request]

5.3. Delete Announcement Data Source

The DELETE request to api/announcement_datasource/id/<ID> deletes an Announcement's Data Source association.

  1. Item: announcement_datasource
  2. Methods: DELETE
  3. announcement_id: Enter ID of the Announcement's Data Source association that needs to be deleted
  4. Enter an API Token
  5. [Run request]

6. Configure Announcement Elements

Note: In order to add or delete Announcement Elements you need to execute GET request first to obtain the value of the id property of the Announcement Element's data entry.

6.1. Get Announcement Elements

The GET request to api/announcement_element returns all Announcements' Element associations available to User.

  1. Item: announcement_element
  2. Methods: GET
  3. Optionally, use filters for Announcements' Element associations:
    • ID: Enter ID of the Announcement's Element association
    • announcement_id: Enter ID of the Announcement
    • element_id: Enter ID of the Element
  4. Enter an API Token
  5. [Run request]
  6. The returned object contains an array of objects with Announcement Element's data.

Example Response 

{
    "announcement_elements": [
        {
            "id": 10,
            "announcement_id": 22,
            "element_id": 1286
        },
        {
            "id": 9,
            "announcement_id": 22,
            "element_id": 1640
        },
        {
            "id": 8,
            "announcement_id": 22,
            "element_id": 122373
        }
    ]
}

6.2. Add Announcement Element

The POST request to api/announcement_element  with body {"announcement_id": <ID>, "element_id": <ID>} creates a new Element association for the Announcement.

  1. Item: announcement_element
  2. Methods: POST
  3. ID: Enter ID of the existing Announcement's Element association
  4. Select JSON request and replace the value of the element_id with the ID of the Element that needs to be added to the Announcement
  5. Enter an API Token
  6. [Run request]

6.3. Delete Announcement Element

The DELETE request to api/announcement_element/id/<ID> deletes an Announcement's Element association.

  1. Item: announcement_element
  2. Methods: DELETE
  3. Enter ID of the Announcement's Element association that needs to be deleted
  4. Enter an API Token
  5. [Run request]

7. Configure Announcement Folders

Note: In order to add or delete Announcement Folders you need to execute GET request first to obtain the value of the id property of the Announcement Folder's data entry.

7.1. Get Announcement Folders

The GET request to api/announcement_folder returns all Announcements' Folder associations available to User.

  1. Item: announcement_folder
  2. Methods: GET
  3. Optionally, use filters for Announcements' Element associations:
    • id: The ID of the Announcement's Element association
    • announcement_id: The ID of the Announcement
    • folder_id: The ID of the Folder
  4. Enter an API Token
  5. [Run request]
  6. The returned object contains an array of objects with Announcement Folder's data.

Example Response 

{
    "announcement_folders": [
        {
            "id": 2,
            "announcement_id": 22,
            "folder_id": 120
        },
        {
            "id": 3,
            "announcement_id": 22,
            "folder_id": 28
        }
    ]
}

7.2. Add Announcement Folder

The POST request to api/announcement_folder  with body {"announcement_id": <ID>, "folder_id": <ID>} creates a new Folder association for the Announcement.

  1. Item: announcement_folder
  2. Methods: POST
  3. ID: Enter ID of the existing Announcement's Folder association
  4. Select JSON request and replace the value of the folder_id with the ID of the Folder that needs to be added to the Announcement
  5. Enter an API Token
  6. [Run request]

7.3. Delete Announcement Folder

The DELETE request to api/announcement_folder/id/<ID> deletes an Announcement's Folder association.

  1. Item: announcement_folder
  2. Methods: DELETE
  3. Enter ID of the Announcement's Folder association that needs to be deleted
  4. Enter an API Token
  5. [Run request]