GET Alerts Expiration

The GET /Alerts/Expiration operation retrieves details of all expiration alerts configured in Keyfactor Command. Query parameters support filtering using defined criteria, control over pagination by specifying the page number and return limit, and customization of sorting based on specified fields and order. On success, the operation returns HTTP 200 OK with  details about the specified alert.

Tip:  The following permissions (see Security Roles and Claims) are required to use this feature:

/monitoring/alerts/read/

Table 163: GET Alerts Expiration Input Parameters

Name In Description
QueryString Query

A string containing a query to limit the results (for example, field1 -eq value1 AND field2 -gt value2). The default is to return all records. For querying guidelines, refer to: Using Search in the Management Portal. The query fields supported for this operation are:

  • CertificateQueryId
  • Days
  • DisplayName
  • Message
  • RegisteredEventHandlerId
  • ScheduledTaskId
  • Subject
  • UseHandler
  • UseWorkflows
  • WorkflowName
PageReturned Query An integer that specifies how many multiples of the returnLimit to skip and offset by before returning results, to enable paging. The default is 1.
ReturnLimit Query An integer that specifies how many results to return per page. The default is 50. Very large values can result in long processing time.
SortField Query

A string containing the property by which the results should be sorted. Fields available for sorting through the API include:

  • CertificateQuery

  • DisplayName

  • ExpirationWarningDays

  • Message

  • Subject

  • UseWorkflows

  • WorkflowName

Available sort fields are affected by the query provided in QueryString. The default sort field is DisplayName.
SortAscending Query An integer that sets the sort order on the returned results. A value of 0 sorts results in ascending order while a value of 1 sorts results in descending order. The default is ascending.

Table 164: GET Alerts Expiration Response Data

Name

Description
Id An integer indicating the Keyfactor Command reference ID of the expiration alert.
DisplayName A string indicating the display name for the expiration alert. This name appears in the Expiration Certificate Request Alerts grid in the Management Portal.
Subject

A string indicating the subject for the email message that will be delivered when the alert is triggered.
Message

A string indicating the email message that will be delivered when the alert is triggered. The email message is made up of regular text and substitutable special text. If desired, you can format the message body using HTML.

See Table 18: Substitutable Special Text for Expiration Alerts for a complete list of available substitutable special text strings.
ExpirationWarningDays

An integer indicating the number of days before expiration to send the warning.

Alerts report on certificates that enter the configured expiration period (X days/weeks/months before expiration) between the last run and the current run. When an alert is first configured, the configuration time is treated as the last run time.

When the alert runs, each run reports only on certificates that fall into the next new time window that has not already been reported. This window is based on the prior reference time and the current execution time.

Example:  On June 30 at 5:00 PM you create a new alert with a 30-day Timeframe and schedule it to run daily at 5:00 AM.

  • On the first run (July 1 at 5:00 AM), the alert reports certificates that entered the 30-day expiration period between June 30 at 5:00 PM (configuration time) and July 1 at 5:00 AM.

  • On the next run (July 2 at 5:00 AM), the alert reports certificates that entered the 30-day expiration period between July 1 at 5:00 AM and July 2 at 5:00 AM (one day of expirations).

If alerts do not run for a period of time (for example, due to an outage), the next run uses the last successful run time and reports on all certificates that fall within the missed window. For example, an outage causing the alert not to run on July 3 would mean that the run on July 4 includes certificates that entered the 30-day expiration period between July 2 at 5:00 AM and July 4 at 5:00 AM.
Recipients

An array of strings containing the recipients for the alert. Each alert can have multiple recipients. You can use specific email addresses and/or use substitutable special text to replace an email address variable with actual email addresses at processing time.

When entering email addresses on the Recipients parameter, if more than one recipient is added to a string, all recipients in that string receive the same email and can see the other recipients on the email. To do this, enter email addresses separated by commas or semi-colons withing the string. To include multiple strings, separate each string by a comma within the array. 

"Recipients": [
 "{certemail}", 
 "pkiadmins@keyexample.com,bbrown@keyexample.com"
]

Available email substitutable special text strings include:

  • {certemail} and your custom email-based metadata field, which would be specified similarly to: {metadata:AppOwnerEmailAddress}.
CertificateQuery

An object indicating the certificate collection on which the alert is based. ClosedShow certificate querydetails.

For more information about certificate collections, see Save Search Criteria as a Collection.
RegisteredEventHandler

An object containing the event handler configuration for the alert, if applicable. ClosedShow event handler details.

For more information about event handlers, see Using Event Handlers.
EventHandlerParameters

An array of objects containing the parameters configured for use by the event handler. The type of data will vary depending on the configured handler. ClosedShow event handler parameter details.
Use Workflows A Boolean indicating whether the alert uses workflows to deliver the alerts (True) or the legacy alerting system (False).
Workflow Id A string indicating the Keyfactor Command reference GUID of the workflow used to deliver alerts for this expiration alert.
Workflow Name A string indicating the name of the workflow used to deliver alerts for this expiration alert.
Workflow Published Version An integer indicating the published version of the workflow used to deliver alerts for this expiration alert.
Workflow Enabled A Boolean indicating whether the workflow used to deliver alerts for this expiration alert is turned on (True or False).
Schedule

An object indicating the schedule for delivery of the expiration alerts. Only a daily schedule is allowed. Leave the parameter blank for no schedule. Each expiration alert is configured with its own schedule.ClosedShow schedule details.
Tip:  See the Keyfactor APIClosed An API is a set of functions to allow creation of applications. Keyfactor offers the Keyfactor API, which allows third-party software to integrate with the advanced certificate enrollment and management features of Keyfactor Command. Reference and Utility, which allows you to call API operations and view results. It is primarily intended for validation, testing, and workflowClosed A workflow is a series of steps necessary to complete a process. In Keyfactor Command, it refers to the workflow builder, which allows you to automate event-driven tasks such as when a certificate is requested, revoked or found in a certificate store. development, and also serves as an interactive supplement to this API documentation. You can access it from the help menu () in the Management Portal.