Schedule monetization jobs

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

Overview of scheduled jobs

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

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

Job Description Schedule (UTC) Trigger
Monthly Developer Tax Rate 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. MINT.MONTHLY_DEV_TAXRATE@@@
management-server@@@DEFAULT@@@
management-server@@@DEFAULT
Renew Subscription Applies recurring fees for active rate plans or new fees for future rate plans that start on the current day. Every day at 5 seconds past midnight MINT.RENEW_SUBSCRIPTIONS@@@
management-server@@@DEFAULT@@@
management-server@@@DEFAULT
XeFeed Updater Obtains the exchange rate in U.S. dollars for each supported currency. Every day at 1 second past midnight MINT.XEFEED@@@
management-server@@@DEFAULT@@@
management-server@@@DEFAULT
Renew Developer Rate Plan Rolls over renewal dates for a rate plan and calculates early termination fees. Every day at 2:20 A.M. MINT.RENEW_DEV_RATEPLAN@@@
management-server@@@DEFAULT@@@
management-server@@@DEFAULT
Retry Transaction Relay Note: This job has been deprecated and has no impact on monetization. Every day at 4:30 A.M. MINT.RETRY_TX_RELAY@@@
management-server@@@DEFAULT@@@
management-server@@@DEFAULT
Transaction Cleanser Note: This job has been deprecated and has no impact on monetization. Every day at 5:30 A.M. MINT.TX_CLEANSER@@@
management-server@@@DEFAULT@@@
management-server@@@DEFAULT
Developer Balance Audit Audits the developer account balance. Copies the current usage and prepaid balance/postpaid credit limit to an audit table, then deducts the current usage from the developer account and returns usage balance to zero. First day of every month at 5 seconds past midnight MINT.DEVELOPER_BALANCE_AUDIT@@@
management-server@@@DEFAULT@@@
management-server@@@DEFAULT
Monthly Billing Docs Generates billing documents.

Note: Apigee no longer supports the generation of billing documents from Apigee Edge Monetization. See Retirements.

The 11th day of every month at 1 minute after midnight MINT.MONTLY_BILLING_DOCS@@@
management-server@@@DEFAULT@@@
management-server@@@DEFAULT
Developer Rate Plan Counter Note: This job has been deprecated and has no impact on monetization. Every day at 3 seconds past midnight MINT.RESET_DEVELOPER_RATE_PLAN_COUNTER@@@
management-server@@@DEFAULT@@@
management-server@@@DEFAULT
Daily Charges Recomputes all hourly transaction totals and uses them to compute daily totals for the previous day. Every day at 1:20 A.M. MINT.CHARGE_DAILY@@@
management-server@@@DEFAULT@@@
management-server@@@DEFAULT
Hourly Charges Computes all transaction totals for each quarter of an hour. 1 minute past each quarter of an hour MINT.CHARGE_HOURLY@@@
management-server@@@DEFAULT@@@
management-server@@@DEFAULT
Refresh notification configuration Reindexes all notification conditions. Every 5 minutes MINT.REFRESH_NOTIFICATION_CONFIG@@@
management-server@@@SYSTEM@@@
management-server@@@SYSTEM
Send email notifications Sends accumulated email notifications Every hour MINT.EMAIL_NOTIFICATION@@@
management-server@@@SYSTEM@@@
management-server@@@SYSTEM
Refresh Limit Note: This job has been deprecated and has no impact on monetization. N/A (Never executes) MINT.REFRESH_LIMIT@@@
message-processor@@@SYSTEM@@@
message-processor@@@SYSTEM

In addition to the jobs listed above, there are jobs that you can enable through event notifications, as listed in the following table. For more information, see Set up notifications.

Job Description Schedule Trigger
New Package Notification Sends a notification to all developers that a new API package is available. Runs once — on the day the job is enabled at 9:00 P.M.

Note: Notifications are sent only once, regardless of whether you configure a cronExpression that results in the job being executed multiple times.

MINT.NEW_PACKAGE_NOTIFY@@@
management-server@@@DEFAULT@@@
management-server@@@DEFAULT
New Ad Hoc Notification Sends a notification to all developers that new API products are available in specific geographic markets. Runs once — on the day the job is enabled at 9:00 P.M.

Note: Notifications are sent only once, regardless of whether you configure a cronExpression that results in the job being executed multiple times.

MINT.ADHOC_NOTIFY@@@
management-server@@@DEFAULT@@@
management-server@@@DEFAULT
New Product Notification Sends a notification to all developers that a new API product is available. Runs once — on the day the job is enabled at 9:00 P.M.

Note: Notifications are sent only once, regardless of whether you configure a cronExpression that results in the job being executed multiple times.

MINT.NEW_PRODUCT_NOTIFY@@@
management-server@@@DEFAULT@@@
management-server@@@DEFAULT
New Rate Plan Notification

Sends a notification to affected developers that a new rate plan is available. All developers subscribed to the parent rate plan are notified that a new rate plan is active.

In addition:

  • 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.
Runs on the start date of the new rate plan, at 4:30 A.M. MINT.NEW_RATEPLAN_NOTIFY@@@
management-server@@@DEFAULT@@@
management-server@@@DEFAULT
New Tnc Sends a notification to affected developers that new or revised Terms and Conditions have been published (and the developer has not yet accepted them). Runs 30, 7, and 1 day before the start date of the new or revised Terms and Conditions, at 9:00 P.M. MINT.TNC_ACCEPTANCE_NOTIFY@@@
management-server@@@DEFAULT@@@
management-server@@@DEFAULT
Expiring rate plan Sends a notification to affected developers to provide advance warning that a rate plan is going to expire. Runs 30, 7, and 1 day before the expiration of the rate plan, at 9:00 P.M. MINT.EXPIRING_RATE_PLAN_NOTIFY@@@
management-server@@@DEFAULT@@@
management-server@@@DEFAULT

Managing the monetization job schedule using the API

The following sections describe how to manage the monetization job schedule using the API:

For more information about the APIs described in this section, see Scheduled jobs in the API reference.

Configuring triggers

The scheduler relies on triggers to execute jobs. A scheduled job executes when its associated trigger executes. 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 an execution schedule. A simple trigger does not have a cronExpression property; you specify the startTime to indicate when the trigger goes into effect, and optionally the endTime.

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

Property Description
cronExpression Cron expression to create an execution 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 Building cron expressions for further details.

Specifying this property defines the trigger as a cron trigger.

Note: If both cronExpression and startTime/endTime are specified, cronExpression takes precedence.

enabled Flag that indicates whether the trigger is enabled to execute. The value can be one of the following:
  • true. The trigger is enabled to execute.
  • false. The trigger is disabled — it will not execute.
endTime Time in epoch format when the trigger's schedule is no longer in effect.
group Type of server in which the trigger will execute. For example, if the trigger is supposed to execute in a management server, the value should be set to management-server. If the trigger is supposed to execute in a message processing server, the value should be set to message-processor.
id Identification of the trigger.
jobId Identification of the job to be executed.
name Unique name used to identify the trigger.
priority Relative execution priority of the triggers if multiple triggers are scheduled to execute at the same. The lower the value, the higher the priority. For example, if two triggers are scheduled to execute 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 executes first.

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

startTime Applies only to simple triggers.

Time in epoch format when the trigger's schedule goes into effect.

Note: If both cronExpression and startTime/endTime are specified, cronExpression takes precedence.

suiteId Flag that specifies whether the notification part of the system-level or default-level suite of notifications. Valid values are DEFAULT or SYSTEM, or you can specify your own unique suite name.
triggerDataMap Lock key, custom_lock_key, that prevents multiple servers from executing the same job at the same time.

Building 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 execution of that trigger.

A cron expression has the following format: s m h dm m dw y

Where:

Field Description Required Allowed values Allowed Special Characters
s Seconds Yes 0-59 , - * /
m Minutes Yes 0-59 , - * /
h Hours Yes 0-23 , - * /
dm Day of month Yes 0-31 , - * ? / L W
m Month Yes 1-12 or JAN-DEC , - * /
dw Day of week Yes 1-7 or SUN-SAT , - * ? / L #
y Year No Empty or 1970-2099 , - * /

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 execute 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 execute 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.
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 execute on Friday the 14th. If the 15th is a Sunday, the trigger will execute on Monday the 16th. If the 15th is a Tuesday, then it will execute on Tuesday the 15th. However, if you specify 1W for day of month, and the 1st is a Saturday, the trigger will execute 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.
# 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.

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

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

Viewing scheduled jobs using the API

You can view all the currently scheduled jobs by issuing a GET request to /triggers?orgid={org_name}.

For example:

$ curl -H "Accept:application/json" -X GET \ "http://localhost:8080/v1/mint/triggers?orgid={org_name}" \ -u email:password

The following provides an example of the response:

[ {
  "createdDate" : 1457924378176,
  "cronExpression" : "3 0 0 * * ?",
  "enabled" : true,
  "group" : "management-server",
  "id" : "MINT.RESET_DEVELOPER_RATE_PLAN_COUNTER@@@management-server@@@DEFAULT@@@management-server@@@DEFAULT",
  "jobId" : "MINT.RESET_DEVELOPER_RATE_PLAN_COUNTER@@@management-server",
  "name" : "MINT.RESET_DEVELOPER_RATE_PLAN_COUNTER@@@management-server@@@DEFAULT",
  "priority" : "1",
  "suiteId" : "DEFAULT",
  "triggerDataMap" : {
    "custom_lock_key" : "mint.scheduler.__ORG_ID__.resetdeveloperrateplancounter@@@management"
  },
  "updatedDate" : 1457924378176
}, {
  "createdDate" : 1457924378014,
  "cronExpression" : "",
  "enabled" : true,
  "group" : "management-server",
  "id" : "MINT.ADHOC_NOTIFY@@@management-server@@@DEFAULT@@@management-server@@@DEFAULT",
  "jobId" : "MINT.ADHOC_NOTIFY@@@management-server",
  "name" : "MINT.ADHOC_NOTIFY@@@management-server@@@DEFAULT",
  "priority" : "4",
  "startTime" : "1372916749000",
  "suiteId" : "DEFAULT",
  "triggerDataMap" : {
    "custom_lock_key" : "mint.scheduler.__ORG_ID__.adhocnotify@@@management"
  },
  "updatedDate" : 1457924378014
}, {
  "createdDate" : 1457924377877,
  "cronExpression" : "0 20 1 * * ?",
  "enabled" : true,
  "group" : "management-server",
  "id" : "MINT.CHARGE_DAILY@@@management-server@@@DEFAULT@@@management-server@@@DEFAULT",
  "jobId" : "MINT.CHARGE_DAILY@@@management-server",
  "name" : "MINT.CHARGE_DAILY@@@management-server@@@DEFAULT",
  "priority" : "1",
  "suiteId" : "DEFAULT",
  "triggerDataMap" : {
    "custom_lock_key" : "mint.scheduler.__ORG_ID__.chargedaily@@@management"
  },
  "updatedDate" : 1457924377877
},
...
]

You can also view a specific scheduled job by issuing a GET request to /triggers/{trig_id}, where {trig_id} is the identification of the job trigger, as described in Overview of scheduled jobs. For example:

$ curl -X GET \ "http://localhost:8080/v1/mint/triggers/MINT.RENEW_DEV_RATEPLAN@@@management-server@@@DEFAULT@@@management-server@@@DEFAULT" \ -u email:password

The following provides an example of the response:

{
    "createdDate" : 1457924377925,
    "cronExpression" : "0 20 2 * * ?",
    "enabled" : true,
    "group" : "management-server",
    "id" : "MINT.RENEW_DEV_RATEPLAN@@@management-server@@@DEFAULT@@@management-server@@@DEFAULT",
    "jobId" : "MINT.RENEW_DEV_RATEPLAN@@@management-server",
    "name" : "MINT.RENEW_DEV_RATEPLAN@@@management-server@@@DEFAULT",
    "priority" : "1",
    "suiteId" : "DEFAULT",
    "triggerDataMap" : {
        "custom_lock_key" : "mint.scheduler.__ORG_ID__.renewydevrateplan@@@management"
    },
    "updatedDate" : 1457924377925
}

Updating scheduled jobs using the API

You can update a scheduled job by changing the properties of its trigger. For example, you might need to change the execution 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 startTime or priority.

To update a scheduled job, issue a PUT request to /triggers/{trig_id}, where {trig_id} is the identification of the job trigger, as described in Overview of scheduled jobs. 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. UTC:

$ curl -H "Content-Type: application/json" -X PUT -d \
 '{
    "cronExpression" : "0 0 5 * * ?",
    "enabled" : true,
    "group" : "management-server", 
    "id" : "MINT.RENEW_DEV_RATEPLAN@@@management-server@@@DEFAULT@@@management-server@@@DEFAULT",
    "jobId" : "MINT.RENEW_DEV_RATEPLAN@@@management-server",
    "name" : "MINT.RENEW_DEV_RATEPLAN@@@management-server@@@DEFAULT",
    "priority" : "1",
    "suiteId" : "DEFAULT",
    "triggerDataMap" : {
        "custom_lock_key" : "mint.scheduler.__ORG_ID__.renewydevrateplan@@@management"
    },
}' \
https://localhost:8080/v1/mint/triggers/MINT.RENEW_DEV_RATEPLAN@@@management-server@@@DEFAULT@@@management-server@@@DEFAULT
\
-u email:password

Disabling and re-enabling a scheduled job using the API

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,
    "group" : "management-server",
    "id" : "MINT.RENEW_DEV_RATEPLAN@@@management-server@@@DEFAULT@@@management-server@@@DEFAULT",
    "jobId" : "MINT.RENEW_DEV_RATEPLAN@@@management-server",
    "name" : "MINT.RENEW_DEV_RATEPLAN@@@management-server@@@DEFAULT",
    "priority" : "1",
    "suiteId" : "DEFAULT",
    "triggerDataMap" : {
        "custom_lock_key" : "mint.scheduler.__ORG_ID__.renewydevrateplan@@@management"
    },
}' \
https://localhost:8080/v1/mint/triggers/MINT.RENEW_DEV_RATEPLAN@@@management-server@@@DEFAULT@@@management-server@@@DEFAULT
\
-u email:password

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

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.