New Notice Producers

The following steps guide new instrument, mission, or observatory producers into setting up new notices streams that are distributed to the user community via Kafka. This process requires interaction with the GCN Team to enable accounts and Kafka topics creation on the GCN Kafka broker. The GCN Team is also happy to work with the mission teams to help construct your alerts.

Start Producing Alerts

1. Sign in / Sign up

   Decide which of your team members will have programmatic access to produce your alerts. Make sure that they have all signed in at least once to the GCN website and the GCN test website.

2. Name Your Kafka Topics

   The naming convention for Kafka topics follow the format gcn.notices.mission.notices_type. The mission name should be in lowercase, and the Kafka topics should be in snake_case format, with the words in lowercase separated by underscores. Example for a single observatory, such as IceCube is gcn.notices.icecube.lvk_nu_track_search. For missions with multiple instruments, you can include the instrument name as gcn.notices.mission.instrument.notices_type, for example, Swift-BAT Kafka topic should be gcn.notices.swift.bat.alert. Pick a prefix for your Kafka topic names, mission.*.

3. Contact the GCN Team

   Send the GCN Team your list of team members from Step 1 and your chosen Kafka topic prefix from Step 2. The GCN Team will reply after they have configured producer permissions for your team.

4. Draft Your Schema

   As a GCN Notice producer, you can create your own instrument-specific schema. Please contribute your schema to our GitHub repository, placing it in a folder under gcn/notices/mission and submit a pull request for the GCN Team to review. For details, please refer to the schema documentation.

5. Build Producer Code

   • Log out and log back in.
   • Go through the Start Streaming GCN Notices process.
   • On Step 2, choose the scope gcn.nasa.gov/kafka-mission-producer.
   • Your producer code will look very similar to the client example code in Step 4 of the Start Streaming GCN Notices guide. Your client_id and client_secret can be found in Step 4 client example code.
   • Start from this and adjust the client_id, client_secret, topic and data content:

   from gcn_kafka import Producer
   # Connect as a producer.
   # Warning: don't share the client secret with others.
   producer = Producer(client_id='fill me in', client_secret='fill me in')
   # any topic starting with 'mission.'
   topic = 'gcn.notices.mission'
   # JSON data converted to byte string format
   data = json.dumps({
       '$schema': 'https://gcn.nasa.gov/schema/vX.Y.Z/gcn/notices/mission/SchemaName.schema.json',
       'key': 'value'
   }).encode()
   producer.produce(topic, data)
   producer.flush()
   

   Schema Version

   Please indicate the latest schema version (i.e., vX.Y.Z) against which the mission schema has been validated, rather than referring to the main branch.

6. Create or Update the Mission Page

   Create a new mission page by submitting a pull request or by sending text to the GCN Team.

7. Announce New Notice Types

   Work with the GCN Team to draft a community announcement, which the GCN Team will circulate.