Publish notifications through the IU Notifications service

On this page:


Before you begin

You can use the CNS REST API to send notifications for an application you maintain through the IU Notifications service. To do so, you need to set up a Publisher, an API account, a notification system, and a notification type. Future integrations may need one or more of these, depending on how the integration should work.

Data classification concerns

Notifications sent through the IU Notifications service should not include data classified higher than University-Internal data, because:

  • Email systems (such as Exchange) are approved only for university internal data.
  • Push notifications are not approved for anything higher than university internal data.
  • Text message notifications are delivered to recipients through various telecom providers, and are not approved for anything higher than university internal data.
  • Future notification channels are even less secure.

In general, your notifications should link back to your system through the primary and secondary action URLs (see Notification types below) to display sensitive information to recipients. Also, you should not request that an individual provide Critical data or Restricted data in a notification sent through the IU Notification service, to avoid it being confused with a phishing scheme.

Publishers

A publisher represents a group of people who will publish notifications in the IU Notifications service. Typically, development teams want to integrate with the IU Notifications service to send notifications through their applications. A Publisher is usually set up once for a team when setting up their first integration, with future integrations reusing the same publisher.

When requesting a new publisher, provide:

  • Name: Uniquely identifies a publisher; typically the name of the team.
  • Description: Describes the publisher, and provides additional context for how it could be used. This is optional.
  • Contact email address: An email address for the IU Notifications service administrators to contact your team if issues arise, and to notify your team about new features, breaking changes, or other important information.

API account

API accounts authenticate with the IU Notifications service using an OAuth 2 Client Credentials Grant. When you request an API account, administrators will provide you with the client ID and secret you'll use to perform this authentication. An API account is tied to a single publisher, and can send notifications for any notification system belonging to that publisher

IU Notifications service admins recommend that you set up separate API accounts for each application which will integrate with the IU Notifications service. This is not required, but doing so will make it easier to rotate API accounts when the time comes. API accounts expire two years from the initial creation of the account, and cannot be extended. You will be notified before each of your API accounts expire, so you can coordinate the creation of replacement accounts. To request a new API account, provide:

  • Name: Uniquely identifies the API account. When naming the account, you may want to identify where it will be used, so you will know what needs to be updated when the account expires. The name can be up to 100 characters in any format you like.
  • Publisher: The publisher which owns this API account; optional if you are requesting a new publisher at the same time.
  • Contact email address: Optional address that is notified when the API account is about to expire. If you don't provide a contact address, IU Notifications service admins will use the publisher's contact email address.

Notification system

A notification system reflects a collection of notification types sent from a single system. A system may be used by a single application, or a collection of applications which serve a single purpose. The notification system name is displayed in the notification card in the Notification Center, and is also included in the email and push notifications sent to users. When requesting a new notification system, provide:

  • Name: The name of the system sending notifications, displayed on the notification
  • Publisher: The publisher which owns this notification system, optional if you are requesting a new publisher at the same time.
  • Test users: If you are requesting access to the IU Notifications service test instance, you may supply a list of users who will receive test email and push notifications, allowing you to test notifications without risk of notifying the intended recipients.

Notification types

A notification type identifies a single type of notification sent by a notification system. When requesting a new notification type, provide:

  • Name: Name for the type of notification being sent.
  • Key: A unique identifier passed in API calls to indicate the type of notification. If you don't provide this, admins will use the name in lowercase, replacing any spaces with hyphens.
  • Notification system: The notification system to which this type belongs, optional if you are requesting a new notification system at the same time.
  • Primary action label: Optional button label describing the primary action individuals can take on the notification; displayed on the notification in the Notification Center, on the notification detail page, in the body of any sent email messages, and as an action button on any sent push notifications. If you include a label name, also include the URL to which individuals will be sent when creating a notification through the API.
  • Secondary action label: This option labels a button for the secondary action individuals can take on the notification, and will be displayed on the notification in the Notification Center, on the notification detail page, in the body of any sent email messages, and as an action button on any sent push notifications.If you include a label name, also include the URL to which individuals will be sent when creating a notification through the API.
  • Notification delivery method(s): Every notification is sent to an individual's Notification Center by default. In addition, notifications can be sent via:
    • Email: Messages are sent to the recipient's primary IU email address, come from notifications@iu.edu, are digitally signed from that address, contain IU's standard security footer, and follow IU branding guidelines for email content.
    • Push notification: Users who have opted to receive push notifications through IU Mobile will receive a push notification on any mobile devices they've registered.
    • Text message: Notifications will be sent directly to users' phones. If you want to use this delivery method, you must provide additional information and obtain special approval:
      • You must provide a funding source to pay for any text messages sent.
      • Users must opt in to receive text messages for each notification type. Users can opt in to receive text message notifications from your application through a special URL.
      • Text messages must be sent between 9am and 8pm Eastern Time.
  • Allow urgent notification: Nearly all IU Notifications service notifications should be sent with a "normal" priority. If your integration requires recipients to take a specific action and not doing so would have some consequence, you may use "urgent" priority. An urgent notification must at least be sent through email, since the IU Notifications service can only guarantee a notification is sent through that mechanism. Other delivery methods may also be enabled, but email is a requirement. Urgent notifications are displayed at the top of a individual's Notification Center, are flagged as important in email headers, and will bypass notification preferences to guarantee the notification is sent. If you wish to have this option enabled, provide a justification for doing so, and admins will review it.

Request setup

To request setup of these components, email the One.IU team at one@iu.edu, providing the described details based on your needs.

Considerations

When working through the Publishing API Guide to create a new notification, consider:

  • Send multiple users the same notification: If you wish to send the same notification text and action URLs to multiple people, you can provide an array of them in the recipients field in a single notification.
  • Create multiple notifications in a single call: If you are sending a batch of notifications, you can include an array of notifications in a single POST request.
  • Summary, description, and SMS description: Three similar fields on a notification are shown in different contexts; each of them optional. A notification's summary is displayed anywhere a short summary of the content of a notification is required, including the display in the Notification Center, and push notifications (at this time). The description field allows more content, supports Markdown syntax, and is displayed where longer content is desirable. This includes a notification's detail view in the Notification Center, and in the body of any email messages sent for the notification. The SMS description is a short summary which is shown if the notification is delivered as a text message, which allows you to customize the messaging for the shorter format of text messages. If you do not provide an SMS description, the summary will be used instead.

This is document avhu in the Knowledge Base.
Last modified on 2024-01-26 16:18:05.