Creating an Event Handler

In this article:

Creating an Event Handler

The following operations must be performed before creating an Event Handler:

Creating an SMS gate for the SMS notification (see Managing SMS Gates).
Adding a Notification Template for the required Event (see Creating a Notification Template).

The new created Event Handler is automatically created for all downstream Resellers (see Delegating UI Templates, Notification Templates, Event Holders and Notification Categories).

To add an Event Handler:

Sign in to the Operator Control Panel.
On the Navigation Bar, go to Event Handlers (see Navigation). The list of Event Handlers is displayed (see Viewing the List of Event Handlers).
On the Toolbar, click Create. The New Event Handlers page is displayed.

Since the Event Handler is delegated to all downstream Resellers it should be unique. That means that the set of Event, Notification template type, Notification template and Query parameters must not match the corresponding set of parameters of any other Event Handler of current Reseller (Operator) and all its downstream Resellers.
In the Event list, select the event for the notification. For the full list of events, see the table.
In the Notification template type list, choose one of the following ways to send a notification message: SMS, Email or Client Panel.
In the Notification template list, select a template that will be used to create a notification message (see Creating a Notification Template).
In order to configure sending messages in the certain time:
- Clear the Add to sending queue immediately checkbox. The Add to sending queue at a specific time (hour of day) field will be available for changes.
- In the Add to sending queue at a specific time (hour of day) field, enter an hour of the day when the task for sending notification will be put in the Sending queue.
In the Query field, enter the request and condition of the handler. Use Placeholders if necessary (see Using Placeholders for Event Handlers).
The following operation with Placeholders are possible during the query creation:
- >
- <
- >=
- <=
- =
- !=
- include? (for example, order.type = "SalesOrder" and (order.plans_ids include? 2000030)) — the Event Handler works if the Plan with id =2000030 is included in the Order)
- exclude? (to exclude the certain entities (using an id, key or name) from the massive of entities. For example, in order to exclude sending messages about an order creation, which includes the Plan with the id = 2000000, use the following rule: order.plans_ids exclude? 2000000)
- and
- or. For several or after and, use additional parentheses: order.type = "RenewalOrder" and order.renewal_is_positive = true and subscription.payment_model = "prepay" and ((order.plans_ids include? 293827) or (order.plans_ids include? 293824) or (order.plans_ids include? 294340))
- % (for example, 30% of the Financial blocking threshold: account.financial_blocking_threshold % 30 )
You can use the Liquid language, which allows creating more complicated Notification. For more information see https://shopify.github.io/liquid/basics/introduction/.
```
subscription.days_left = 10 AND subscription.status = "active" 
This query is used for all active Subscriptions that expire after 10 days.
```
Click Create. The new Event Handler will be created and displayed in the List of Event Handler of the current Reseller and all its downstream Resellers (see Viewing the List of Event Handlers).

List of events

Event	Description
Account credit hold is coming	Occurs when the Account balance becomes equal to or less than the defined part (1~99%) of the Financial blocking threshold but not less than the Financial blocking threshold. Requires the proper Query. For example, the Account credit hold is coming event will occur when the Account balance becomes less than 35% of the Financial blocking threshold: `account.financial_blocking_threshold % 35 < -account.balance`
Account changed	Occurs when an Account is moved to the Administrative or Financial hold (see Moving an Account to the Administrative hold and Moving an Account to the Credit hold) or when an Account is returned from the Administrative or Financial hold (see Returning an Account from Administrative hold).
Account created	Occurs when a new Account was created (see Creating an Account).
Financial blocking threshold was changed	Occurs when the Financial blocking threshold was set for a new Account (see Creating an Account) or changed in an AccountClass (see Viewing and updating Account Class's details) or at the Account level (see Viewing and updating an Account's details). When an Account gets another Account Class but the value of the Financial blocking threshold is not changed, the event does not occur.
Account manager changed	Occurs when an Account Manager was set or changed (see Viewing and updating an Account's details).
Invoice closed	Occurs on the Billing day, when an Invoice is generated (see Managing Invoices).
The Invoice was approved	It is triggered by an API method (see Approve postpaid invoice) for a postpaid Invoice with external management (see Managing Invoices for the Postpay model by a third-party ERP system). The invoice.has_attached Placeholder is used to define whether a third-party invoice is attached to the linked Payment.
Low balance	Occurs when the Account Balance is negative.
Manager created	Occurs when a new Manager is created via the Operator Control Panel (see Adding a Manager) or API (see Create manager). Used for sending the credentials to the Manager (see Placeholders used in Notification Templates for specific Event Handlers). Requires no Query.
Manual operation	Occurs when: A Manual operation is generated (see Viewing the List of Manual Operations, Creating an Application Template based on the Manual Provisioning plugin, and Creating an Account Class). A Manual operation is approved or declined (see Managing Manual Operations).
Payment has been received	Occurs when the Payment changes its status: To Cancelled (see Approving a Payment). From Waiting for payment to Completed. From Waiting for payment to Invoice creation. From Invoice creation to Receipt sent. From Receipt sent to Completed.
Payment due date is coming	Occurs only for Subscriptions within the Postpay model. Depending on the conditions specified in the Query (see Using Placeholders for Event Handlers), it occurs the specified number of days prior to the end of the Payment expiration period (see Viewing and updating Account Class's details), or on the Payment due date, when the Payment receives the Expired status, and the related Subscriptions are blocked (see Viewing details of the Invoice for the Postpay charging model). If no conditions are specified in Query, the Event occurs on the Payment due date. To send Notifications several days prior to the Payment due date, use the following condition in Query: payment.days_left = N, where N — number of days prior to the end of Payment expiration period. To send Notifications on the Payment due date, when the Payment receives the Expired status, and the related Subscriptions are blocked, use following condition in Query: payment.days_left = 0 or leave Query empty. An Email Notification includes a PDF invoice attached. The PDF invoice is generated for a Payment linked to a postpaid Invoice in the platform. The PDF invoice is generated for Accounts with the default Payment method based on the CheckCash plugin only (see Viewing and updating Account Type's details).
Postpay payment created	Occurs on the day after the Billing day, when the platform closes a postpaid Invoice and creates the related Payment. An Email Notification includes an attached PDF invoice for the postpaid Payment. The PDF invoice is generated for Accounts with the default Payment method based on the CheckCash plugin only (see Viewing and updating Account Type's details).
Password reset request	Occurs when an email with instructions on how to reset the User's password for the Customer Control Panel is requested (see Resetting the password to the Customer Control Panel).
Manager password reset request	Occurs when an email with instructions on how to reset the Manager's password for the Operator Control Panel is requested (see Reset the password for the Operator Control Panel).
Before subscription expiration	Occurs daily for all the Subscriptions that are not linked to Renewal Orders in the Waiting for provisioning or Provisioning statuses. Requires the proper configuration of the Query field.
After subscription expiration	Occurs daily for all the Subscriptions. Requires the configuration of the Query field.
After subscription switched from trial to no-trial	Occurs when a Subscription is switched from a trial to a paid period.
Subscription changed	Occurs when: The Subscription status is changed to: Active. Deleted, excluding the case of automatic or manual deletion of a Subscription with Waiting for payment status. Stopped (excluding the case of the Administrative hold of the Account). Delivered. Graced. Stopping failed. Installation failed. Activation failed. Renewing failed. Updating failed. A Subscription is switched from a trial to a paid period. An active Subscription is renewed in the Operator Control Panel (see Manual renewing of a Subscription) or in the Customer Control Panel (see Renewing a Subscription). A Subscription is auto-renewed (see Auto-Renewing a Subscription). The amount of additional Resources is changed (see Upgrading or Downgrading a Subscription).
Verify email	Occurs when a new User completes the registration process in the Customer Control Panel by clicking the Sign Up button (see Short registration).
User invitation	Occurs when an external user is invited by the Account Administrator or Account Owner (see Inviting External Users).
Order changed	Occurs when the Order status changes to: Cancelled (in the case of manual cancelling of the Order and manual cancelling of the Payment of the Order in the Operator Control Panel and Customer Control Panel, see Operator Control Panel. Cancel a Payment of the Order, Customer Control Panel. Viewing the List of Orders). Provisioning. Completed (see Viewing the List of Orders). The receipt is not attached to a Notification.
Order created	Occurs when a new Order is created (Creating an Order) including manual and automatic renewing of a Subscription. To avoid sending to customers invoices to pay for Prolong Orders created on the Billing day for automatic paying from the Account balance, see Prolonging a Subscription), it is necessary to exclude Subscriptions with the Auto-renew point (days) = 0 from the Order created and Order changed Events. To do that, for these Events, in the Query field, use the following expression: `order.type = "ProlongOrder" AND order.renewal_is_positive = true`. As a result, the Events will occur for Subscriptions with the Auto-renew point (days) greater than 0 only.
Guaranteed payment created	Occurs when A Guaranteed Payment is created manually in the Operator Control Panel or Customer Control Panel (see Operator Control Panel. Creating a Guaranteed Payment and Customer Control Panel. Creating a Guaranteed Payment). A Guaranteed Payment is created automatically with the status Provided because of top up (see Viewing List of Guaranteed Payments).
Guaranteed payment changed	Occurs when a Guaranteed Payment is revoked manually or automatically because of balance top up (see Manually Revoking a Guaranteed Payment).
Guaranteed payment will expire	Occurs in the specified number of days before the expiration date of a Guaranteed Payment.
Days left to pay	Occurs daily for all the Subscriptions. Requires the configuration of the Query field.
Phone verification	Occurs after clicking the Receive a verification code button at the SMS Verification step during the Full Registration of an Account (see Full registration).
Billing day is coming	Occurs on a daily basis for each unique Billing day. This event is used to inform the Account Owner by email about the sum that is required at the Account balance on the Billing day in order to prevent the Subscriptions stopping. If an Account has a Subscription with the Pay as you go billing type, the notification contains the information that the required sum may change (see Pay as you go. Charges generation). The email additionally contains the link to the Top-up Balance page (see Top up balance). Managers authorized in the Operator Control Panel with the System administrator and Salesperson roles (see Managers' Roles) can also follow the link and log in to the Customer Control Panel within the same Reseller if they do not have another session in their browser with authorization in the Customer Control Panel. Subscriptions in the following statuses only (see Viewing the list of Subscriptions) are taken into account by the Event Handler: Active. Graced. Waiting for manual approve for stopping. This Event Handler requires the setting of the Query. If the Query is not set, then the Event Handler is triggered in every possible situation. For example, if an Account has three Subscriptions with any billing type with three different Billing days, the Account Owner would receive three email Notifications a day. To avoid this situation, it is strongly recommended to set the following parameters (see Using Placeholders for Event Handlers): Existence of the Subscriptions with the determined payment model. You can set this parameter using the subscription.payment_model Placeholder: If `subscription.payment_model = "postpay"`, the notification is sent for postpaid Subscriptions only. If `subscription.payment_model = "prepay"`, the notification is sent for prepaid Subscriptions only. Existence of the Subscriptions with the determined billing types. You can set this parameter using the monthly_billing Placeholder. To send Notifications only to the Owners of the Accounts that have the Subscriptions with the CSP monthly, ESET solutions for ISP (Monthly), G Suite, Pay in full and Non-refund billing types, add the following expression in the Query field: `monthly_billing = "true"` Number of days left to the Billing day that caused the Notification event occurring. You can set this parameter by using the billing_day_left Placeholder. To send Notifications a defined amount of days prior to each unique Billing day, add the following expression in the Query field: `billing_day_left = {amount of days prior to each unique Billing day}` You can additionally set the following parameters: Date of the Billing day. You can set this parameter by using the billing_day Placeholder. Total amount of Charges in the Open status that will be closed or blocked on the Billing day that caused the Notification event occurring. Only Subscriptions with the Auto-renew point (days) = 0 are included. If there are no open Charges, preliminary generation of the Charges for the next Billing period is used for calculation. You can set this parameter by using the billing_day_open_charges_amount Placeholder. IDs of the Plans of the Account active Subscriptions. You can set this parameter by using the plan_ids Placeholder. IDs of the Products of the Account active Subscriptions. You can set this parameter by using the product_ids Placeholder. Account type key. You can set this parameter by using the account.type_key Placeholder. Account class key. You can set this parameter by using the account.class_key Placeholder. Available Account balance. You can set this parameter by using the account.balance Placeholder. Financial blocking threshold. You can set this parameter by using the account.financial_blocking_threshold Placeholder. For example: billing_day = 1 and billing_day_left = 28 and account.type_key = "personal" and account.class_key = "default" and account.financial_blocking_threshold = 0 and monthly_billing = true and (plan_ids include? 1420) and (product_ids include? 498) If you want to add several conditions that should be fulfilled simultaneously, use the and operator: billing_day = 1 and billing_day_left = 28. In this case the Notification is sent 28 days prior to the Billing day only for the Subscriptions, whose Billing day is set on 1st day of each month. In total, one Notification a month is sent to each unique Account Owner. If you want to add several conditions, only one of which should be fulfilled at a time, use the or operator: billing_day = 1 or billing_day = 5. In this example, one notification for each Subscription with the unique Billing day is sent each day of the Billing period for Subscriptions, if the Billing day is set on the 1st or the 5th day of each month. In total, two Notifications a day are sent to each unique Account Owner. Use parentheses () to group and to combine conditions: (billing_day = 1 or billing_day = 2) and (billing_day_left = 3 or billing_day_left = 4). In this case: one Notification is sent 23 days prior to the Billing day for the Subscriptions, whose Billing day is set on 1st day of each month. one Notification is sent 24 days prior to the Billing day for the Subscriptions, whose Billing day is set on 1st day of each month. one Notification is sent 23 days prior to the Billing day for the Subscriptions, whose Billing day is set on 2nd day of each month. one Notification is sent 24 days prior to the Billing day for the Subscriptions, whose Billing day is set on 2nd day of each month. In total, four Notifications a month are sent to each unique Account Owner. Also, you can use math operators + and -, comparison operators > <, or to invert a Placeholder and its value (1 = billing_day). To make a table with Subscriptions that are about to expire, use the following Placeholders: next_billing_period_start_day — the first day of the next Billing period with reference to the Billing day triggered the Event. next_billing_period_end_day — the last day of the next Billing period with reference to the Billing day triggered the Event. Placeholders for the Subscription entity (see Placeholders for the Subscription entity).
Billing day has come	Occurs after running the billing process and closing Charges for every Manager in the following cases: The Manager has at least one Account with a Subscription in any status except Deleted, and the Subscription billing day is the day of running the billing process. The conditions specified in the Query field are satisfied. On the New Notification Template page, in the Additional Settings group, in the To field, it is necessary to enter the {{manager.email}} placeholder to send the Notification to the proper Manager email.
Net cost has been changed	Occurs when net cost has been changed at the current Reseller level (see Viewing the Price List). Leave the Query field empty when creating this Event Handler. Platform collects information about net cost changing once per 24 hours at night. Only the Plans, for which the net cost has been changed from 00:00:00 to 23:59:59 on the previous day, are included. For example, if information is collected at 2:00 a.m. on July, 30, only the Plans for which the net cost has been changed from 00:00:00 to 23:59:59 on July, 29, are included.
Credit limit for postpaid subscription was changed	Occurs for Accounts with postpaid Subscriptions that are not deleted in the following cases: The Subscription credit limit was changed in the Account Class (see Viewing and updating Account Class's details). On the Account details page, the Subscription credit limit was changed for the Account with Postpay as the default payment model (see Viewing and updating an Account's details). The Subscription* credit limit* was changed for the postpaid Subscription (see Viewing and updating Subscription's details). On the Account details page, the Use from the account class switch state was changed and that caused changing the Subscription credit limit for the Account (see Viewing and updating an Account's details). On the Subscription details page, the Use from the account settings switch state was changed and that caused changing the Subscription credit limit for the Subscription (see Viewing and updating Subscription's details). On the Account details page, the Account Class was changed for the Account and the Use from the account class switch is On and that caused changing the Subscription credit limit for the Account (see Viewing and updating an Account's details). The event occurs for changes via API and the Operator Control Panel.
Credit limit for postpaid subscription is approaching	Occurs when the Current debt becomes greater than the defined part (1~99%) of the Subscription credit limit but still less than the Subscription credit limit. Requires the proper Query. Occurs only once. For example, the Credit limit for postpaid subscription is approaching event will occur when the Current debt for a postpaid Subscription becomes greater than 70% of the Subscription credit limit: `subscription_postpay.credit_limit % 70 < subscription_postpay.current_debt`
Closing documents generated	It is triggered by an API method (see Send notifications on closing documents). The event is used for sending notifications to Accounts of a Reseller on Closing documents for the selected period. The Closing documents are available for downloading via the link in the notification and viewing in the Customer Control Panel (see Closing documents). The Closing documents section of the Customer Control Panel is displayed for an Account if the corresponding system settings are applied (see General system settings). Notification are sent on Closing documents in the New status only. After notifications are set, the Closing documents get the Sent status.
Joined payment created	Occurs when Payments have been joined automatically or manually to the joined Payment (see Joining Payments for the Prepay model).
Resend the order	Occurs in the specified number of days after the day when the Order was created for Orders in the Waiting for payment status and Payments linked to one Order only (the Payments are not joined, see Joining Payments for the Prepay model).
Resend the joined payment	Occurs in the specified number of days after the day when the joined Payment was created. For Payments in the Waiting for payment status only.
Request to reset the password after the user creation	Occurs when the User's password has been reset, in the case when the User was created in the Operator Control Panel (see Creating a User).
Update CSP net costs	Occurs daily for all the Subscriptions. Requires the configuration of the Query field.
Upload CSP net costs	Occurs when: A new file with prices has been downloaded (see Updating the net costs of the Resources of the Microsoft Office 365 Plans). After a new file with prices has been approved, when the file with prices changes its status from Approval required to Current or Future. The file with prices changes its status from Future to Current.
Request for creating bill was sent	Occurs if the manual operation for receipt generating was created.
Bill on balance replenishment is ready	Occurs if the receipt for balance top-up was created manually.
The accounting period was closed	Occurs when 1C sends a request to ActivePlatform to reconcile the Account balance in 1C and ActivePlatform to close the accounting period.
VSP resources changed	Occurs when a Subscription to a Plan received from Vendor Portal changes its status from Updating to Active, after the amount of Subscription Resources was changed.
VSP subscription created	Occurs when a Subscription to a Plan received from Vendor Portal changes its status from Installing to Active (see also Synchronization of Products and Plans between Vendor Portal and ActivePlatform).
Create instance	Occurs when a new CloudServer server is created (see Создание Сервера).
Reset instance password	When a password for a CloudServer server is reset. Password reset is possible only using the user interface of the CloudServer control panel.