Axiell WebAPI home page > WebAPI > insertrecord

WebAPI Browser

insertrecord

Url request
Adlib.Data
jQuery

Syntax

command=insertrecord&<parameter>=<value>&...

database (String) database on which to perform the insertrecord function. The name of this database must have been specified in the adlibweb.xml file.
data (String) the record(s) to write; data constitutes the data in the form of adlibXML which must be written back to the database. Use the POST method in software of your own making to send record data to the web server.
Include the writeAllowed setting in adlibweb.xml, otherwise records can’t be written to the database.
The user who wants to write a record in the database, must have write access in the Axiell Collections application (which access rights can be set up via Axiell Designer). Further make sure that the write process runs under the right identity (which is determined by the setup of the WebAPI application in IIS).
All fields that are referenced in any way for writing data really must have been defined in the data dictionary of the databases used by the Axiell application; this includes link reference tags. By default, you can't write to fields which are not specified in the data dictionary, because of security reasons. The data dictionary consists of all the database, dataset, field and index specifications collected in the .inf database configuration files of an Axiell application. These .inf files can be viewed and edited using Axiell Designer.
In the XML data, assign priref 0: the new record will then automatically get a number just one higher than the highest existing record in the database. If the database is subdivided into datasets, and the record must be created in one of these datasets, then specify this dataset in the databaseConfiguration section of the relevant database in adlibweb.xml, like so for example: collect>extern.
If you write data in which a validated field contains a non-preferred term, then this value will automatically be replaced by the correct preferred term. The returned record XML will contain the preferred term. If there is more than one preferred term (when there are homonyms) then an exception is thrown and the record is not updated.
When you POST grouped XML data to the wwwopac.ashx while one or more of the application fields are multilingual, then be sure to structure your XML accordingly. From wwwopac.ashx version 3.6.13277, the required source XML format is identical to the search result XML format and it is now mandatory for multilingual fields to use the lang attribute to specify the data language of the field to write to; previously, specifying the language was not a requirement. The WebAPI will check the data dictionary (.inf file) of the relevant database to find out if fields are multilingual or not. The XML format for a new record containing just a multilingual title field (in field group Title) must now be structured similarly to the following:
<adlibXML><recordList><record><priref>0</priref><Title><title><value lang=’en-GB’>Test title English</value><value lang=’nl-NL’>Test titel Dutch</value></title><Title></record></recordList></adlibXML>
while for a monolingual title field you would structure the XML like:
<adlibXML><recordList><record><priref>0</priref><Title><title>Test title</title><Title></record></recordList></adlibXML>
Note that before version 3.6.13277, the source XML format for multilingual data deviated from the returned XML in the sense that in the source XML the <title> node had to be repeated for each language you wanted to write, like so:
<adlibXML><recordList><record><priref>0</priref><Title><title><value lang=’en-GB’>Test title English</value></title><title><value lang=’nl-NL’>Test titel Dutch</value></title><Title></record></recordList></adlibXML>
xmltype (String) [optional] type of xml to be written ('grouped' or 'unstructured')
output (String) [optional] output format to be returned. Values for output can be either json or xml (xml is the default, so you don't need to specify that explicitly). However, the output format produced by jQuery applications is always JSON, so you don't need to specify the output type there either.
Read more about JSON output here.
callback (String) [optional] returns JSON output wrapped in brackets with your callback function name, for AJAX requests: <callback function name>( <JSON output> ); You don't need to specify output=json, because the output format is JSON by default.
language (String) [optional] the default data language for monolingual data inserted into a multilingua field. From WebAPI version 3.2.1.1385, a default data language parameter is available for the insertrecord and updaterecord commands (as well as for the deprecated writerecord command), to allow the client or user to POST monolingual record XML while specifying the default data language for any multilingual target fields once through the URL. This has the advantage that a lang attribute no longer needs to be added to fields in monolingual XML source data that is targeted for a multilingual field. So the client no longer needs to be to be aware of any multilingual fields in the target database and may POST its monolingual source data without lang attributes: the WebAPI will use the new language parameter (with an ISO 639-1-ISO 3166-1 language code like nl-NL or en-GB for example) to determine which lang attribute must be added automatically to any monolingual value when it is written to a multilingual field. Of course, if you're sure there exists no multilingual target fields, then you don't need to use this parameter.
(If you were to leave out the lang attribute in the XML body AND you do not provide the language parameter while writing the data to multilingual fields, an error will be reported as before in the XML diagnostic section.)

Description

Writing a new record resolves links and it manages reverse links, but internal links are not yet dealt with. From version 3.6.1173.0, non-preferred terms in validated fields are automatically replaced by their preferred terms.
Further, linked fields in your database may have write-back fields defined for them, which means that in a catalogue record the user can edit or enter information in merged-in fields belonging to a linked record, to be stored with the linked record when the catalogue record is saved. From wwwopac.ashx version 3.7.13301.1, data you write to such merged-in fields will be written back to the relevant linked record if for the linked field the appropriate write-back fields have been specified. In previous versions this data could not be written to the linked record.

Examples

Write a new record with just a title in database 'externalobjects' show

// Create a connection to the wwwopac.ashx
conn = new AdlibConnection(url);

// Create a new adlib record
record = new AdlibRecord(conn, "externalobjects");

// Set the priref field
record["priref"] = "0";

// Set the title field
record["title"] = "A new title"

// Insert the record in the database
record.Insert();

select text

Delete the record you created in the previous example show

// Create a connection to the wwwopac.ashx
conn = new AdlibConnection(url);

// Create a new adlib record
record = new AdlibRecord(conn, "externalobjects");
record.Search(10000001);
if (record != null)
{
  // Delete the record
  record.Delete();
}

select text

Description

- no jQuery-specific description available yet; see the Adlib.Data tab for all information -

Examples

Write a new record with just a title in database 'externalobjects' show

var url = "http://test2.adlibsoft.com/api/wwwopac.ashx";

var xmldata =   '<adlibXML><recordList><record>' +
	    '<priref>0</priref><title>test title</title>' +
	    '</record></recordList></adlibXML>';

$().adlibdata(url,
{
  //arguments
  database: "externalobjects",
  command: "insertrecord",
  data: xmldata,
  xmltype: "grouped"
},
function (adlibJSON) {
  alert(adlibJSON.diagnostic.hits);
});

select text

Delete the record you created in the previous example show

var url = "http://test2.adlibsoft.com/api/wwwopac.ashx";

$().adlibdata(url,
{
  //arguments
  database: "externalobjects",
  command: "deleterecord",
  priref: 10000001
},
function (adlibJSON) {
  alert(adlibJSON.diagnostic.hits);
});

select text