Set up notifications using notification templates

You're viewing Apigee Edge documentation.
Go to the Apigee X documentation. info

What are notification templates?

Monetization provides a set of templates that define sample text for various types of event notifications. You can customize any of these templates to:

  • Notify all developers about events such as new products, new versions of T&C's, or new rate plans.
  • Notify affected developers about events such as a revised rate plan.
  • Notify an API provider, about developer-related events such as when a developer registers for an account or when a developer signs up for a rate plan.
  • Notify all company administrators about a specific event.

Alternatively, you can create a webhook that defines an HTTP callback handler, then configure the condition that triggers the webhook, as described in Set up notifications using webhooks.

Exploring the Notifications page

Access the Notifications page, as described below.

Edge

To access the Notifications page using the Edge UI:

  1. Sign in to apigee.com/edge.
  2. Select Publish > Monetization > Notifications in the left navigation bar.

The Notifications page is displayed.

As highlighted in the figure, the Notifications page enables you to:

Classic Edge (Private Cloud)

To access the Notifications page using the Classic Edge UI:

  1. Sign in to http://ms-ip:9000, where ms-ip is the IP address or DNS name of the Management Server node.

  2. Select Admin > Notifications in the top navigation bar.

The Notifications page enables you to:

Editing notifications

To edit a notification using the UI:

  1. Access the Notifications page.
  2. Click adjacent to the notification that you want to edit to expand its details.
  3. Edit the Subject, Body, and Recipient (if available) fields, as required.

    For information about variables that can be specified within a notification template, see Using variables in notification templates.

    Refer to the following sections for more information about editing notifications in each caetgory:

  4. Enable a notification by selecting the check box adjacent to it.
  5. Repeat steps 2 through 4 to edit additional notifications.
  6. Click Save to save all changes.

A message is displayed to confirm that the notifications have been saved. The save operation may take a few minutes.

Editing notifications to Notify All Developers

Notifications for the types of events you select in the Notify All Developers section are sent to all developers.

The notifications are scheduled to run at the end of the day. After the notifications have been sent, the event checkboxes are automatically cleared. You must select them again to schedule notifications for the associated event types.

The following table lists the notifications based on event types in the Notify All Developers section. For more information, see Editing notifications using the UI.

Event Type Trigger Notes
New package New API package is available

Add the name of each new package (and the products contained in each package) to the body of the email template as part of your update. You can also add a link to the developer portal or any other website that provides more information about the notification.
New product New API product is available

Add the name of each new product to the body of the email template as part of your update. You can also add a link to the developer portal or any other website that provides more information about the notification.
New Markets/Coverage New API products are available in specific geographic markets

Add the name of each new market and pertinent products to the body of the email template as part of your update. You can also add a link to the developer portal or any other website that provides more information about the notification.

Editing notifications to Notify Affected Developers

Notifications for the types of events you select in the Notify Affected Developers section are sent to only the developers affected by those types of events. For example, if you select the Revised rate plan event, a notification is sent only to the developers that have accepted the rate plan.

The following table lists the notifications based on event types in the Notify Affected Developers section. For more information, see Editing notifications using the UI.

Event Type Trigger Notes
T&C not accepted or expired New set of T&Cs has been published and the developer has not yet accepted them

The notification is sent 30 days, 7 days, and 1 day before the new T&Cs are due to go into effect.
New rate plan New rate plans is published

If the rate plan is a:

  • Standard plan, all developers are notified.
  • Developer category rate plan, only developers in that category are notified.
  • Developer rate plan, only the specific developer are notified.
Revised rate plan Newer version of a purchased rate plan is available

Only the developers that purchased the current version will be notified. The notification allows the developers to review the new version, and terminate or switch plans if they do not wish to accept the new rates.
Expired Rate plan Rate plan is expired with no follow-up rate plan

This notification is sent when you initially set the rate plan to expire, with additional notifications sent 30, 7, and 1 day before the expiration date. Only those developers who have purchased the rate plan to be expired will be notified.
Renewed Rate Plan Rate plan subscription has been renewed.

Inform developer that applicable fees will be charged.
Rate Limit Exceeded Rate plan limit has been exceeded

Inform developer that applicable fees will be charged.
Depleted Freemium Rate Plan Free usage periods, measured by transaction count or days, have been depleted

The free usage period is defined by your freemium rate plan.
Billing Document published

Billing documents (such as invoices) for the developer are available.
Developer signs up for new Rate Plan Developer signs up for a new rate plan.

Editing notifications to Notify API Providers

Notifications for the types of events you select in the Notify API Provider section are sent to the API provider you specify.

The following table lists the notifications based on event types in the Notify API Provider section. For more information, see Editing notifications using the UI.

Event Type Trigger
New Developer Signs Up

Developer has registered for an account.
Developer Adds an App

Developer has created a new application.
Developer Sign Up for New Rate Plan

Developer has signed up for a rate plan.
Developer changes financial details

Developer has changed financial details, such as his company name or company address.

Enabling or disabling a notification

To enable or disable a notification using the UI:

  1. Access the Notifications page.
  2. Enable or disable a notification by selecting or deselecting, respectively, the check box adjacent to it.
  3. Click Save to save all changes.

The save operation may take a few minutes. A message is displayed to confirm that the notifications have been saved.

Setting up notifications using templates using the API

Set up notifications using the API, as described in the following sections.

Managing notification templates using the API

Manage notification templates using the API, as described in the following sections:

Viewing all notification templates using the API

You can list all the notification templates that monetization provides by issuing a GET request to /mint/organizations/{org_name}/notification-email-templates. For example:

curl -H "Accept:application/json" -X GET \
  "https://api.enterprise.apigee.com/v1/mint/organizations/myorg/notification-email-templates" \
  -u email:password

For example, the following is an event template that notifies developers of the availability of a new API product:

{
    "createdDate" : 1376975394984,
    "htmlImage" : "<p>Dear ${developer.legalName} , ${developer.name} <br /> Introducing _________. For more details visit us at _________________</p>",
    "id" : "4d81ea64-d005-4010-b0a7-6ec8a5c3954b",
    "name" : "DEFAULT_NEW_PRODUCT_TEMPLATE",
    "orgId" : "myorg",
    "source" : "Mail Man Test",
    "subject" : "Notification of new product",
    "updatedDate" : 1376975394984
}

Viewing a notification template using the API

View a notification template by issuing a GET request to /mint/organizations/{org_name}/notification-email-templates/{template_id}, where {template_id} is the ID of the template. For example:

curl -X GET "https://api.enterprise.apigee.com/v1/mint/organizations/{org_name}/notification-email-templates/4d81ea64-d005-4010-b0a7-6ec8a5c3954b" \
  -H "Accept:application/json"  \
  -u email:password

The items in the templates that begin with $ are variables. For more information, see Using variables in notification templates. Assume that the variables in the notification evaluate to the following values:

  • ${developer.legalName}.XYZ company
  • ${developer.name}.DEV1
  • ${QUOTA_TYPE}.Transactions
  • ${PERCENT}.90%
  • ${QUOTA_UNIT}.Calls
  • ${QUOTA_LIMIT}.100
  • ${ratePlan.monetizationPackage.products.name}.X
  • ${EXPIRY_DATE}.2016-09-30

The notification message provided by the template would be:

    "Dear XYZ company, DEV1
    You have exceeded Transactions of 90% calls of 100 calls for X product. Your API calls will be blocked till 2016-09-30"

Editing a notification template using the API

Edit a notification template by issuing a PUT request to /nint/organizations/{org_name}/notification-email-templates/{template_id}. Provide the changed content of the template in the request body.

When you customize the message in a notification template, you can include one or more variables. For more information, see Using variable in notification templates.

For example, the following request edits the content of a new API product notification:

curl -X PUT "https://api.enterprise.apigee.com/v1/mint/organizations/{org_name}/notification-email-templates/4d81ea64-d005-4010-b0a7-6ec8a5c3954b " \
  -H "Content-Type: application/json" \
  -d '{
    "id" : "4d81ea64-d005-4010-b0a7-6ec8a5c3954b",
    "htmlImage" : "<p>Exciting news, we have added a new product :${Product.name}. See details in <a href="${Product.url}">New Products</a> </p>",
    "name" : "NewProductNotification",
    "organization": {
    "id": "{org_name}"
    },
    "source" : "Mail Man Test ",
    "subject" : "New Product Available: ${Product.name}"
  }' \
  -u email:password

Managing notification conditions and actions using the API

Manage notification conditions and actions using the API, as described in the following sections.

Creating a notification condition and action using the API

Create a notification condition and action that results in an automatic notification by issuing a POST request to /mint/organizations/{org_name}/notification-conditions.

When you make the request, specify in the request body the condition that results in the notification, and the actions to be taken when the condition is reached (such as sending a notification email).

You define the details of the notification condition by specifying one or more attribute values. See Configuration properties for notification conditions for a list of attributes. For an event notification, the condition might be triggered when a new product is published.

When defining the actions, reference the applicable notification template. See Configuration properties for notification actions for a list of actions.

For example, the following request specifies that when the attribute is NEW_PRODUCT and the value of the attribute PUBLISHED is true, send the notification in the template with the ID 01191bf9-5fdd-45bf-8130-3f024694e63 (this is the DEFAULT_NEW_PRODUCT_TEMPLATE).

curl -X POST "https://api.enterprise.apigee.com/v1/mint/organizations/{org_name}/notification-conditions" \
  -H "Content-Type:application/json"
  -d '{
    "notificationCondition": [
    {
      "attribute": "NEW_PRODUCT"
    },
    {
      "attribute": "PUBLISHED",
      "value": "true"
    }
    ],
    "actions": [{
      "actionAttribute": "DEV_ID",
      "value": "ANY",
      "templateId": "01191bf9-5fdd-45bf-8130-3f024694e63"
    }]
  }' \
  -u email:password

Viewing a notification condition and action using the API

View a notification condition and action by issuing a GET request to organizations/{org_name}/notification-conditions/{condition_Id}, where {condition_Id} is the ID of the condition. The ID is returned when you create the notification condition. For example:

curl -X GET "https://api.enterprise.apigee.com /v1/mint/organizations/{org_name}/notification-conditions/2d08d03f-8a54-4e75-bd6f-9c9da2f53fc4" \
  -H "Accept:application/json" \
  -u email:password

The following provides an example of the response:

    {
    "actions" : [ {
    "actionAttribute" : "DEV_ID",
    "id" : "141ba00c-d7bd-4fef-b339-9d58b83255f4",
    "templateId" : "766aba4f-0f7a-4555-b48e-d707c48b8f4c",
    "value" : "ANY"
    }, {
    "actionAttribute" : "ORG_EMAIL",
    "id" : "21486ce1-4290-4a55-b415-165af3e93c9d",
    "templateId" : "efa4ce63-7c08-4876-984b-6878ec435994",
    "value" : "DEFAULT_LIMIT_NOTIFICATION_EMAIL"
    } ],
    "notificationCondition" : [ {
    "attribute" : "Balance",
    "id" : "2d08d03f-8a54-4e75-bd6f-9c9da2f53fc4",
    "organization" : {
    ...
    },
    "value" : "< 0"
    } ]
    }

Editing a notification condition and action using the API

Edit a notification condition and action by issuing a POST request to organizations/{org_name}/notification-conditions/{condition_Id}, where {condition_Id} is the ID of the condition. The ID is returned when you create the notification condition. When you issue the request, specify in the request body the changes that you want to make to the notification condition or action.

For example:

   $ curl -H "Content-Type:application/json" -X POST -d \
    ' {
    "notificationCondition": [
    {
      "attribute": "NEW_PRODUCT"
    },
    {
    "attribute": "PUBLISHED",
    "value": "true"
    }
    ],
    "actions": [{
      "actionAttribute": "DEV_ID",
      "value": "ANY",
      "templateId": "01191bf9-5fdd-45bf-8130-3f024694e63"
    }]
    }' \
    "https://api.enterprise.apigee.com/v1/mint/organizations/{org_name}/notification-conditions/2d08d03f-8a54-4e75-bd6f-9c9da2f53fc4" \
  -u email:password

Deleting a notification condition and action using the API

Delete a notification condition by issuing a DELETE request to organizations/{org_name}notification-conditions/{condition_Id}. For example:

curl -X DELETE "https://api.enterprise.apigee.com/v1/mint/organizations/{org_name}/notification-conditions/2d08d03f-8a54-4e75-bd6f-9c9da2f53fc4"  \
  -H "Accept:application/json"  \
  -u email:password

Configuration properties for notification conditions

The following configuration properties for notification conditions are available when using the API.

Name Description Default Required?
attribute

Details of the notification condition. You can specify one or more attributes to refine the notification condition.

The value can be one or more of the following:

  • ADD_RATEPLAN
  • ADHOC_NOTIFY_DEVELOPERS
  • BILLING_DOCS_PUBLISHED
  • COMPANY_ACCEPTS_INVITATION
  • COMPANY_CANCELS_INVITATION
  • COMPANY_DECLINES_INVITATION
  • COMPANY_INVITES_DEVELOPER
  • CREATE_APPLICATION
  • CREATE_DEVELOPER
  • DATE
  • DEVELOPER_ACCEPTS_INVITATION
  • DEVELOPER_CANCELS_INVITATION
  • DEVELOPER_DECLINES_INVITATION
  • DEVELOPER_INVITES_COMPANY
  • EXPIRING_TNC
  • FeeExposure
  • FREEMIUM_USED_UP
  • NEW_PACKAGE
  • NEW_PRODUCT
  • PUBLISHED
  • RATEPLAN
  • RATEPLAN_ACCEPTED
  • RATEPLAN_ENDED
  • RATEPLAN_EXPIRED
  • RATEPLAN_RENEWED
  • RATEPLAN_REVISION
  • Transactions
  • UPDATE_DEVELOPER
  • UsageTarget (valid for configuring webhooks only)
 N/A Yes
value

Value of the attribute.

 N/A No
associatedCondition

Reference to an associated condition.

 N/A No

Configuration properties for notification actions

The following configuration properties are available for notification actions when using the API.

Name Description Default Required?
actionAttribute

Method used to identify the notification recipient. The value can be one or more of the following:

  • ORG_EMAIL. Notification recipient is identified by email address.
  • DEV_ID. Notification recipient is identified by developer ID (email address).
  • COMPANY_ADMINS. Notification is sent to all company administrators regardless of the value set. Note that company administrators are different than organization administrators.
  • WEBHOOK. Notification recipient information is sent to the webhook callback handler. See Set up notifications using webhooks.
 N/A Yes
value

Value of the action attribute.

If the actionAttribute is set to ORG_EMAIL or DEV_ID, a value of ANY sends the notification to any applicable recipient, for example, any ORG_EMAIL address or any DEV_ID.

If actionAttribute is set to WEBHOOK, set this value to the ID of the webhook.

If actionAttribute is set to COMPANY_ADMINS, this value is ignored; notification is sent to all company administrators.

 N/A Yes
templateID

ID of the notification template.

Note: This option is not valid if actionAttribute is set to WEBHOOK.

 N/A Yes
postURL

Callback handler for the webhook.

Note: This option is required if actionAttribute is set to WEBHOOK. This option is not valid if the value is set to ORG_EMAIL, DEV_ID, or COMPANY_ADMINS.

 N/A Yes

Using variables in notification templates

When you edit the message in a notification template, you can include one or more variables, using Spring Expression Language (SpEL), to represent values returned in the Transaction object.

The following table summarizes the most commonly used notification template variables.

Variable Description
${application.name}

Name of an application.
${application.products.name} Name of a product included in an application.
${BALANCE} Balance for a given quota.
${developer.legalName}

Name of a developer’s company.
${developer.name}

Name of a developer.
${EXPIRY_DATE}

Date or time at which a limit expires or gets reset.
${LONG_PERCENT} Percentage of a limit reached by current usage, with no % symbol. For example, 50
${PERCENT}

Percentage of a limit reached by current usage, with % symbole. For example, 50%.
${products.displayName} Display name defined for a product.
${QUOTA_TYPE}

Type of limit (transaction volume, spend limit, or fee exposure).
${QUOTA_UNIT}

Basic unit for a limit: currency (for a spend limit), or calls (for a transaction limit).
${QUOTA_LIMIT}

Amount of a limit.
${ratePlan.displayName} Display name defined for a rate plan.
${ratePlan.endDate} Date on which an API provider ended a rate plan.
${ratePlan.monetizationPackage.displayName}

Name of an API package.
${ratePlan.monetizationPackage.name} Name of a Monetization package.
${ratePlan.monetizationPackage.products.displayName}

Display name defined for an API product.
${ratePlan.monetizationPackage.products.name} Name of a product included in a Monetization package.
${ratePlan.startDate} Date on which a rate plan was created.
${USAGE} Current usage (total revenue or charges, or volume).
${USER}

Name of a user.

Customizing your reply-to email address

For monetization, a default noreply@apigee.com address is configured to use for email notifications that are sent to companies and developers. Contact Apigee Support to configure a custom reply name and address for your organization.