Functionality and configuration of Getty Images / iStockPhoto Brandworkz connector

Overview

The Getty Images / iStockPhoto connector for Brandworkz is an out-of-the-box integration which enables you to automatically import pictures and videos which you purchase from Getty into a specified Brandworkz folder so they are easily available for your Brandworkz users to find and download from your central Brandworkz DAM library.

You can also configure this to import the metadata associated with each Getty image/video into matching Brandworkz tagging fields.

Note that this connector/article is for our connector to http://gettyimages.com, not to Getty Images Media Manager which is a separate DAM-like product from Getty which we also have a separate connector to.

Configuration

Pre-requisites

Contact your Getty Images account handler and:

• Obtain an API key and associated API secret. Note that only certain Getty plans include API access.
• If you aren’t sure which “Product Type” you are licencing from Getty get clarity on this as it is needed for the configuration. This could e.g. be “Premium Access” or “Editorial Subscription". Note that you may subscribe to multiple products.
• Create or nominate a specific folder in Brandworkz for the Getty images/videos to be imported into. 
  • If you subscribe to multiple products and you would like to import these into separate folders then set one up for each product.
  • You will most likely also want to import some of the metadata Getty has for each image as part of the import of each image which requires configuration as described further down. You can either discuss this with your Account Manager who can help you configure this or you can do this yourself once the connector has been enabled.
• Licence the connector via your Brandworkz Account Manager who will then enable it.
  • Inform us whether you subscribe to multiple Getty products and if you would like to enable the integration for several/all of these products as an integration needs setting up for each product.Let us know which Brandworkz folder(s) you would like to import the images/videos into.

Core config steps

Note that the below core config will already have been done by our Brandworkz Account Handler as part of the setup/pre-requisites and is only includes as you may want to review the settings.

• As a sysadmin go to Settings → Integrations →  Getty Images, and click EditNote that if you subscribe to multiple Getty products you may have multiple entries (see previous section).
  
  
• Under “Getty Credentials”:
  • Please leave the Getty API key and secret unchanged.
• Under “Basic Configuration”:
  • Integration name: typically leave this unchanged.
  • Product Type: This will already be configured by your account handler. Please leave unchanged.
  • Collections to Exclude: As the name suggests select any collections for which you don’t want to import images.
  • Username Filter: If you wish to exclude purchases/downloads from certain users enter their Getty user name here. Multiples need to be comma separated.
  • Date filter: Typically set the “From” date as the first day of your agreement if you would like to import all purchased images/videos from that date forward. Alternatively, if you don’t want to import images that you would consider to old or out-of-date then set this to a more recent date.
  • Brandworkz Folder: The Brandworkz Folder to import the images into. This will be pre-set to the folder as communicated to your Brandworkz Account Handler but can be changed if needed. Note however that if you change this you need to make sure that the new folder also subscribes to the same metadata set as the previous one, otherwise the Getty metadata will not import.
• Hit Save.
  
  

This completes the core config, but you should also complete the next/metadata configuration as per the next section.

Metadata mapping configuration

The first step will depend on whether you already have a metadata set configured which contains all of the fields which corresponds to the Getty metadata fields you would like to import for each image. For the full list of metadata fields available from Getty see the table below.

The most likely scenario is that you already have a main metaset configured for your images/videos which contains general fields like “keywords”, “copyright”, “author” etc but will not contain Getty-specific fields like “Getty ID”, “Getty URL” etc.

We do not recommend that you simply add additional Getty-specific fields to this metaset as it will clutter up the Edit screens with additional, unnecessary fields for images not coming from Getty which use this metaset. Instead we recommend that you do the following:

Create the Metaset

• Under Settings → Metadata create a new metadata set called e.g. “Getty Images” and make sure “Asset” is ticked under “Metaset type”
• Review the table below for fields available from Getty and decide which ones you would like to import.Something like “keywords” is probably a no-brainer to import as you then don’t have to do the keywording yourself. Also the “Getty URL” could be handy for your users as they will then get a link back to the image on Getty’s website where they can then explore e.g. images by the same photographer, etc.
• For each of your chosen Getty fields you would like to import, do one of the following on the main admin screen for your “Getty Images” metaset :
  • If your main image/video metaset already has a field which is appropriate for this data (e.g. “Keywords") and which is also of a compatible field type (see table below) then do not create a new field for it but instead include it via the “Add existing field” button.

    Note that if you map a multiple-choice Brandworkz field (radio, checkbox, select, multi-select) to an equivalent Getty field then on import of each image, the connector will add any missing option values automatically to the field. It will do this at the bottom of the option list.

    Note that it does not have to be named identically to the Getty equivalent as you will be setting up a mapping to the corresponding Getty field. On the review screen before you add the existing field to the new metaset you will see a “Getty Images mapping” dropdown. Select the corresponding Getty field and hit Save. 

    Note that if you use multi-language metadata then you will as an admin from time to time go in and add any missing translations to these options. Whether or not the integration will ever need to add additional options and how many will depend on whether the corresponding Getty field is a text field or is also a multiple-choice field. For example, you will see in the table below that the “Asset family” can only ever be “editorial” or “creative”, whereas “artist” can essentially be any amount of values.

    Note that for Getty fields which are likely to generate a very large amount of auto-created options such as “caption” or “Getty ID” it’s not possible to import this into a multiple-choice Brandworkz field as this wouldn’t result in a very usable config.

• If you don’t have an appropriate field in Brandworkz (e.g. “Getty URL”) then add one via the “Create new field” button:
  • Field name: In terms of the name of the field then we in general recommend naming it identically to the corresponding Getty field, although if you think you will use this new field for other purposes than Getty then this may not be the case. For instance if you intend to buy images from other photo libraries than Getty/iStock in the future then you wouldn’t create a field called e.g. “Getty URL” but instead “Stock Library URL”.
  • Field type: Please see the “Usable with these Brandworkz field types” column in the below table for your choice on this for different fields. For some Getty fields there only one compatible field type such as “Keywords” (textarea) and “Date Created” (date) but for others you have multiple options to choose from. To help you select the best field type for your usage here are some pointers:
    • For something like the “Getty ID” field which is very short in terms of the value we recommend that you choose “text” over “textarea” as it takes up less space on the edit screens.
    • For Getty’s multiple-choice fields such as “Asset Family” which can only have two values you will probably want to have a radio button field and call the field “Getty asset family” so end-users don’t get this confused with Brandworkz’s own asset types.
    • For Getty's text fields where it’s possible to map this to a Brandworkz multiple-choice field such as a Select field then this will depend on whether you also plan to use this for other non-Getty purposes and the volume of images you import. For instance if you want to import the “Allowed use: Release info” Getty field then this is only likely to auto-generate a relatively low amount of options so a Select/dropdown could be a good choice. However, if this was also to be used for non-Getty purposes and you need non-sysadmins to add values/text that isn’t one of the existing options then you probably want to create this as a Text field so you as the sys-admin don’t have to add new options all the time on behalf of end-users.
• Getty mapping: On the review screen before you add the new field to the new metaset you will see a “Getty Images mapping” dropdown. Select the corresponding Getty field and hit Save.

Apply the Metaset

Your metaset should now be ready so navigate to the folder which the connector is configured to import images and videos into. Click “Properties” in the bottom admin bar and under the “General Options” section select the new Getty-specific metaset under “Asset metaset”. Hit Submit.

Test the metadata is importing

Everything should now be ready so you are ready to head over to Getty’s website, log in with your corporate account, buy/download an image, wait a few minutes and the image should show up in your nominated Brandworkz folder!

Finally double-check that the metadata for your test images has imported correctly. Note that double-checking this for some fields isn’t straightforward as they don’t display all of an asset’s metadata on their public website. For the fields which they do display (in a grey box on the right-hand side and keywords at the very bottom) you can easily double-check it but for some of the other fields you need to check this with an API tool which Getty has where you can retrieve the “raw” metadata in json form. To check these “hidden” fields do the following:

• "Go to Getty Image's Swagger UI" and then list out the link afterwards with a hyperlink on to: https://api.gettyimages.com/swagger/index.html
• In the top-right click on "Authorize" and enter your Getty Images apiKey in the first input box and then hit the Authorize button again in the pop-up.
• Expand the “Images” section and then expand the “GET” /v3/images/{id} entry.
• Click the “Try it out” button on the right-hand side around 2/3 down through that entry.
• Enter the Getty ID for the image you would like to get info on in the “ID” field (you can see this on Getty’s site on the image detail page)
• In the “fields” multi-select, first select “detail_set” and then hold down the Shift key and also select “keywords” to get both of these selected.
• Click the massively-wide blue “Execute” button.
• In the black “Response body” field further down you should now see all of the Metadata in json form. To get a nicer view of this you can e.g. paste it into a json formatter such as JSON Formatter & Validator where you can then collapse/expand each node.

List of Getty Metadata fields which can be imported