Domains' life cycles in Atomia components

Here we describe the domains’ life cycles in the components of Atomia Billing, Atomia Automation, and Atomia Domain Registration.

Overview

This is an introduction to the domains’ flows and life cycles in three different parts of the Atomia system: Atomia Billing, Atomia Automation, and Atomia Domain Registration. Here we describe what happens on major domain events such as registrations, transfers, renewals, and expirations. First we set out the general flow and then the event specific behaviour.

System overview

Below is a brief overview of the components, their purposes, and roles from a domain life cycle perspective.

Atomia Billing

Atomia Billing is a creation entry point in the domains’ life cycles in which new domains can be ordered and existing transferred in. The main purpose of Atomia Billing is to keep track of domain subscriptions and invoices. It also initiates provisioning of new subscriptions and renewals.

Atomia Automation

Atomia Automation is placed between Atomia Billing and Atomia Domain Registration. All communication between Atomia Billing and Atomia Domain Registration goes through Atomia Automation. It’s used as a mapping between subscriptions and their counterparts on provisioning resources, which in this case is Atomia Domain Registration.

The default configuration that is set regarding domains is periodic synchronization of domain data. The following properties of Atomia Automation’s DomainRegDomain service are synchronized every hour per default:

StatusLocal – Property indicating if the domain is local or not, i.e. if it exists in Atomia Domain Registration or not.
StatusExpireDate – Property indicating the expiry date of the domain.
StatusLock – Property indicating the lock status of the domain.
StatusAuthInfoGenerationMode – The mode used for GenerateAuthInfo, currently either generated or email.
StatusAuthInfoGenerationEmail – If email AuthInfoGenerationMode is used, this property contains the email that the authinfo code is emailed to on generation.
StatusTransferStatus – Transfer status if a transfer has been requested for the domain name but hasn’t succeeded yet. It is either pending or failed.
StatusTransferReason – The reason a transfer was rejected, if it was supplied by the losing registry. It’s either authinfo, inprogress, policy, status, or unknown.
StatusTransferMessage – The human readable cause of a transfer rejection, if available.
StatusRegistrationStatus – The current status of async registrations: success, failed, or pending.
StatusRegistrationExtendedDetails – Atomia Domain Registration plugin specific details for async registrations, i.e. cause of failure.
StatusOwnerChange – Property indicating the status of ongoing or last ownership changes for the domain.
StatusOwnerVerification – Property indicating the status of the owner contact data verification process.

Atomia Domain Registration

Atomia Domain Registration communicates directly with the registries/registrars that are being used. There is a plugin for each supported registry or registrar, which handles workflows based on the behavior of the registry/registrar in question. The system must be configured to adapt to the enforced rules of the registry/registrar. The life cycles can be different based on these rules.

To be able to work properly with the asynchronous operations that a registry/registrar may enforce, such as registrations or transfers, the plugins usually have at least one of the following ways to periodically check the registry/registrar for information:

Periodic task – Calls specific commands periodically on a registry/registrar that retrieves status for all domains affected by an async operation.
Message polling – Periodically polls and processes messages coming from a registry/registrar. Some of these messages contain info about async operations.
Periodic sync – Changes are reflected and the Atomia Domain Registration state aligned with the registry/registrar using an exportable CSV file from the registry/registrar.

Domain events

Domain registration

Atomia Billing initiates the domain subscription provisioning by adding a new DomainRegDomain service in Atomia Automation. In addition, Atomia Automation sends the registration request to Atomia Domain Registration, which in turn propagates the request to the registry/registrar.

The registry/registrar can have synchronous or asynchronous registrations. This means that the registry/registrar either registers domains immediately and responds that the domain was successfully registered, or adds the request to a queue for processing. If the request is queued it sends a response that the request was accepted and that the outcome will be known after X amount of time when the request has been processed.

Keep in mind

Atomia Billing always considers registrations as asynchronous. On a positive response it always sets the provisioning status of the subscription to Provisioning initiated asynchronously. On the next provisioning attempt, Atomia Billing checks the local and registered statuses (StatusLocal and StatusRegistrationStatus) and determines if the provisioning was successful, failed, or still in progress.

The registry/registrar has synchronous registrations

In this case the response can be either that the request was successful, or that it wasn’t.

If it’s successful the domain is registered and Atomia Domain Registration adds the domain in its database, marking it as local. A response is propagated back to Atomia Billing that sets the provisioning status of the subscription to Provisioning initiated asynchronously. On the next provisioning attempt, Atomia Billing sees that the domain is local in Atomia Domain Registration and sets the provisioning status of the subscription to Provisioned.
If it’s not successful, the domain registration failed and an error will be raised. The DomainRegDomain service will not be added and the subscription’s provisioning status will be set to Provisioning failed.

The registry/registrar has asynchronous registrations

In case of asynchronous registrations a response is given back stating if the request (which will be processed at a later time) has been accepted or not.

If the request is not accepted it is processed as in the above described case of unsuccessful synchronous registrations.
If the request is accepted Atomia Domain Registration saves that the domain has a pending registration, but doesn’t add it as local. Atomia Domain Registration uses a mechanism in place that periodically pulls info from the registry/registrar to check if the domain registration was completed, failed, or still pending.

Keep in mind

The Atomia Domain Registration plugin that handles this type of registry/registrar must support asynchronous registrations. This option has to be turned on in the Atomia Domain Registration configuration for each TLD that the registry/registrar uses.

Once Atomia Domain Registration gets information about the domain registration outcome it marks the domain as local if the registration was successful, or marks the asynchronous registration as failed. This is reflected in StatusRegistrationStatus in the DomainRegDomain service.

When the request has been accepted by the registry/registrar Atomia Billing marks the provisioning status of the subscription as Provisioning initiated asynchronously. Atomia Billing makes periodical checks on each provisioning attempt to see if Atomia Domain Registration has some new info about the registrations’ outcome. Eventually it sets the subscription’s provisioning status to either Provisioned or Provisioning failed.

For all successfully completed registrations Atomia Billing checks if the domain expiration date is bigger than the one initially set in the subscription. If so, Atomia Billing updates it in the subscription.

Domain transfer in

Similar like with registrations, a transfer in in the subscription provisioning is initiated by Atomia Billing. It always considers a transfer in as an async operation. The difference here is that the subscription never gets Provisioning initiated asynchronously. It is instead set to Provisioned when the registry/registrar accepts the transfer in request.

Keep in mind

Even though Atomia Billing considers transfer ins as asynchronous, the provisioning status Provisioning initiated asynchronously is never used. It’s done like this to enable the scheduled task TransferInNotificationScheduledEventHandler to take over the checking of the transfer completion.

Instead of the initiated provisioning status the information that a transfer is in progress is stored in the subscription’s custom attribute called TransferStatus. The value of this attribute is set to Pending when the registry/registrar accepts the request.

As with registrations, the Atomia Domain Registration plugin must have a way of checking the transfer status. Once the transfer completion information is known Atomia Domain Registration takes action by doing one of the following:

If the transfer is successful the domain is set as local.
If the transfer is unsuccessful the transfer is marked as failed in the DomainRegService property StatusTransferStatus.

In Atomia Billing the TransferInNotificationScheduledEventHandler task is in charge of periodically checking if a transfer has finished.

If the transfer is successful the value of the TransferStatus attribute is set to success and the expiration and renewal date of the subscription synced with the date that is available in the DomainRegService property StatusExpireDate.
If the transfer is unsuccessful the value of the TransferStatus attribute is be set to failed.

A notification mail is sent in both cases.

Domain transfer out

In order for transfer outs to be detected some sort of periodic retrieving of information must be active in the Atomia Domain Registration plugin. Most commonly message polling is used for this purpose, but periodic sync can also be used if available. Periodic sync can be used either on its own or in addition to the message polling.

Once Atomia Domain Registration detects that a transfer out has happened for a domain that domain is deleted and no longer considered local in the Atomia Domain Registration.

Atomia Billing’s scheduled task called TransferOutNotificationScheduledEventHandler collects all domains periodically which have the DomainRegDomain service but are not local, and which subscription fulfils one of the following conditions:

The subscription is of the type domain registration, has state OK, and provisioning status Provisioned.
The subscription is of the type domain transfer, has the custom attribute named TransferStatus with the value success, it has state OK, and provisioning status Provisioned.

These conditions cover successful registrations and transfer ins. All subscriptions collected like this are Terminated and the corresponding DomainRegDomain services removed. A notification is sent to all customers who have these subscriptions in their accounts.

Domain renewal

Based on the behavior of the registry/registrar regarding renewals the Atomia system can be configured to work in one of the following ways.

The registry/registrar renews domains based on requests

In this scenario, the registry/registrar renews a domain only when it receives a renewal request. Renewals originate from Atomia Billing, which creates a renewal subscription. If the provisioning conditions are met for the subscription (e.g. the renewal invoice is paid) a provisioning renewal request is sent to Atomia Domain Registration (via DomainRegDomain) and then forwarded to the registry/registrar. The expiration date is increased in all components in this process.

If a renewal is not sent, the domain expires automatically.

The registry/registrar performs auto renewals

When a registry/registrar performs automatic renewals of domains the Atomia system doesn’t send any renewal requests towards the registry/registrar. Instead it only bumps up the expiration date locally. However, it is very important with this type of workflow that the Atomia system sends expiration or deletion requests to the registry/registrar if the domain should not be renewed (e.g. if the renewal invoice is not paid).

In this scenario, the system acts in the following manner:

Atomia Billing renews subscriptions and issues invoices normally. The renewal requests are sent to Atomia Domain Registration on provisioning of renewal subscriptions, as usual. Atomia Domain Registration acts locally only upon this request with just increasing the expiration date and propagating to the registry/registrar. Plugins that handle registries/registrars with this behavior usually have a config option that only turns on local renewing. For plugins that implement EPP that config option is the following:

<code>renew_domains_locally = 1</code>

More TLD config examples can be found here: TLD Configuration Examples.

For domains that shouldn’t be renewed it is very important to send an expiration or a deletion request before the domain gets renewed automatically by the registry/registrar. This is done by turning on the auto expiring workflow in Atomia Domain Registration. If the domain reaches its expiration date this workflow sends an expiration request if it’s available, or a deletion request to the registry/registrar. At what time the system sends these requests can be tuned relatively to the expiration date of the domain. It is possible to configure requests to be sent X number of days before or after the expiration day is reached. This is done through the following config option:
```
<code>autoexpire_offset_days = 0</code>
```
The value here is the number of days relative to the expiration date of the domain.
- If the value set for autoexpire_offset_days is 0 the the expiry of the domain will be done on the expiry date.
- If this value set for autoexpire_offset_days is bigger than 0 the expiry will be done this number of days after the expiry date.
- If the value set for autoexpire_offset_days is less than 0 the expiry will be done that number of days before the expiry date.

Important!

It is important that Atomia Billing is configured to send renewals before the day set for expiration. This way the expiration date is increased and any expiration won’t be sent for the domain that should be renewed.

In order for the autoexpire_offset_days config option to work the periodic tasks must be turned on. To turn on periodic tasks in the Atomia Domain Registration configuration file (/etc/domainreg.conf) the following config option has to be added in the <tld> element:

<code>periodic_registry_plugin_task = 1</code>

And in the <connection> part of that same <tld> element the following has to be added:

<code>handles periodic</code>