Adlib - Portfolio integration development notes
Last update: 06Oct13
In September 2013 a first version of integration with Extensis Portfolio was built into the Adlib API. This leveraged the existing functionality and model of Adlib's imaging API by allowing it to communicate natively with Portfolio's API.
This was a jointly resourced project supported by Adlib, Extensis & The Fitzwilliam Museum. Development to include this functionailty in the Adlib API module was undertaken by Adlib's Christ Hagenaars.
The notes here come with the normal caveats and disclaimers: these are my notes and are not intended to, and do not, represent the views of Adlib or Extensis
Primary need: to be able to ingest and reference images in a Portfolio catalog via the Adlib windows client
- an 'image server' in Adlib terminology maps directly to a single catalog in Portfolio terminololgy (multiple image servers can be defined in the Adlib API, hence providing access to multiple Portfolio catalogs if so desired)
- an 'image server' is configured for a single storage location, and obviously, this storage location should be an 'auto-sync' folder in the named Portfolio catalog.
- having made the above two points a logical statement then becomes that the Adlib API should be the only credentials which have 'publisher' access to this Portfolio catalog.
- but putting caveats on top of caveats.. this is only a suggestion/guideline.. and makes the important point:
the primary integration is intended to impose no functional or schematic restrictions
how the integration between the two systems is made at any given site is a matter of choice.
- functionality required was create, read & delete
- update functionality (from the CRUD model - create, read, update, delete) doesn't make sense in the primary integration:
- for images: once the image is ingested, and linkage made in Adlib to that asset in Portfolio, changing the image makes little sense (delete, create makes more sense i.e. replace an image)
- for data: no data (other than that embedded in the image, and the image's filename) is sent to Portfolio, the primary purpose here is to get the asset into Portfolio and return the assetId to Adlib
(It is possible to return, and map, any number of Portfolio fields across to Adlib fields during ingest, although this is mostly only useful for retrieving the catalogId and assetId of the ingested asset. And you must remember this is 'one shot' - it only happens at the point of ingest so it should be used with care, lest you want to create a sync nightmare :-) )
- having achieved the above: using either API it's possible to do any sort of custom data interactions a client may wish to undertake, e.g.
from Portfolio: the assetID (RID) provides the primary key with which to query the Adlib 'reproductions' database and from there objects linked to that reproduction record can easily be determined, their data acessed etc through further calls.
from Adlib: the reproduction reference (FN) is the Portfolio assetId (RID) so calling the Portfolio API is straighforward.
In summary, each has direct access to the primary key to call the other.
(and, although not necessary, it's suggested that catalogId is also stored in the Adlib reproduction record during ingest - this make possible direct calls to the Portfolio API for this asset without referring to any other data stored in the Adlib)
- delete functionality - this has been implemented in the Adlib API for the Portfolio integration *only*
this makes it available as API functionality - e.g. Wwwopac.ashx?command=deletecontent&server=images&value=530 ...
there is, however, currently no matching functionality within adlwin.exe to trigger a delete call to the API (the impact of such functionality has much wider impact within adlwin.exe and the general 'Adlib stack' and will require more thinking..)
Using this integration opens a rich seam of possibilities. Although the primary integration purpose is to allow users to seamlessly ingest and view images within adlwin.exe client, bringing all the implied benefits of DAMS to the user/organisation, the extended possibilities come when considering what functionality is now available for web applications leveraging these two systems in concert.
Before expanding on that, it's worth noting that the principle of not imposing an integration model (in terms of, say field mappings) on any implementation is important. Exact integration details are always site specific.
A simple example of this is to ask the question "where shall we store the copyright and IPR information for an image?" - in the CMS, the DAMS, or both, or a bit in both? - and those with experience in the field will know that the 'definitive' answer to this is 'it depends..' :-)
If, as an organisation, you are going to bring two systems together like this (and then build services atop them) there is much thought needed to how your data models and data flows are going to work - you simply cannot have the technical integration machinery imposing anything but the most basic requirements on you (in this case the only requirement is Adlib and Portfolio must have access to a reference, FN/RID/assetID, they can share).
Hence this point is made as an assumption in the above sections.
The astute amongst you will be disagreeing with me by now.. 'but there are restrictions, there's no update or data sync'ing capability'. And you are right, or you would be right if this was a data integration module, but it's not, its a digital asset integration module - it's designed to do the 'heavy lifting' of ingesting and accessing digital assets between these two systems.
Our environment (The Fitzwilliam Museum, 20Sep2013)
Extensis Portfolio 11 Enterprise
Adlib Museum+Archive+Internet server (Win version 7.0.0 build 471, API 3.6)
preferred development/integration technologies - PHP, HTTP transport, JSON data
Adlib API tests (The Fitzwilliam Museum, 20Sep2013)
Our initial testing was successful and encompassed the following:
- installing and configuring new Adlib API module under IIS
- configuring an 'image server' in Adlib API module to point to a Portfolio catalog
- configuring a test copy of Adlib for it's reproduction reference field to be type 'image' and point to our configured Adlib API 'image server'
- browse, or drag n drop, image files into adlwin.exe client and have them successfully appear in the configured Portfolio target catalog/filesystem and for the image's references (assetId/RID & catalogId) to be written into the Adlib reproduction record
To be done (21Sep2013) at the Fitzwilliam:
- test of configuring repro reference throughout Adlib screens to retrieve assets via API/Portfolio - on development server
- PHP code development to build a test implementation of a migration tool, for our site, from our current http:// image references to DAM ingested assetId's
- note that 'bug' in adlwin.exe - where ingested asset doesn't show/refresh in the media viewer immediately - is anticipated to be corrected by Adlib 7.1
Adlib API tests - PHP examples
These rely on Adlib API 3.6.13263 or higher
Basic image ingest test through Adlib API - ingesttest.php.txt