• Introduction
• Command syntax
• Field types
  • Writable fields
  • Read-only fields
  • Group fields
  • Date fields
  • Name-servers
• Update checks
• Dry run mode
• Examples

1 Introduction

This document describes the bulk automaton that allows tag-holders 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

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.  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.

2.1 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

- STRING must be given in single quotes.
- field is a writable field listed in section 3.1 - Writable fields .
- nservers replaces all name-servers listed for a domain name by the list of nameservers in nserver_list . This is described more fully in section 3.5.3 - Replace single name-server.
- nserver replaces any occurrences of old_nserver with new_nserver . This is described more fully in section 3.5.4 - Replace all name-servers.

select_clause:
select: select_field_list

select_field_list: select_field |
    select_field_list , select_field

- select_field is either a writable or read-only field as listed in section 3.1 - Writable fields and section 3.2 - Read-only fields; or nservers to return all nameservers; or a group field as defined in section 3.3 - 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. 

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.

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 )

- field is a writable or read-only field as listed in section 3.1 - Writable fields and section 3.2 - 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 section 3.5.1 - Name-server filtering .
- date_field is either created or changed.  Date fields and DATE_STRING are described more fully in section 3.4 - Date fields .

The following fields may be updated with an update clause:
* reg-contact
* reg-trad-name
* reg-type
* reg-co-no
* reg-addr
* reg-city
* reg-county
* reg-postcode
* reg-country
* reg-fax
* reg-email
* reg-phone
* reg-opt-out
* notes
* admin-c
* a-phone
* a-fax
* a-email
* a-addr
* billing-c
* b-phone
* b-fax
* b-email
* b-addr
* first-bill
* recur-bill
* auto-bill
* next-bill
* ips-key

* key
* registrant
* changed
* created
* expiry

* reg-fields - returns registrant, reg-contact, reg-trad-name, reg-type, reg-co-no, reg-addr, reg-city, reg-county, reg-postcode,   reg-country, reg-fax, reg-email, reg-phone and reg-opt-out
* admin-fields - returns admin-c, a-addr, a-phone, a-fax and a-email
* billing-fields - returns billing-c, b-addr, b-phone, b-fax and b-email
* * - returns all fields.

The changed and created fields may be selected in a list request and also 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

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
            

If any domain names defined by the filter clause need glue records then one must be provided in new_nserver, an error is returned if not. Glue records will only be saved for domain names that require them and will be stripped out for all other domain names affected.

old_nserver is case insensitive. Trailing dots are ignored - all domain names with the name-server with or without the trailing dot are updated.

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 domain names that don't require them.

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.

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

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

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' ] 
            

filter: registrant = 'mr reg. I. strant'
update: reg-contact = 'Reginald Strant',
reg-type = 'IND',
reg-opt-out = 'y',
reg-addr = '10, The Avenue, Streatham',
reg-city = 'London',
reg-county = 'NULL',
reg-postcode = 'ST14 5TH',
reg-country = 'GB'
            

filter: created >= '20020101' and created < '20020201'
select: billing-fields
            

filter: created = ''
select: reg-fields
            

filter: registrant = 'Reginald Strant'
select: key
            

filter: registrant like 'Reginald %'
select: admin-fields
            

The following example will return the domain names where the registrant is “Reginald Strant” and the reg-postcode field is 'OX4 6LB'.

filter: registrant = 'Reginald Strant' and reg-postcode = 'OX4 6LB'
select: reg-addr, reg-city, reg-county, reg-postcode
            

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

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