Overview
IApiEventListenerPlugin
located in theAtomia.Billing.Core.Sdk.Plugins
namespace. All API event handlers should implement this interface and add custom logic for handling defined events.Workflow event handlers
Here is a list of defined events which can be used for adding custom logic into workflows:
EVENT NAME | DESCRIPTION |
AccountAddressUpdated | Occurs when account address is updated. |
AccountCreated | Occurs when account is created. |
AccountPreCreated | Occurs when account is about to be created. |
AccountPreTerminated | Occurs before account is terminated. |
AccountPreUpdated | Occurs when account is about to be updated. |
AccountTerminated | Occurs when account is terminated. |
AccountTerminationRequestPostCreate | Occurs whent account termination request is created. |
AccountTerminationRequestPreCreate | Occurs whent account termination request is about to be created. |
AccountUpdated | Occurs when account is updated. |
CreditInvoicePreSent | Occurs when single credit invoice is about to be sent. |
CustomerCreated | Occurs when customer is created. |
CustomerStatusChanged | Occurs when customer status is changed. |
HeartBeatEvent | Occurs when Ticker sends heart beat signal. |
InvoicePaid | Occurs when invoice is paid. |
InvoicePreCreated | Occurs before invoice is created. |
InvoicePreSent | Occurs when single invoice is about to be sent. |
InvoiceSending | Occurs before invoices are sent. |
OrderCreated | Occurs when order is created. |
OrderPreCalculate | Occurs when order totals are about to be calculated. |
OrderPreCreated | Occurs when order is about to be created. |
OrderPreProcessed | Occurs before order is processed. |
OrderProcessed | Occurs when order is processed. |
OrderProcessedPreCreateInvoice | Occurs when order is processed, and before we should create an invoice for each subscription. |
PaymentCreated | Occurs when payment is created. |
PaymentPreCreated | Occurs when payment is about to be created. |
SubscriptionChangedStatus | Occurs when Subscription is about to be updated (status changed). |
SubscriptionCreated | Occurs when Subscription is created. |
SubscriptionExtended | Occurs when subscription is extended. |
SubscriptionPreChangedStatus | Occurs when Subscription is updated (status changed). |
SubscriptionPreCreated | Occurs when Subscription is about to be created. |
SubscriptionPreTerminated | Occurs when Subscription is about to be terminated. |
SubscriptionPreUpdated | Occurs when Subscription is about to be updated. |
SubscriptionProvisionedOnPayment | Occurs when subscription is provisioned when payment is created. |
SubscriptionProvisioningStatusChanged | Occurs when Subscription provisioning status is changed. |
SubscriptionTerminated | Occurs when Subscription is terminated. |
SubscriptionUpdated | Occurs when Subscription is updated. |
UpgradeOrderCreated | Occurs when upgrade order is created. |
Complete documentation can be found in the Atomia Billing API reference.
Example event handler implementation
Scheduled task handlers
Defining tasks
The Atomia Billing API allows its users to define scheduled tasks and specific handlers for them. Scheduled tasks are represented by the type ScheduledTask
and are defined by adding a record to the scheduled_tasks
table in the Atomia Billing database. Every scheduled task has an execution period, expiration period and whether weekend and holidays should be skipped. Every scheduled task has its handler which is specified by setting Name
to the name of plug-in which is defined in the plugin
table.
public class ScheduledTask { /// <summary> /// Gets or sets the id. /// </summary> public Guid Id { get; set; } /// <summary> /// Gets or sets the last run time. /// </summary> public DateTime LastRunTime { get; set; } /// <summary> /// Gets or sets the next run time. /// </summary> public DateTime NextRunTime { get; set; } /// <summary> /// Gets or sets the expires after. /// </summary> public TimeSpan ExpiresAfter { get; set; } /// <summary> /// Gets or sets the name of the scheduled task. /// </summary> public string Name { get; set; } /// <summary> /// Gets or sets a value indicating whether task should be ran once. /// </summary> public bool RunOnce { get; set; } /// <summary> /// Gets or sets a value indicating whether holidays should be skipped. /// </summary> public bool SkipHolidays { get; set; } /// <summary> /// Gets or sets a value indicating whether weekends should be skipped. /// </summary> public bool SkipWeekend { get; set; } /// <summary> /// Gets or sets the execution period. /// </summary> public TimeSpan Period { get; set; } /// <summary> /// Gets or sets a value indicating whether this <see cref="ScheduledTask"/> is finished. /// </summary> public bool Finished { get; set; } }
Here is an example of a task definition in the scheduled_tasks
table:
COLUMN NAME | EXAMPLE |
name | NotificationHandler |
last_run_time | 2010-05-25 21:06:10.000 |
next_run_time | 2010-05-25 22:06:07.000 |
expires_after | 86400000000000 |
run_once | 0 |
period | 36000000000 |
finished | 1 |
skip_holidays | 0 |
skip_weekend | 0 |
Creating scheduled task handlers
Custom scheduled task handlers can be created by implementing the interface IScheduledEventHandler
defined in theAtomia.Billing.Core.Sdk.Plugins
namespace. The type of handler for a specific task is defined by the Name
property and it is instantiated when a task is about to be run. The scheduled task doesn’t have any input parameters for its handler because it is used only for scheduling execution. All logic for getting needed data and its manipulation should be in the handler’s HandleEvent
method implementation.
Simple notifications handler example
public class NotificationHandler : IScheduledEventHandler { /// <summary> /// Initializes a new instance of the <see cref="NotificationHandler"/> class. /// </summary> public NotificationHandler() { // Load SenderAddress value from configuration this.SenderAddress = "[email protected]"; } /// <summary> /// Gets or sets SenderAddress. /// </summary> public string SenderAddress { get; set; } /// <summary> /// Gets or sets plugin name. /// </summary> public string Name { get { return "NotificationHandler"; } set { } } /// <summary> /// Gets or sets IAtomiaBillingApi instance. /// </summary> public IAtomiaBillingApi AtomiaBillingApi { get; set; } /// <summary> /// Handles scheduled event. /// </summary> public void HandleEvent() { IList<MyNotification> notifications = this.GetNotifications(); foreach (MyNotification notification in notifications) { this.SendEmail(this.SenderAddress, notification.To, notification.Subject, notification.Body); } // Do some more work... } private void SendEmail(string senderAddress, string recipient, string subject, string body) { this.AtomiaBillingApi.SendMail(senderAddress, recipient, subject, body, new List<MailAttachment>()); } private IList<MyNotification> GetNotifications() { IList<MyNotification> notifications = new List<MyNotification>(); // Place logic for getting notifications here. // ... return notifications; } } public class MyNotification { /// <summary> /// Gets or sets recipient's email-address. /// </summary> public string To { get; set; } /// <summary> /// Gets or sets Subject. /// </summary> public string Subject { get; set; } /// <summary> /// Gets or sets Body. /// </summary> public string Body { get; set; } }