Introduction

This document describes the bulk automaton that allows registrars to list and modify many domain names without having to send in a single operation for each one. To do this send a message to the Automaton using the following instructions

• Send to the address auto-bulk@nic.uk.
• Use the subject line TAG Bulk (replace TAG with your tag name in capitals)
• Specify the instructions using the command syntax below
• Make sure the e-mail is PGP-signed with a registered PGP key.

A dry run facility is also available. This is described in Dry run mode.

Command syntax

The bulk-automaton accepts PGP-signed emails which contain a request for a single bulk-modification or list. A bulk modification request contains a single update clause preceeded by an optional filter clause.  The filter clause can be thought of as representing a set of domain names. If there is no filter clause, all domain names on the signing tag will be updated. 

A bulk list request will contain a single select clause preceeded by an optional filter clause. Again, if there is no filter clause, all domain names on the signing tag will be returned. For both bulk modification and lists, the purpose of the filter clause is to specify the set of domain names which will be modified or listed.

Examples of bulk modification and list requests are given in Examples .

Update clause

An update clause lists the fields that will be updated and the new values for them. Valid update clauses are defined by the following:

 update_clause:
     update: update_field_list
 update_field_list: field = STRING |
     nservers = [ nserver_list ] |
     nserver old_nserver = new_nserver |
     update_field_list

Notes:

• STRING must be given in single quotes.
• field is a writable field listed in Writable fields .
• nserver finds all nameservers associated with the domain names represented by the filter clause that match old_nserver and overwrites them with new_nserver (which may include glue records). This will affect other domain names not included in the filter clause that refer to the nameservers modified. This is described more fully in Replace single name-server.
• nservers creates new nameserver objects from the list in nserver_list and then replaces the nameserver list with these for all the domain names in the filter clause. This is described more fully in Replace all name-servers.

Select clause

A select clause lists fields to be returned to the registrar. Valid select clauses are defined by the following:

select_clause:
select: select_field_list
select_field_list: select_field |
    select_field_list , select_field

Notes

• select_field is either a writable or read-only field as listed in Writable fields and  Read-only fields; or nservers to return all nameservers; or a group field as defined in Group fields .

All lists will be returned in a similar format to the standard automaton list requests - as a text email, one line per domain name with the fields split by the '|' character. All new line characters appearing in returned fields such as addresses will be replaced by a '^' character.

Filter clause

A filter clause defines the domain names for a select or update clause to act upon. If there is no filter clause, all registered domain names on the signing pgp key are acted upon. Only domain names that are on the signing pgp-key are acted upon, it is not possible to modify or list domain names on a different pgp-key.

If a filter clause is used then it must precede a select clause or update clause. Valid filter clauses are defined by the following:

filter_clause:
filter: predicate
predicate: field =STRING |
  field  like STRING |
  date_field <= DATE_STRING |
  date_field >= DATE_STRING |
  date_field < DATE_STRING |
  date_field > DATE_STRING |
  STRING in nservers |
  predicate or predicate |
  predicate and predicate |
  not predicate |
  ( predicate )

Notes:

• The usual precedence rules apply.
• field is a writable or read-only field as listed in Writable fields and Read-only fields .
• All filter clauses are case-insensitive.
• like allows for wild-card filtering using the character '%'.
• in nservers will check all nameservers held to find if the given string appears. This is described in Name-server filtering .
• date_field is either created or changed.  Date fields and DATE_STRING are described more fully in Date fields .
• All filter clauses are case-insensitive.

Field types

Writable fields

The following fields may be updated with an update clause:

• account-id 
• notes
• first-bill
• recur-bill
• auto-bill
• next-bill
• registrar-tag

account-id may be used to move the group of domain names to that account. This will only succeed if the account names for all the domain names are the same as for that account.

Read-only fields

The following fields, along with those listed in Writable Fields, may be included in a filter or select clause:

• key
• created
• expiry
• account-name
• trad-name
• opt-out
• type
• co-no

The following field can be used in a filter clause only:

• email

It can be used to find accounts with a particular email address on them. Accounts will be found irrespective of which particular contact the email address appears on.

The following fields may be included in a select clause:

• changed
• a1-id
• a1-name
• a1-phone
• a1-fax
• a1-email
• a2-id
• a2-name
• a2-phone
• a2-fax
• a2-email
• a3-id
• a3-name
• a3-phone
• a3-fax
• a3-email
• b1-id
• b1-name
• b1-phone
• b1-fax
• b1-email
• b2-id
• b2-name
• b2-phone
• b2-fax
• b2-email
• b3-id
• b3-name
• b3-phone
• b3-fax
• b3-email
• addr
• locality
• city
• county
• postcode
• country
• b-addr
• b-locality
• b-city
• b-county
• b-postcode
• b-country

Date fields

The created, changed and expiry fields may be selected in a list request and created and expiry may also be included in a filter request. The following comparisons are available for date filter clauses:

date-field> DATE_STRING
date-field < DATE_STRING
date-field >= DATE_STRING
date-field <= DATE_STRING

DATE_STRING must be of the format 'yyyymmdd'.

Name-servers

Name server can be specified by name (e.g. 'ns0.nserver.co.uk') or by IP address (e.g. '101.101.101.101').

Filtering

Domain names on the signing pgp-key can be filtered by nameserver by using the string in nservers clause. For example

filter: 'ns0.nserver.co.uk' in nservers

All name servers which contain the string 'ns0.nserver.co.uk' will be included in the set to be acted upon. This will include any domain names with the given name server and a glue record. If a glue record is provided e.g:

filter: 'ns0.nserver.co.uk 101.101.101.101' in nservers            

only domain names with the name server and glue record will be included in the set.

To find domain names with no nameservers, use:

filter: nservers = 'NULL' 

Selecting

By including nservers in a select clause, all name-servers will be returned for the requested domain names.

Replace single name-server

By including nserver old_nserver = new_nserver in the update clause, all nameservers associated with any of the domain names defined by the filter clause that match old_nserver will be modified directly to match new_nserver.
Any glue records provided in are stripped out and the filter is based on the name only. Domain names not included in the filter clause which use the nameservers modified will also be affected by this.

If any of the nameservers affected need glue records then one must be provided in , an error is returned if not. Glue records will only be saved for nameservers that require them and will be stripped out otherwise.
old_nserver is case insensitive. Trailing dots are ignored - all domain names with the name-server with or without the trailing dot are updated.

new_nserver is not case insensitive. DNS will be updated to the exact contents of new_nserver - with or without capitals.

Replace all name-servers

By including nservers = [ nserver_list ] in the update clause, new nameserver objects will be created for the nameservers in the list and the domain names in the filter clause will have their nameserver lists updated to point at this list.

If any of the domain names specified by the filter clause need glue records for the listed name-servers, the name server must include the glue record. Glue records are stripped out for nameservers that don't require them.

Update Checks

Checks are made on the data provided in an update clause in the same way as for the main automaton.

Dry run mode

If a line containing only dry-run: is contained in a modify request, the update will not be made. Two lists will be returned to the requestor, each containing the affected domain names and fields, showing the state of the domain names before and after the modification.

Examples

Example 1 - Find all the domain names on an account

This returns a list of all the domain names on the 10002 account

filter: account-id = '10002'
select: key

Example 2 - Replacing a name server

The following replaces ns0.nserver.co.uk with ns0.new-nserver.co.uk for all
domain names on the signing pgp-key.

update: nserver 'ns0.nserver.co.uk' = 'ns0.new-nserver.co.uk 120.120.120.120'

This effectively modifies all nameserver objects on the signing pgp-key that match ns0.nserver.co.uk. Glue records are written only for nameserver that the domain name new-nserver.co.uk refers to.

Example 3 - Overwriting a name server

The following over-writes all the name-servers for all domain names on the signing pgp-key.

update: nservers = [ 'ns0.nserver.co.uk 121.121.121.121',
                     'ns1.nserver.co.uk 101.101.101.101' ]            

The effect of this is to create two new nameserver objects and to replace the nameserver list for all domain names on the signing pgp-key with these two nameservers.

Example 4 - Name Server filtered list

The following example will replace the name servers of domain names where the name server ns1.nominet.org.uk is present.

filter: 'ns1.nominet.org.uk' in nservers 
update: nservers = [ 'ns0.nserver.co.uk 121.121.121.121',
                    'ns1.nserver.co.uk 101.101.101.101' ] 

Example 5 - Update fields in filtered list

The following updates the billing fields for all domain names on the account '10001'.

filter: account = '10001'
update: auto-bill = '1',
recur-bill = 'NULL'

Setting recur-bill to 'NULL' strips out the recur-bill field in line with the main automaton.

Example 6 - Date filtered list 1

To list created and expiry dates for all domain names registered in January 2001.

filter: created >= '20020101' and created < '20020201'
select: created, expiry

Example 7 – Filtered out domain names

To update the auto-bill field to the value of '1' for all the domain names on your tag apart from 'automaton-example.co.uk and 'automaton-example.org.uk' Note that that this example contains the "dry-run:" mode, which means that the update will not be made. See more information on the dry run mode.

dry-run:
filter: not (key = 'automaton-example.co.uk' or key = 'automaton-example.org.uk')
update: auto-bill = '1'

Example 8 - Merging accounts

To move a group of domain names to a single account, modify the account-id field.

filter: account-name = 'Example Registrant'
update: account-id = '10001'

This will move all domain names where the account-name is 'Example Registrant' to the account 10001, provided the account name for 10001 is 'Example Registrant' and 10001 is on your tag.

Example 9 - Releasing an account

To release all the domain names on an account to a new tag, modify the registrar-tag field:

filter: account-id = '1001'
update: registrar-tag = 'TAGB'

To release all the domains on all accounts where the account name matches 'Example Registrant':

filter: account-name = 'Example Registrant'
update: registrar-tag = 'TAGB'

 

Example 10 - To merge all domain names onto two name server objects

The following request will merge all domain names on a tag onto two nameserver objects.

update: nservers = [ 'ns1.nameserver.co.uk', 'ns2.nameserver.co.uk' ]