Announcement API

Prerequisites:

  • Set up API access
  • Verify that you have API access and obtain a token via get_token call
  • 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

NOTE: The returned data types in v6 may vary from v7.

1. Access Admin > System > API Toolkit

2. Configure Announcements

2.1. Get Announcements

  1. Item: announcement
  2. Method: GET
  3. Select whether to return all Announcements that are available to the user ("Y") or to return only the 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_portal_page": "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_portal_page string Whether or not the announcement is displayed on Portal Pages.
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

  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

  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

  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

  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

  1. Item: announcement_group
  2. Methods: GET
  3. announcement_id: Enter ID of the Announcement
  4. Enter an API Token
  5. [Run request]
  6. The returned object contains an array of objects with announcement Group data:
    • id: The identifier of the Announcement Group's data entry
    • announcement_id: The ID of the Announcement
    • group_id: The ID of the Group

See Example Response for details.

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

  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

  1. Item: announcement_group
  2. Methods: DELETE
  3. Enter ID of the Announcement Group's data entry 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

  1. Item: announcement_category
  2. Methods: GET
  3. announcement_id: Enter ID of the Announcement
  4. Enter an API Token
  5. [Run request]
  6. The returned object contains an array of objects with Announcement Categories' data:
    • id: The identifier of the Announcement Category's data entry
    • announcement_id: The ID of the Announcement
    • category_id: The ID of the Category

See Example Response for details.

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

  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

  1. Item: announcement_category
  2. Methods: DELETE
  3. announcement_id: Enter ID of the Announcement Category's data entry 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

  1. Item: announcement_datasource
  2. Methods: GET
  3. announcement_id: Enter ID of the Announcement
  4. Enter an API Token
  5. [Run request]
  6. The returned object contains an array of objects with Announcement Data Source's data:
    • announcement_id: The ID of the Announcement
    • datasource_id: The ID of the Data Source
    • id: The identifier of the entry with Announcement Data Source's data

See Example Response for details.

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

  1. Item: announcement_datasource
  2. Methods: POST
  3. ID: Enter ID of the existing Announcement Data Source's data entry
  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

  1. Item: announcement_datasource
  2. Methods: DELETE
  3. announcement_id: Enter ID of the Announcement Data Source's data entry 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

  1. Item: announcement_element
  2. Methods: GET
  3. announcement_id: Enter ID of the Announcement
  4. Enter an API Token
  5. [Run request]
  6. The returned object contains an array of objects with Announcement Element's data:
    • id: The identifier of the entry with Announcement Element's data
    • announcement_id: The ID of the Announcement
    • element_id: The ID of the Element

See Example Response for details.

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

  1. Item: announcement_element
  2. Methods: POST
  3. ID: Enter ID of the existing Announcement Element's data entry
  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

  1. Item: announcement_element
  2. Methods: DELETE
  3. Enter ID of the Announcement Element's data entry 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

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

See Example Response for details.

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

  1. Item: announcement_folder
  2. Methods: POST
  3. ID: Enter ID of the existing Announcement Folder's data entry
  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

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