Send Docs Feedback

Set up notifications using notification templates

Introduction

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 specific developers about events such as a billing document being published.
  • 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.

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.

Toolbox

You can set up notifications using the management UI or monetization API.

Setting up event notifications using the UI

The following sections describe how to set up event notifications using the UI.

Configuring an event notification and action using the UI

To configure an event notification and action using the UI:

  1. Select Admin > Notifications to open the Notifications page.

    Admin menu with Notifications selected

  2. Select the event types for which you want to enable notifications in each of the following categories:

    When you select an event type, the area expands to enable you to define a notification for that event type.

  3. Update the Subject, Body, and To fields, for each notification that you enable, as required. For information about variables that can be specified within a notification template, see Using variables in notification templates.
  4. Deselect a checkbox if you do not want to enable notifications for an event type.
  5. Click Update notifications to save your notification settings.

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

Customizing Notify All Developers event types

Notifications for the types of events you select in the Notify All Developers section are sent to all developers. The following figure provides examples of the event notifications in this category.

The event types in the Notify All Developers section include:

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.

To customize notification templates for all developers:

  1. Select the event types for which you want to enable notifications.
  2. Update the Subject, Body, and To fields, as needed. For information about variables that can be specified within a notification template, see Using variables in notification templates.
  3. Click Update Notifications to save your notification updates.

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. If you want to disable the notifications for an event type, clear its checkbox.

Customizing Notify Affected Developers event types

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 Billing Document Published event, a notification is sent only to the developer for whom the billing documents are published. The following figure provides examples of the event notifications in this category.

Notify Affected Developers section

The event types in the Notify Affected Developers section include:

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  

To customize notification templates for affected developers:

  1. Select the event types for which you want to enable notifications.
  2. Update the Subject, Body, and To fields, as needed. For information about variables that can be specified within a notification template, see Using variables in notification templates.
  3. Click Update Notifications to save your notification updates.

The notifications are automatic and are based on the occurrence of the events. If you want to disable the notifications for an event type, clear its checkbox.

Customizing Notify API Provider event types

Notifications for the types of events you select in the Notify API Provider section are sent to the API provider you specify. The following figure provides examples of the event notifications in this category.

The event types in the Notify API Provider section include:

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

To customize notification templates for API providers:

  1. Select the event types for which you want to enable notifications.
  2. Update the Subject, Body, and To fields, as needed. For information about variables that can be specified within a notification template, see Using variables in notification templates.
  3. Click Update Notifications to save your notification updates.

The notifications are automatic and are based on the occurrence of the events. If you want to disable the notifications for an event, clear its checkbox.

Disabling an event notification condition and action using the UI

To disable a notification condition and action using the UI:
  1. Select Admin > Notifications to open the Notifications page.
  2. Clear the checkboxes for the notification event types that you want to disable in each of the categories.
  3. Click Update Notifications to save your notification updates.

Setting up notifications using the API

The following sections describe how to set up notifications using the API.

Managing notification templates using the API

The notification templates are provided by the Notifications resource. The resource path to the templates is notification/organizations/{org_name}/notification-email-templates.

The following sections describe how to view and customize the notification templates using this resource.

Viewing all notification templates using the API

You can list all the notification templates that monetization provides by issuing a GET request to that resource path. 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

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

    $ curl -H "Accept:application/json" -X GET \
    "https://api.enterprise.apigee.com/v1/mint/organizations/{org_name}/notification-email-templates/4d81ea64-d005-4010-b0a7-6ec8a5c3954b" \
    -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 limit 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"

Updating a notification template using the API

You can update a notification template by issuing a PUT request to notification/organizations/{org_name}/notification-email-templates/{template_id}. Provide the updated 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 updates the content of a new API product notification:

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

Configuring notification conditions and actions using the API

The following sections describe how to configure notification conditions and actions using the API.

Create a notification condition and action using the API

To create a notification condition and action that results in an automatic notification, issue a POST request to /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 settings 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 settings 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 -H "Content-Type:application/json" -X POST -d \
    ' {
    "notificationCondition": [
    {
    "name": "CreateProduct",
    "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" \
    -u email:password

The following request specifies that when 90% of the applicable limit is reached, send an email notification using the notification template with the ID 5320bcce-19ad-4912-aefc-701606a09ef3 (this is the DEFAULT_DEVELOPER_WARNING_LIMIT_TEMPLATE).

    $ curl -H "Content-Type:application/json" -X POST -d \
    
    '{
    "notificationCondition": [
    {
    "limit": { "id": "e2756f13-724b-4924-ab04-6aa22c60efea" },
    "value": "> 90 %"
    }
    ],
    "actions": [{
    "actionAttribute": "DEV_ID",
    "value": "ANY",
    "templateId": "5320bcce-19ad-4912-aefc-701606a09ef3"
    }]
    }' \
    "https://api.enterprise.apigee.com/v1/mint/organizations/{org_name}/notification-conditions" \
    -u email:password

The following request sends the same notification when 90% of the applicable limit is reached, but sends it only to the developer with the ID 5cTWgdUvdr6JW3xU.

    $ curl -H "Content-Type:application/json" -X POST -d \
    
    '{
    "notificationCondition": [
    {
    "limit": { "id": "e2756f13-724b-4924-ab04-6aa22c60efea" },
    "value": "> 90 %"
    }
    ],
    "actions": [{
    "actionAttribute": "DEV_ID",
    "value": "5cTWgdUvdr6JW3xU",
    "templateId": "5320bcce-19ad-4912-aefc-701606a09ef3"
    }]
    }' \
    "https://api.enterprise.apigee.com/v1/mint/organizations/{org_name}/notification-conditions" \
    -u email:password

Viewing a notification condition and action using the API

You can 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 -H "Accept:application/json" -X GET \
    "https://api.enterprise.apigee.com /v1/mint/organizations/{org_name}/notification-conditions/2d08d03f-8a54-4e75-bd6f-9c9da2f53fc4" \
    -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"
    } ]
    }

Updating a notification condition and action using the API

To update a notification condition and action, issue 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 updates that you want to make to the notification condition or action.

For example:

   $ curl -H "Content-Type:application/json" -X POST -d \
    ' {
    "notificationCondition": [
    {
      "name": "CreateProduct",
      "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

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

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

Configuration settings for notification conditions

The following configuration settings for notification conditions are exposed to the API:

Name Description Default Required?
name

Name of the notification condition.

N/A No
limit

ID of the limit.

N/A No
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
  • APP_ID
  • Balance
  • BILLING_DOCS_PUBLISHED
  • CREATE_APPLICATION
  • CREATE_DEVELOPER
  • CreditLimit
  • DATE
  • DEV_ID
  • EXPIRING_TNC
  • FeeExposure
  • FREEMIUM_USED_UP
  • LIMIT_ID
  • NEW_PACKAGE
  • NEW_PRODUCT
  • NEW_TNC
  • ORG_ID
  • PUBLISHED
  • RATEPLAN
  • RATEPLAN_ACCEPTED
  • RATEPLAN_COUNT
  • RATEPLAN_ENDED
  • RATEPLAN_EXPIRED
  • RATEPLAN_RENEWED
  • RATEPLAN_REVISION
  • SpendLimit
  • TNC_ACCEPTANCE
  • Transactions
  • UPDATE_DEVELOPER
  • VOLUME
N/A Yes
value

Value of the attribute.

N/A No
associatedCondition

Reference to an associated condition.

N/A No

Configuration settings for notification actions

The following configuration options are available for notification actions:

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.
  • 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.

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 or DEV_ID.

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.

Next steps

Using monetization you can create developer categories. This enables you to create a rate plan that applies specifically to a category. Learn how in Manage companies and developers.

 

Help or comments?