Managed topics

What is a managed topics collection?

Initially built as a lightweight version of the standard Tags API, the topics collection differs in a few key aspects:

  • Topics collection are enabled during the installation of Totara Engage
  • There is no administrator access to disable topics
  • The topics collection is specifically for categorising Totara Engage content
  • Topics are site-wide for all Totara Engage users
  • Users will need to assign at least one topic to each Totara Engage knowledge resource (article), playlist or survey they create

How managed topics collections work

The topics collection ensures that topics, which work like tags, are only available for Totara Engage content.   

To manage topics go to Site administration > Topic > Manage topics here you can add new topics, edit existing topics, or delete existing topics.

If you got to Site administration > Topic > Usage of topics then you will find a searchable report showing how many instances of each topic have been assigned to the various content types.

Main API classes and methods

ClassPurpose
totara_topic\hook\get_deleted_topic_usagesList of content pieces affected by deletion of a topic (for notifying authors)
totara_topic\resolver\resolverEnable components to add a topic to an instance of the component
totara_topic\webapi\resolver\query\find_topicsReturns topic objects for list of topic names
totara_topic\webapi\resolver\query\system_topicsReturns list of system-wide Topics

When creating new types in Totara Engage that will utilise topics, remember to define $tagareas.  See ./server/totara/engage/resources/article/db/tag.php as an example for resource articles.

How to add a new managed topics collection

Topics is a special case of tags, therefore it is not expected that a new similar collection will be required and we recommend that any new collections follow the standard Tags API instead.