.. _epp-msg-queue:

EPP Service Messages
====================

.. _epp-service-msg-types:

Message types
-------------

The server manages a separate message queue for each registrar.
Each time a change is made which was not initiated by the sponsoring registrar through EPP, a new message will be queued.

Most messages begin with an event name in square brackets in form **[AffectedObjectName:WhatHappened]**.
In the following examples, variable parts of the message are outlined in italics.

* When the Registry approves or rejects a domain name registration request (when the status of a domain name in the ``pendingCreate`` state changes);

  + When a new domain name is registered and registration request was approved:

    "**[Domain:Registered]** Registration request for domain name [*domain.lv*] approved!"

  + When a new domain name registration request was declined for any reason:

    "**[DomainForm:Rejected]** Registration request for domain name [*domain.lv*] was REJECTED. Reason: [*details, why...*]"

* When an already active domain name is added under registrar's management according to an agreement between registrar and the registrant of domain name:

  "**[Domain:RegistrarAdded]** Domain name domain.lv under management of the registrar since Y-m-d H:i:s."

* When further management by domain name has been refused by the registrar

  "**[Domain:RegistrarRefused]** Registrar management discontinued for domain name [*domain.lv*]"

* When domain name's registrant, administrative contact or technical contact has been replaced in www.nic.lv online control panel or any other way outside of EPP:

  "**[Domain:ContactReplaced]** Domain [*domain.lv*]: [*administrative contact*] role replaced with contact handle: [*amnl123456*]"

* when a domain name registrar change request (``transfer``) is initiated, approved, rejected or canceled by the other party involved or the Registry has taken an automatic action.
  Message examples are:

  + "**[Transfer:Requested]** Transfer of domain name [*domain.lv*], currently managed by [*losing-reg*], was REQUESTED by [*gaining-reg*]. [*losing-reg*] should approve or reject it until [*Y-m-d H:i:s*]."
  + "**[Transfer:Cancelled]** Transfer of domain name [*domain.lv*] from [*losing-reg*] to [*gaining-reg*] was CANCELLED by the gaining registrar."
  + "**[Transfer:Rejected]** Transfer of domain name [*domain.lv*] from [*losing-reg*] to [*gaining-reg*] was REJECTED by the losing registrar. Reason: [*anything losing side supplied*].",
  + "**[Transfer:Approved]** Transfer of domain name [*domain.lv*] from [*losing-reg*] to [*gaining-reg*] was APPROVED by the losing registrar.",
  + "**[Transfer:AutoApproved]** Transfer of domain name [*domain.lv*] from [*losing-reg*] to [*gaining-reg*] was APPROVED by the server. Reason: [current registrar did not react]."
  + "**[Transfer:Failed]** Transfer of domain name [*domain.lv*] FAILED. Reason: [*optional error message*]. Please contact us at dns@nic.lv about the problem!"

  Where:

  *gaining-reg* and *losing-reg* are EPP login names (``clID``) of registrars, which requested the transfer and which currently managers domain name and should accept or reject the transfer of management rights respectively.

  In case if any of the sides involved have no EPP account, *gaining-reg* and/or *losing-reg* may contain a registrar name which could be longer than 16 characters (as restricted by EPP XML schema).

  All poll responses concerning domain name transfers are accompanied by a ``domain:trnData`` element like:

  .. code-block:: xml

     <domain:trnData xmlns:domain="urn:ietf:params:xml:ns:domain-1.0"
                     xsi:schemaLocation="urn:ietf:params:xml:ns:domain-1.0 domain-1.0.xsd">
       <domain:name>tobemoved.lv</domain:name>
       <domain:trStatus>pending</domain:trStatus>
       <domain:reID>losing-reg</domain:reID>
       <domain:reDate>2013-06-06T12:00:00+03:00</domain:reDate>
       <domain:acID>gaining-reg</domain:acID>
       <domain:acDate>2013-06-12T12:00:00+03:00</domain:acDate>
     </domain:trnData>

On our roadmap we have also:

* a message, listing domain names that should be renewed until the next month and therefore, are included in the actual bill;
* list of renewed and discontinued domain names when the actual bill has been finalized;

This list is going to be enhanced (feedback from clients would be much appreciated).

Polling for new messages
------------------------

.. _epp-poll-request:

Client request
~~~~~~~~~~~~~~

An EPP ``<poll>`` command with ``op="req"`` attribute present requests for the next unread service message waiting for the registrar in the queue.

.. code-block:: xml

    <?xml version="1.0" encoding="UTF-8" standalone="no"?>
    <epp xmlns="urn:ietf:params:xml:ns:epp-1.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="urn:ietf:params:xml:ns:epp-1.0
         epp-1.0.xsd">
      <command>
        <poll op='req'/>
        <clTRID>Yl2SYjqDqQtJrsZBgCYV</clTRID>
      </command>
    </epp>

.. _epp-poll-response:

Server response
~~~~~~~~~~~~~~~

The server responds with a result code of ``1301`` ("Command completed successfully; ACK to dequeue") and a ``<msgQ>`` tag would be present with:

* ``id`` attribute whose value identifies the retrieved message
* ``count`` attribute containing a number of messages still in queue (including just retrieved one).

Along with ``<qDate>`` and ``<msg>`` tags, there could be a namespaced element,
specific for each message type (e.g., containing details of just approved domain name registration request).

The response would contain a result code of ``1300`` ("Command completed successfully; no messages") if the message queue is empty.

Example of a response with a very simple service message:

.. code-block:: xml

    <?xml version="1.0" encoding="UTF-8" standalone="no"?>
    <epp xmlns="urn:ietf:params:xml:ns:epp-1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="urn:ietf:params:xml:ns:epp-1.0 epp-1.0.xsd">

      <response>
        <msgQ id="76" count="15">
          <qDate>2011-07-07T10:00:00+03:00</qDate>
          <msg>Welcome, LVNIC, to NIC.LV EPP service. Good luck!</msg>
        </msgQ>
        <result code="1301">
          <msg>Command completed successfully; ack to dequeue</msg>
        </result>
        <trID>
          <clTRID>uSxDlMXTYGZdMl0Dce8G</clTRID>
          <svTRID>LVNIC-20110905-70f26d38b042eb54d758e896082db2e2-2</svTRID>
        </trID>
      </response>
    </epp>

.. _epp-poll-ack-request:

Dequeuing read messages
-----------------------

When a message has been read, the client should acknowledge it and the server would make
the next message, if any, available for the next ``<poll>`` request.

Client request
~~~~~~~~~~~~~~

The request contains a ``<poll op="ack">`` element, whose ``id`` attribute typically contains the ID of the last read message.

.. code-block:: xml

    <?xml version="1.0" encoding="UTF-8" standalone="no"?>
    <epp xmlns="urn:ietf:params:xml:ns:epp-1.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="urn:ietf:params:xml:ns:epp-1.0
         epp-1.0.xsd">
      <command>
        <poll op='ack' msgID='15'/>
        <clTRID>KUrJg6EmokFWP0eAvTxd</clTRID>
      </command>
    </epp>

Server response
~~~~~~~~~~~~~~~

On the success, server would respond with a result code of a ``1301`` and a ``<msgQ>``
element whose ``id`` attribute holds the ID of the next message, or ``1300`` -
if the last message has already been read and acknowledged.

.. code-block:: xml

    <?xml version="1.0" encoding="UTF-8" standalone="no"?>
    <epp xmlns="urn:ietf:params:xml:ns:epp-1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="urn:ietf:params:xml:ns:epp-1.0 epp-1.0.xsd">

      <response>
        <result code="1300">
          <msg>Command completed successfully; no messages</msg>
        </result>
        <trID>
          <clTRID>KUrJg6EmokFWP0eAvTxd</clTRID>
          <svTRID>LVNIC-20110905-250d4696f1ecadf870e7c6d67383acf1-3</svTRID>
        </trID>
      </response>
    </epp>