Documentation Home

Configuring Automatic Degraded Service Events Notifications

Creating a Status Message
Application Services
Sending Notification Emails
Updating Application Status
Updating Application Status through API

Creating a Status Message

There are multiple status types that a status message can have

OK - When the client application is performing nominally without issues.
ISSUE - Degradation of service that falls outside of Service Level Objectives, but is not causing any effects to application functionality.
OUTAGE - Severe degradation of service that prevents a majority of users from using core application functionality.
MAINTENANCE - Known operation that will cause a disruption of service.

When services are not configured status messages can be configured from the application edit page.

After clicking the 'Add New Status Message' button a form will populate with the follow fields

Incident Type - A dropdown menu of the options OK, ISSUE, OUTAGE, MAINTENANCE. This determines what type of message that will be displayed as well as the color of the status.
Service Key - This is a unique one word description of your notification that will be used for updating the status through the API. This is not shown to the end user.
Subject - Subject is a short description of the incident that will be used as the subject of email notifications and will be displayed on the homepage and Tophat banners.
What's Happening - What's happening is a longer description of the message and will be displayed when the status notification is clicked on and in the body of notification emails.
Action Needed - Action Needed is to inform the user of action that needs to be taken to prevent service interruption and will be displayed when the status notification is clicked on and in the body of notification emails.
Who is Affected? - Who is Affected is to inform the user if they are affected by the current incident and will be displayed when the status notification is clicked on and in the body of notification emails.
Support - Support is where users can reach out to get further assistance and will be displayed when the status notification is clicked on and in the body of notification emails.

Application Services

Depending on your application setup, it may be useful to configure application services to allow for multiple distinct statuses within a single client application. This can be done from the client application edit page as shown below.

After clicking the 'Add New Service' button, you will be directed to a new page to enter a name, description, and a unique key for your service. Please note, the Service Key is used for internal distinction, is only seen by your client application's admins and cannot be changed after creation.

When services are configured each individual service will need its own status messages which can be configured through the service edit pages.

Once 'Add New Status Message' is clicked, the same form from Creating a Status Message will populate.

If the application is configured to display its current status on the homepage, each individual service and its status will be shown.

Sending Notification Emails

When changing the status of your client application there is an option to send an email detailing the status change.
By default, the email will be sent to 'earthdata-status-internal@lists.nasa.gov' but can be changed at the application level on the client application edit page to instead send to one or more addresses. The email will contain a table with the information from the status message.

If you have services configured, you can have an additional message sent when all services are back to normal. This is intended to prevent confusion when multiple services are degraded at one time but are restored one-by-one.

Updating Application Status

Client application statuses can be updated through the Earthdata Status app from the client application edit page. When the client application does not have services the status that you set will be the status that the homepage will show.

When the application does have services the status is updated through each individual service. The top level application status is then aggregated and the service with the worst status will become the application's status. The ranking of the statuses is
1. OUTAGE
2. ISSUE
3. MAINTENANCE
4. UNKNOWN
5. OK

Updating Application Status through API

Client applications statuses can be updated through an API to allow for automated status updates through a third party application such as OpsGenie.
To use this API, you must be an application admin with a client application that has an API key and a status message.
Optionally, you can also set the status of a service of your application and you must have a status message for that service.

To update an application status you need to make a POST to http://{Base_URL}/update_application_status with the API Key in a Bearer header and passing the key of the status to update to as a parameter.

Parameters

key: Key of status message to update to. - Required
service_key: Key of the service to be updated.
email_notify: Boolean flag to send an email notification. Optional, defaults to false.

Example calls

curl --request POST \
  --url 'https://status.earthdata.nasa.gov/update_application_status?key=OK' \
  --header 'Authorization: Bearer d51033ee-70d0-47c0-b893-ca4356b86a4a'

To update an application service status you need to make a POST to http://{Base_URL}/update_application_status with the API Key in a Bearer header and passing the key of the status to update to and the key of the service to update as parameters.

curl --request POST \
  --url 'http://status.earthdata.nasa.gov/update_application_status?key=OK&service_key=exampleService' \
  --header 'Authorization: Bearer d51033ee-70d0-47c0-b893-ca4356b86a4a'

Additionally, you can use this endpoint to send an email to addresses that are configured for your application. This requires sending an email_notify flag with your update status call.

curl --request POST \
  --url 'http://status.earthdata.nasa.gov/update_application_status?key=OK&email_notify=true' \
  --header 'Authorization: Bearer d51033ee-70d0-47c0-b893-ca4356b86a4a'

and when updating service

curl --request POST \
  --url 'http://status.earthdata.nasa.gov/update_application_status?key=OK&service_key=exampleService&email_notify=true' \
  --header 'Authorization: Bearer d51033ee-70d0-47c0-b893-ca4356b86a4a'