Atomia Billing System developer guide

Atomia billing event handlers

33 views 0

Overview

 The Atomia Billing API defines a set of events that can be used to customize predefined workflows or add executions of scheduled tasks. Writing handlers for what these events should provide means inserting custom business logic into workflows. The API provides pre- and post- events for all essential workflows. The base interface for API event handlers is 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;
  }
}

Was this helpful?