The Axiell WebAPI 3.0.21344.1 and higher support the processing of posted XML payloads to extract their data to write or update Axiell database records using an adapl.
Imagine for example some media ingest software which generates metadata about the result of an ingest action, in the form of a snippet of raw XML or JSON (the latter supported from WebAPI version 3.7.1.3123), with the purpose of having some or all of the information in such a file processed in certain Axiell database records, maybe in the media records that were just created or in object records linking to those media records or maybe in some new event records.
The Axiell WebAPI is now capable of requesting such processing with the load command and the payload argument. The processing of the posted XML file itself however, must be done via a custom adapl. A <payloadConfiguration> section in the WebAPI adlibweb.xml configuration file specifies the Axiell database table name and (location of) the adapl to use, tying it all together. So a raw XML or JSON file posted with a wwwopac.ashx?command=load&payload=my_payload_type1 request would process the posted file according to the my_payload_type1 configuration, using a custom adapl for a specific database, as set in the adlibweb.xml.

For ADAPL to support this functionality, the existing indirection functionality (using the prefix exclamation mark to treat the contents of a text variable or string as if it were a field tag) can also be used to extract data from an xpath or jpath node (for XML and JSON respectively). Simply provide the xpath path to the desired elements in the XML DOM node or the jpath path, preceded by the payload keyword as identifier to the payload and a space, as a string in a text variable for example and use indirection to retrieve the contents of the node: in this context, the contents are only any textual value directly underneath the specified element, so any subnodes (their element names nor their contents) are not considered contents here. You can also count "occurrences" of a provided xpath or jpath element, using repcnt, to find out how often a certain node appears in the payload, but note that repcnt counts the total number in the file: you cannot recursively count subnodes per some higher node. An example of an adapl counting the number of xpath mavis/DigitalCarrier nodes in the file, which then retrieves the value of the xl:href attribute of the first DigitalCarrier node, then also counts the number of mavis/DigitalCarrier/objectResourceIdentifiers/ResourceIdentifier/resourceIdentifierType nodes, after which of each of those nodes its content is retrieved can be seen below. Note that the xpath text variable can have any name, it doesn't need to be xpath.

 

* payload test adapl

text xpath[0]
integer occ, maxocc

xpath = 'payload mavis/DigitalCarrier'
errorm 'Count = ' + repcnt(!xpath);
if (repcnt(!xpath) > 0) {
 xpath = 'payload mavis/DigitalCarrier/@xl:href'
 errorm 'First digital carrier href: ' + !xpath
}

xpath =  'payload mavis/DigitalCarrier/objectResourceIdentifiers/ResourceIdentifier/resourceIdentifierType';
maxocc = repcnt(!xpath);
occ = 1
while (occ <= maxocc) {
 errorm 'Occ[' + occ + ']=' + !xpath[occ]
 occ = occ + 1
}

end

So !xpath retrieves the value of the first node, while !xpath[occ] retrieves a specific occurrence of the node. An attribute of an element can be retrieved with the @ prefix: this works with or without attribute namespace.

The errorm texts produced by this payload adapl will end up in the WebAPI response, but only if the <debug>true</debug> setting has been made in the adlibweb.xml configuration file.

For JSON payloads, the adapl needs to be written a little differently. In jpath, the nodes must be separated by a dot instead of a slash. Moreover, the occurrences of jpath nodes are 0-based (as opposed to xpath occurrences and Collections field occurrences which are 1-based). So to retrieve the first occurrence of a Manufacturers node and in it the Name node, you'd write Manufaturers[0].Name. For example:

text jpath[0]
jpath = 'payload Manufacturers[0].Name'
errorm !jpath[1]

When a WebAPI load request is executed, in memory a new blank record is created for the specified database and the adapl is run for that record, so besides generating errorm messages you can use the adapl to assign data from XML nodes to field tags in the record as you would normally assign values to field tags in e.g. a before-storage adapl. To save the new record, include a write _LOCAL statement in the adapl after all relevant data has been assigned to field tags. Leave out the write _LOCAL statement if you don't want to create a new record in the currently relevant database.
You can also (regardless of what you do with the new record in memory) use the ADAPL FACS functionality to read, update or create records in FACS databases that you specify using regular FACS definitions in the adapl.

There's also an &1 execution code value for payload adapls: 31. So if not all code in your custom adapl is meant for payload processing, you can enclose the payload section by an if (&1 = 31) { ... } condition and the other code by other &1 conditions.