What you can and can’t do with the Portfolio API


The Portfolio API allows you to create a number of tools and workflows to assist you in your day to day use of Portfolio, but it cannot do everything. There are still some things that the API will not do, but there are ways to get around the limitations.

API tools cannot automatically trigger
This is one that I have heard a couple of different times. A person wants a workflow where they add a record to Portfolio and their API tool will activate, apply a couple of transforms on the image, and then save a copy to another location. The thing to remember is that the any tool created with the API will be an external tool. It will not reside within the server and watch for triggered events.

In this particular example, you can get around this by having all new records be assigned a specific keyword when they are added to the catalog. Set up the API tool to automatically run at routine intervals. (Task Scheduler, Crontab.) When the tool activates, it searches for any record that contains the keyword, applies the required transforms, and finally removes the keyword from the affected records.

API tools cannot customize the existing Portfolio Clients
The API is not a Macro. You cannot select some records in the client and then activate your tool to automatically apply a preset sequence of commands. Well, that is not entirely true. The big “cannot” in this section is that you cannot add your tools to the existing clients. Any tool created by the API is separate from the clients with their own username/password login. The Portfolio clients will not communicate with your tool and vice versa. Any tool you create is a client that will communicate directly with the Portfolio server.

How do you get around this? Add your selection of records to a specific gallery, than activate the client outside of Portfolio, perhaps from a command line or a PHP web interface. Create your tool to look for anything in that gallery, apply the sequence of changes, and remove the records from the gallery.

What can you do with the Portfolio API?
There is a multitude of things you can do, but here is one real world example.

Company A has a website that they use to display a selection of images to the world. The website in question imports images using a XML format dictated by a DTD specification. It also requires five JPG instances of the image in various sizes, including the original size.
Out of the box, Portfolio can only export metadata in a tab delimited text file. So Company A developed a PHP based tool that follows the following workflow. [ul]
[li]Throughout the day, users work with the records. Any records they wish to export are added to a gallery called Export.[/li]
[li]The API tool is set to activate after hours using the Windows Task Scheduler.[/li]
[li]When activated, the tool finds all the records in the Export gallery. [/li]
[li]It parses through the metadata for each record and formats it in the XML format required by the DTD file. The XML file is saved in a network location. [/li]
[li]After exporting the XML, the tool grabs a copy of the preview file, resizes it for all the required sizes and saves them to the network location using a filename specified in the metadata.[/li]
[li]It also downloads a copy of the original image. If the original is not a JPG, it will convert it to JPG before downloading it.[/li]
[li]Finally, it will write the date the file was exported in a custom field called Exported. Once complete, the records are removed from the Export gallery. [/li]
[li]Additionally, it generates a report of how many records were exported, and which records failed to export and why. The Tool also checks to see what exported records have been changed since they were last exported, in case the administrator wishes to export them again.[/li][/ul]

This is one example of what you can do with the Portfolio API. What would you like it to do?