Was this helpful?

Introduction

Monetization provides a job scheduler and a set of jobs that are pre-scheduled to run at designated times.

Toolbox

You can use the monetization API to retrieve schedules jobs, update a scheduled job, and disable or re-enable a scheduled job.

You retrieve scheduled jobs by issuing a GET request to the /organizations/{org_name}/task-scheduler resource. You can update a scheduled job by issuing a PUT request to the /organizations/{org_name}/task-scheduler/{trig_id}, where {trig_id} is the identification of the job trigger (see Triggers and job execution for further information about triggers). You can also disable or re-enable a scheduled job by issuing a PUT request to the /organizations/{org_name}/task-scheduler/{trig_id} resource.

Scheduled jobs

The table below lists the prescheduled jobs provided by monetization and the times they are scheduled to run (all times listed are in GMT). Also listed is the trigger for each job.

 

Job/Trigger Description Schedule
Monthly Developer Tax Rate

mint.scheduler.monthlydevtaxrate
@@@management

Fetches the tax rate from the tax engine for each developer, and updates the developer entity with the revised tax rate.

First day of every month at 5:45 A.M.
Renew Subscription

mint.scheduler.renewsubscriptions
@@@management

Sends a notification to developers whose rate plan renewal date is approaching.

Every day at 5 seconds past midnight.
XeFeed Updater

mint.scheduler.xefeed
@@@management

Obtains the exchange rate in U.S. dollars for each supported currency.

Every day at 1 second past midnight.
Renew Developer Rate Plan

mint.scheduler.renewydevrateplan
@@@management

Sends a notification to developers whose rate plan end date is approaching.

Every day at 2:20 A.M.
Retry Transaction Relay

mint.scheduler.retrytxrelay
@@@management

Retries failed transactions.

Every day at 4:30 A.M.
Transaction Cleanser

mint.scheduler.txcleanser
@@@management

Cleans up unwanted transactions.

Every day at 5:30 A.M.
Developer Balance Audit

mint.scheduler.{org_id}.devbalanceaudit
@@@management

Audits the balance for prepaid developers. Copies the balance to an audit table.

First day of every month at 5 seconds past midnight.
Monthly Billing Docs

mint.scheduler.{org_id}.monthlybillingdocs
@@@management

Generates billing documents.

The 11th day of every month at 1 minute after midnight.
Developer Rate Plan Counter

mint.scheduler.{org_id}.resetdeveloperrateplancounter
@@@management

Resets the rate plan counter when the reset time is reached.

Every day at 3 seconds past midnight.

In addition to the jobs listed above, there are jobs that you can enable through the monetization UI. To enable the jobs, you need to open the Notifications page in the UI and then check an appropriate checkbox on the page. See Setting up event notifications and alerts in the UI for details.

The following table lists the jobs that are enabled through the UI (all times listed are in GMT):

Job/Trigger Description How scheduled
New Package Notification

mint.scheduler.{org_id}.newpkgnotify
@@@management

Sends a notification to all developers that a new API package is available.

Check the New Package checkbox on the Notifications page. Runs once — on the day the job is enabled at 9:00 P.M.
New Ad Hoc Notification

mint.scheduler.{org_id}.adhocnotify
@@@management

Sends a notification to all developers that new API products are available in specific geographic markets.

Check the New Markets/Coverage checkbox on the Notifications page. Runs once — on the day the job is enabled at 9:00 P.M.
New Product Notification

mint.scheduler.{org_id}.newproductnotify
@@@management

Sends a notification to all developers that a new API product is available.

Check the New Package checkbox on the Notifications page. Runs once — on the day the job is enabled at 9:00 P.M.
New Rate Plan Notification

mint.scheduler.{org_id}.newrateplannotify
@@@management

Sends a notification to affected developers that a new rate plan is available. If the rate plan is a standard plan, all developers will get notified. If it is a developer category rate plan, only developers in that category will get notified. If it is a developer rate plan, only that specific developer will get notified.

Check the New Rate Plan checkbox on the Notifications page. Runs 30, 7, and 1 day before the start date of the new rate plan, at 9:00 P.M.
New Tnc

mint.scheduler.{org_id}.tncacceptancenotify
@@@management

Sends a notification to affected developers that new or revised Terms and Conditions have been published (and the developer has not yet accepted them).

Check the T&C not accepted or expired checkbox on the Notifications page. Runs 30, 7, and 1 day before the start date of the new or revised Terms and Conditions, at 9:00 P.M.

Triggers and job execution

The scheduler relies on triggers to execute jobs. A scheduled job executes when its associated trigger fires. The properties of a trigger configure the job execution, and by setting the value of these properties you can control characteristics of the job execution such as when a job executes, and how often.

The two most common types of triggers are cron triggers and simple triggers. A cron trigger has a cronExpression property that specifies a firing schedule. A simple trigger does not have a cronExpression property, but has other properties such as a repeatInterval property that specifies the time interval between firings of the trigger.

The trigger properties are as follows (all times listed are in GMT):

Property Description
cronExpression Specifies a cron expression to create a firing schedule for the trigger, such as: "At 8:00 A.M. every Monday through Friday" or "At 1:30 A.M. every last Friday of the month". See Cron expressions for further details.

Specifying this property defines the trigger as a cron trigger.

enabled

Indicates whether the trigger is enabled to fire. The value can be one of the following:

  • true. The trigger is enabled to fire.
  • false. The trigger is disabled — it will not fire.

 

id

The identification of the trigger.

jobId

The identification of the job to be executed.

startDate

Applies only to simple triggers. The date (in milliseconds counted from an epoch date) when the trigger’s schedule goes into effect.

endDate

Applies only to simple triggers. The date (in milliseconds counted from an epoch date) when the trigger’s schedule is no longer in effect.

priority

Sets the relative firing priority of the triggers if multiple triggers are scheduled to fire at the same. The lower the value, the higher the priority. For example, if two triggers are scheduled to fire at the same time., and if one trigger has a priority of 1 and the other a priority of 2, the trigger with priority 1 fires first.

This property applies only if multiple triggers have exactly the same firing time.

repeatCount

Applies only to simple triggers. Specifies how many times the trigger should be fired after the initial firing. For example, a repeatCount value of 10 will fire the trigger 11 times.

repeatInterval

Applies only to simple triggers. Specifies the time interval (in seconds) between firings of the trigger. For example, a repeatInterval value of 300 will fire the trigger every 300 seconds until the repeatCount value is reached.

triggerGroup

The type of server in which the trigger will fire. For example, if the trigger is supposed to fire in a management server, the value should be set tmanagement. If the trigger is supposed to fire in a message processing server, the value should be set to message-processor.

orgId

The identification of the organization for the trigger.

env

The environment in which the trigger is scheduled to fire, for example, dev for a development environment, or prod for production environment.

triggerName

A unique name used to identify the trigger.

Cron expressions

A cron expression is a string comprising six or seven fields separated by white space. The expression represents a set of times, normally as a schedule to execute a routine. Cron expressions that are specified in the cronExpression property of a trigger are used to schedule the firing of that trigger.

A cron expression has the following format:

Field name Mandatory Allowed values Allowed Special Characters
seconds Yes 0-59 , - * /
minutes Yes 0-59 , - * /
hours Yes 0-23 , - * /
day of month Yes 0-31 , - * ? / L W
month Yes 1-12 or JAN-DEC , - * /
day of week Yes 1-7 or SUN-SAT , - * ? / L #
year No Empty or 1970-2099 , - * /

The allowed characters and the names of months and days of the week are not case sensitive. MON is the same as mon.

The special characters are defined as follows:

Special character Description
* Used to select all values within a field. For example, * in the minute field means every minute.
? Used to specify something in one of the two fields in which the character is allowed, but not the other. For example, if you want the trigger to fire on a particular day of the month (say, the 10th), but don't care what day of the week, specify 10 in the day of month field, and ? in the day of week field.
- Used to specify ranges. For example, 10-12 in the hour field means the hours 10, 11 and 12.
, Used to specify additional values. For example, MON,WED,FRI in the day of week field means the days Monday, Wednesday, and Friday.
/ Used to specify increments. For example, 0/15 in the seconds field means the seconds 0, 15, 30, and 45. And 5/15 in the seconds field means the seconds 5, 20, 35, and 50. You can also specify / after the " character. Doing that is equivalent of having 0 before the /. Specifying 1/3 in the day of month field means fire every 3 days starting on the first day of the month.
L Has a different meaning in each of the two fields in which it is allowed. L in the day of month field means the last day of the month, that is, day 31 for January, or day 28 for February on non-leap years. In the day of week field, L means the last day of the week, that is, 7 or SAT. But if used in the day of week field after another value, it means the last xxx day of the month. For example, 6L means the last Friday of the month.

The L and W characters can be combined in the day of month field to yield LW, which translates to the last weekday of the month.

W Used to specify the weekday (Monday-Friday) nearest the given day. As an example, if you specify 15W in the day of month field, it means the nearest weekday to the 15th of the month. So if the 15th is a Saturday, the trigger will fire on Friday the 14th. If the 15th is a Sunday, the trigger will fire on Monday the 16th. If the 15th is a Tuesday, then it will fire on Tuesday the 15th. However, if you specify 1W for day of month, and the 1st is a Saturday, the trigger will fire on Monday the 3rd because it will not "jump" over the boundary of a month's days. The W character can only be specified when the day of month is a single day, not a range or list of days.

The L and W characters can be combined in the day of month field to yield LW, which translates to the last weekday of the month.

# Used to specify the nth XXX day of the month. For example, the value 6#3 in the day of week field means the third Friday of the month (day 6 = Friday and #3 = the 3rd one in the month). Other examples: 2#1 = the first Monday of the month, 4#5 = the fifth Wednesday of the month.

If you specify #5 and there is no 5th instance of the given day of the week in the month, no firing will occur that month.

Here are some examples of cron expressions (all times listed are in GMT):

Cron expression Meaning
0 0 12 * * ? Fire at 12 P.M. (noon) every day.
0 15 10 * * ? 2013 Fire at 10:15 A.M. every day during the year 2013.
0 10,44 14 ? 3 WED Fire at 2:10 P.M. and at 2:44 P.M. every Wednesday in the month of March.
0 15 10 ? * 6L 2013-2015 Fire at 10:15 A.M. on the last Friday of every month during the years 2013, 2014, and 2015.
0 15 10 ? * 6#3 Fire at 10:15 A.M. on the third Friday of every month.

Retrieving scheduled jobs

You can retrieve all the currently scheduled jobs by issuing a GET request to /organizations/{org_name}/task-scheduler. For example:

$ curl -H "Accept:application/json" -X GET \
"https://api.enterprise.apigee.com/v1/mint/organizations/{org_name}/task-scheduler" \
-u myname:mypass

The response should look something like this (only part of the response is shown):

[ {
  "cronExpression" : "0 30 5 * * ?",
  "enabled" : true,
  "id" : "mint.scheduler.txcleanser@@@management",
  "jobId" : "mint.scheduler.txcleanser@@@system",
  "priority" : -1,
  "repeatCount" : -1,
  "repeatInterval" : -1,
  "triggerGroup" : "management",
  "triggerName" : "mint.scheduler.txcleanser"
}, {
  "cronExpression" : "1 0 0 * * ?",
  "enabled" : true,
  "id" : "mint.scheduler.xefeed@@@management",
  "jobId" : "mint.scheduler.xefeed@@@system",
  "priority" : -1,
  "repeatCount" : -1,
  "repeatInterval" : -1,
  "triggerGroup" : "management",
  "triggerName" : "mint.scheduler.xefeed"
},
    ...
]    

You can also retrieve a specific scheduled job by issuing a GET request to /organizations/{org_name}/task-scheduler/{trig_id}, where {trig_id} is the identification of the job trigger. For example:

$ curl -H "Accept:application/json" -X GET \
"https://api.enterprise.apigee.com/v1/mint/organizations/{org_name}/task-scheduler/mint.scheduler.renewydevrateplan@@@management" \
-u myname:mypass

The response should look like this:

{
  "cronExpression" : "0 20 2 * * ?",
  "enabled" : true,
  "id" : "mint.scheduler.renewydevrateplan@@@management",
  "jobId" : "mint.scheduler.renewydevrateplan@@@system",
  "priority" : -1,
  "repeatCount" : -1,
  "repeatInterval" : -1,
  "triggerGroup" : "management",
  "triggerName" : "mint.scheduler.renewydevrateplan"
}

Updating scheduled jobs

You can update a scheduled job by changing the properties of its trigger. For example, you might need to change the firing schedule of the trigger.

For cron trigger jobs (that is, jobs that include a cron expression value), you can only change the values of the cronExpression and enabled properties. Other changes are ignored. For jobs that do not specify a cron expression value, you can change other properties such as startDate, repeatCount, or repeatInterval.

To update a scheduled job, issue a PUT request to /organizations/{org_name}/task-scheduler/{trig_id}, where {trig_id} is the identification of the job trigger. When you make the update, you need to specify in the request body the updated settings and the ID of the trigger. For example, the following request updates the cron expression for the New Developer Rate Plan Renewal job to run every day at 5 A.M. GMT:

$ curl -H "Content-Type: application/json" -X PUT -d \
 '{
    "cronExpression" : "0 0 5 * * ?",
    "enabled" : true,
    "id" : "mint.scheduler.renewydevrateplan@@@management",
    "jobId" : "mint.scheduler.renewydevrateplan@@@system",
    "priority" : -1,
    "repeatCount" : -1,
    "repeatInterval" : -1,
    "triggerGroup" : "management",
    "triggerName" : "mint.scheduler.renewydevrateplan"
}' \
"https://api.enterprise.apigee.com/v1/mint/organizations/{org_name}/task-scheduler/mint.scheduler.renewydevrateplan@@@management" \
-u myname:mypass

Disabling and re-enabling a scheduled job

To disable a scheduled job, set the enabled property value of its trigger to false. For example:

$ curl -H "Content-Type: application/json" -X PUT -d \
 '{
    "cronExpression" : "0 0 5 * * ?",
    "enabled" : false,
    "id" : "mint.scheduler.renewydevrateplan@@@management",
    "jobId" : "mint.scheduler.renewydevrateplan@@@system",
    "priority" : -1,
    "repeatCount" : -1,
    "repeatInterval" : -1,
    "triggerGroup" : "management",
    "triggerName" : "mint.scheduler.renewydevrateplan"
}' \
"https://api.enterprise.apigee.com/v1/mint/organizations/{org_name}/task-scheduler/mint.scheduler.renewydevrateplan@@@management" \
-u myname:mypass

To re-enable a disabled job, set the enabled property value of its trigger to true.

Get help

For help, see Apigee Customer Support.

Next steps

It's advisable to periodically re-synchronize with monetization your organization and any developers, applications, and products that you created using Edge API Services. Learn how in Synchronize Apigee Edge data with monetization.

Add new comment

Provide your email address if you wish to be contacted offline about your comment.
We will not display your email address as part of your comment.

We'd love your feedback and perspective! Please be as specific as possible.
Type the characters you see in this picture. (verify using audio)

Type the characters you see in the picture above; if you can't read them, submit the form and a new image will be generated. Not case sensitive.