RIPE Database docs

Acknowledgment Message ​

The acknowledgement (ack) message is always returned to the user who submitted the update to the database, however, the ack message is a unique notification because it is returned via the same method that was used to submit the update. So, for an email update, the ack message is returned to the email address that sent the update. For any other update method, the ack message is returned as an HTTP response.

The original style of the ack message was designed for an email update response. The same ack message was later used for both Syncupdates and Webupdates. Now Webupdates has a more customised web style of ack message, but Syncupdates still uses the original email ack message style. The RESTful API response is totally different and returns either XML or JSON.

Regardless of the update method, one ack message is returned for each update. The results of all operations on all objects contained in the update are included in the single ack message. For all updates, an ack message that is in the original email style is always generated by the database software. This is logged in the RIPE NCC's internal log of database changes, along with copies of all notif messages.

Email Acknowledgement Message ​

This ack message holds the overall result of the update, which either 'FAILED' or was a total 'SUCCESS'. If the update included several objects and the operation on any of those objects failed, then the overall result is 'FAILED'. If no individual operation failed, then the overall result is 'SUCCESS'. This includes any individual 'NOOP' results where no operation was carried out, as the submitted object was identical to the object already in the database. This overall result is stated at the start of the subject line of the ack email sent to the user. Any user comment on the Subject line of the submitted update follows this result.

Subject: SUCCESS: some user comment
Date:    Thu, 11 Sep 2014 10:42:15 +0200 (CEST)
From:    RIPE Database Administration local <unread@ripe.net>
To:      denis@ripe.net

The acknowledgement message content is split into sections. The first section shows from where the update was sent. This could be a copy of the update email header or the IP address for a synchronous connection. This section also includes a summary of the update results, explaining how many objects were recognised by the database software, how many operations were successful and how many failed.

An example first section of an acknowledgment message would look like this:

>  From:       Denis Walker <denis@ripe.net>
>  Subject:    some user comment
>  Date:       Thu, 11 Sep 2014 10:42:14 +0200
>  Reply-To:   Denis Walker <denis@ripe.net>
>  Message-ID: <54116066.7030403@ripe.net>

SUMMARY OF UPDATE:

Number of objects found:                   5
Number of objects processed successfully:  4
Create:         1
Modify:         2
Delete:         0
No Operation:   1
Number of objects processed with errors:   1
Create:         0
Modify:         1
Delete:         0

The next section is the "DETAILED EXPLANATION" of the acknowledgement message. This is split into three parts.

  • The first part lists all the objects where the operation failed. This will include "***Error:" messages as well as possible "***Info:" and "***Warning:" messages.
  • The next part shows all the operations that were successful. This may include additional "***Info:" and "***Warning:" messages with each operation listed.
  • The third part lists all the paragraphs from the update message that were not recognised as objects.

Each part is separated in the ACK by a line containing several '~' characters. Within each part, the objects and paragraphs are listed in the order that they were processed. This is generally the order that they appear in the update message unless 'AUTO-n' NIC Handles are referenced. The line before each object contains three hyphen characters (-) . This allows for easy parsing by script.

Below is an example of this section of the acknowledgement message:

DETAILED EXPLANATION: 

***Warning: Invalid keyword(s) found: some user comment
***Warning: All keywords were ignored

    
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The following object(s) were found to have ERRORS:      


---
Update FAILED: [person] dn1172-ripe          de nis
***Error: Syntax error in object

person:          de nis
address:         here
phone:           1
***Error: Syntax error in "1"
nic-hdl:          dn1172-ripe
mnt-by:         TEST-MNT
source:          ripe

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The following object(s) were processed SUCCESSFULLY:


---
Modify SUCCEEDED: [person] dn1172-ripe          de nis

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The following paragraph(s) do not look like objects
and were NOT PROCESSED:

This is a private email.
It is intended only for the named recipient.

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

There are many reasons why the operation may fail for an object, including syntax error, authorisation failure and failed business rules check.

~

Syncupdates Acknowledgement Message ​

There are only two differences between an ack message returned from a Syncupdate update and an ack message returned from an email update. The 'SUCCESS' or 'FAILED' result shown in the email's subject line is now shown as a code in the first line of a Syncupdates response. However, this response code does not provide the same information. An update that fails with an authorisation error will return response code 403. Any other object update failure,or success, will return response code 200. This indicates that the update was successfully processed. It does not mean that all the objects in the update message were successful operations. This must be determined from the numbers of successes and failures in the SUMMARY part of the message output.

If you use Syncupdates via the web form (see the section 'Syncupdates') there is no response code. All information has to be interpreted using the content of the ack message.

The second difference is also in the first section of the ack message. Whereas the email ack message gives details of the received email, the Syncupdates ack message gives details of the IP address sending in the update.

- From-Host: 2001:67c:2e8:13:198e:207d:6a7:47c5
- Date/Time: Fri Sep 12 11:39:37 2014

Webupdates Acknowledgement Message ​

The Webupdates ack message is very different to both the email and Syncupdates ack message. Only a single object is allowed in a Webupdates update message. If the update is successful one of the following messages is added to the top of the output:

  • Object successfully created
  • Object successfully updated!
  • PERSON object DI1432-RIPE successfully deleted

If the update fails, the errors are shown in different ways depending on the web format that you are using. If you are using the field format, a general error message may be displayed at the top of the form:

A specific error will be added, immediately after the attribute that contains the actual error:

If it is a general error that does not relate to a specific attribute, but rather to the whole update, this error message will be shown at the top of the output:

If you are using the single text area, error messages cannot be added after the attribute that contains the error. Therefore, in this case, all error messages will appear at the top of the output:

RESTful API Acknowledgement Message ​

The ack message for an API update is returned as either an XML or JSON response. The response includes the object that was submitted in the update. If there was an error, an error message section is included at the end of the response. For example an XML error response would include this section:

<errormessages>
    <errormessage severity="Error" text="Syntax error in %s">
        <attribute name="phone" value="31 20 535 4444"/>
        <args value="31 20 535 4444"/>
    </errormessage>
</errormessages>

For a creation, using the API, that returns an error message, the output is the same as for an API update. If creation is successful, the version of the object that has been added to the database is returned. This may be different to the version that was submitted in the update if it has any generated attributes.