Create Topics from Another Database

You are here: Communications Cloud API v1 > Common Uses > Create Topics from Another Database

Create Topics from Another Database

In addition to automatically generating bulletins from external systems, you can use the API to set up automatic topic creation. For example, if you have a system that tracks the creation of legislative bills, you could elect to create a new topic for each bill added to this system. This allows concerned citizens (subscribers) to follow updates for that particular bill. It often helps to group topics of this nature under a category.

There are a number of approaches you can take, based on what you want to accomplish, but one approach might be:

Set up the system to trigger a new topic when a bill is added.
Create a nightly process to check the status and update the category of topics.

1. Set up the system to trigger a new topic when a record is added.

Configure your system to send a request to the API using the Create a Topic method when a specific type of record, such as a new bill, is added. We recommend assigning the same category to each topic created, such as a category labeled "Bills Under Discussion".

Operation

Send a POST to /api/account/ACCOUNT_CODE/topics.xml

Your ACCOUNT_CODE can be found via the administrative interface.

Example Input

<topic>
  <code>####</code>
  <name>ENTER NAME</name>
  <short-name>####</short-name>
  <description nil="true"></description>
  <send-by-email-enabled type="boolean">false</send-by-email-enabled>
  <wireless-enabled type="boolean">false</wireless-enabled>
  <rss-feed-url nil="true"></rss-feed-url>
  <rss-feed-title nil="true"></rss-feed-title>
  <rss-feed-description nil="true"></rss-feed-description>
  <pagewatch-enabled type="boolean">true</pagewatch-enabled>
  <pagewatch-suspended type="boolean">false</pagewatch-suspended>
  <default-pagewatch-results type="integer" nil="true"></default-pagewatch-results>
  <pagewatch-autosend type="boolean">false</pagewatch-autosend>
  <pagewatch-type type="integer">1</pagewatch-type>
  <watch-tagged-content type="boolean">false</watch-tagged-content>
  <pages type="array">
    <page>
      <url>http://####.com</url>
    </page>
  </pages>
  <visibility>Listed</visibility>
</topic>

Elements

Click to view

Note: Fields with an asterisk (*) are required.

<code>	A code is systematically assigned by GovDelivery when a topic is created in the administrative interface. When creating a topic via the API, you choose the code, or leave it blank to have it be system-generated. Any code you choose must be unique (i.e., not used by an existing topic). This code can be changed by an administrator to anything that benefits their organizational purposes.
<name>*	Name of the topic. This name is for internal purposes and is not displayed to the public.
<short-name>*	A short version of the topic's name. This is the name that subscribers will see and can be modified for organizational purposes.
<description>	Description of the topic. This is optional, but recommended. Topic descriptions can be seen by subscribers on your organization's subscription pages, giving them more information about the updates they'll receive. Because this field can be left empty, the nil="true" attribute is required.
<send-by-email-enabled>	This is an optional feature that allows the user to send communications via GovDelivery using a third-party email device. Contact Customer Support at GovDelivery if you want this feature enabled. If this feature is not activated, enter a value of False. This field requires the type="boolean" attribute.
<wireless-enabled>	This field requires a value of either True or False and the type="boolean" attribute. Set this field to true to enable wireless alerts (sent via SMS/text) for the topic.
<rss-feed-url>	The URL for the topic's public RSS feed. This is an account option and must be enabled by GovDelivery prior to use. Contact Customer Support at GovDelivery if you want this feature enabled. Because this field can be left empty, the nil="true" attribute is required.
<rss-feed-title>	The title of the topic's public RSS feed. Because this field can be left empty, the nil="true" attribute is required.
<rss-feed-description>	A short description of the topic's public RSS feed. Because this field can be left empty, the nil="true" attribute is required.
<pagewatch-enabled>	This field requires a value of either True or False and the type="boolean" attribute. Set this to true to enable Page Wage to automatically watch for content updates and notify subscribers of updates
<pagewatch-suspended>	This field requires a value of either True or False and the type="boolean" attribute. Set this to true to temporarily suspend Page Watch. This does not remove any previous pagewatch results.
<default-pagewatch-results>	Set the number of Page Watch results that are stored in GovDelivery. Note that GovDelivery saves the last (specified number) of changes, non-changes, and errors for each Page Watch URL. This field requires a number value and the type="integer" attribute. If you leave this field blank, GovDelivery save the last 10 Page Watch schedules by default. Because this field can be left empty, the nil="true" attribute is also required.
<pagewatch-autosend>	This field requires a value of either True or False and the type="boolean" attribute. Set this to true to enable Page Watch to automatically notify your subscribers via a bulletin when your web pages are updated.
<pagewatch-type>	This field indicates the type of web accessible entity that will be monitored by Page Watch. There are three possible values for this field: 1: HTML page 2: RSS/Atom feed 3: File Enter the number corresponding to the correct type. This field requires a number value and the type="integer" attribute. Because this field can be left empty, the nil="true" attribute is also required.
<watch-tagged-content>	This field requires a value of either True or False and the type="boolean" attribute. Set this to true to enable GovDelivery to only watch particular sections of a web page by tagging content with this topic. Sections to be watched in a page are indicated by a set of HTML tags. Learn more about Page Watch.
<pages>	This field must include the type="array" attribute. You will enter any pages you want to include in Page Watch in each nested <page> field.
<page>	You can include multiple <page> fields in your input; one for each page to be monitored for this topic.
<URL>	The URL of the web page or RSS feed to be monitored by Page Watch for this topic. These pages or feeds must be publicly accessible (i.e., not behind a firewall), and you must include "http://" in the URL. This field is nested within the <page> element.
<visibility>	This sets the visibility of the topic on the Quick Subscriber page. There are three possible values for this field: Listed: The topic is displayed Unlisted: The topic is not displayed. However, subscribers can sign up for updates by a direct link to the topic that can be placed on your website. Restricted: The topic is not displayed. Subscribers can be added for this topic via API or by a CSV upload in the administrative interface.
<categories>	This field must include the type="array" attribute. You will enter any categories you want to include for this topic in each nested <category> field. Any categories not included this list are removed from the topic's categories list. To delete all categories from a topic, include an empty categories array.
<category>	You can include multiple <category> fields in your input; one for each category to be assigned to this topic. The code for the category will be included in a nested <code> element. Use the List Categories method to find the codes in your account.

Example Output

<?xml version="1.0" encoding="UTF-8"?>
<topic>
  <to-param>TOPIC_CODE</to-param>
  <topic-uri>/api/account/ACCOUNT_CODE/topics/TOPIC_CODE.xml</topic-uri>
</topic>

Troubleshooting

2. Create a nightly process to check the status and update the category of topics.

To maintain your topic organization, it might help to set up a nightly process to check your system for certain changes and then trigger updates to associated topics. In the example of a system that tracks legislative bills, a nightly process could check the status of each bill to see if it has changed to something indicating it was passed or voted down. Any bill flagged as such would trigger the Update a Topic method to change the category for that topic. Topics for bills that have passed might go under a category like, "Active Bills". Topics for bills that were voted down might go under a category like, "Blocked Bills."