Setting Up media import from an image bank

As from 2022.6.0, it will be possible to import bought media licenses from an image bank, directly to the DAM. This is allowed by the plugin : PACKAGED_ImgBank.

In order to use it, first we have to set the plugin parameters correctly according to our image bank account and our import wishes : periodic import, one-time import, only videos, alll media types, media property mapping, etc…

Then we can launch the import process.

PACKAGED_ImgBank needs features from WXM_RESTAPI which have been brought with 2022.6.0, therefore it can not be used on versions below 2022.6.0.

1/ Instructions : Setting the plugin parameters

destination_library => Destination media library for the imported media
destination_asset_status => Id of the target status for the imported media
source_image_bank => JSON Array describing the access tokens which have to be used for the authentication part during the media data retrieval. We can set multiple access tokens, each access token must have a “type” which is the image bank to which it is related. Example of value for the parameter :

[
    {
        "type": "shutterstock",
        "token": "XXXXxxxxXXXX"
    },
    {
        "type": "shutterstock",
        "token": "WONT_WORK"
    },
    {
        "type": "getty",
        "token": "testing"
    }
]

mediadata_mapping => JSON Object describing a mapping for the retrieved data from the image bank. The new assets created in the dam, will recieve information from the image bank according to the mapping config. Example of value for the parameter :

{
    "description": "description",
    "contributor": {
        "id": "photograph.externalid",
        "display_name": "photograph.name"
    },
    "keywords": "ai_concepts"
}

As we can see, there is complex mapping and simple mapping.

In the left part of the JSON Object we are using the property names used by the image bank.

In this case, shutterstock’s media’s description, contributor and keywords are retrieved and written on the new asset.

In the right part of the JSON Object we are using the property names of the target properties on the destination media library.

In this case the asset will be created with asset.description, with asset.photograph and with asset.ai_concepts already set, and comming from the image bank.

The retrieval of boolean values or date values from the image bank is not supported by this first version of the plugin

If the asset prop set in the config is a child or a cmlr, we have to search or create a new metadata instance and attach it to the asset.

For a simple mapping, the search/creation is done by the name property of the metadata structure. In our case, for each image bank keyword retrieved which is not already present in our database under ai_concepts’s structure : assetiaconcept (search by name) we will create a new instance by setting the name (only) found/received from the image bank as media data.

If an instance with the same name is already present in our data base, we will not create it, but only return the id of the existing instance.

For a complex mapping, we will first do the search/create by the id mapped prop if it is used in the left part of the config, if not, we will do the search/create by the code mapped prop if it is used in the left part of the config, if not we will do the search/create by the name mapped prop if it is used in the left part of the config. And if neither of the three props are decribed in the left part of a complex mapping, then we will do nothing, and a warning will be raised (log).

In our case, we will create a new instance of photograph (assetauthor) if the search by assetauthor.externalid returns nothing. Assetauthor.externalid is used for the search, because it is the destination of the id value from the image bank.

imgBank_name_wearing_prop => Property which will bear the source information about the imported media on the newly created asset.

This parameter is mandatory and the property described by this parameter should be existing on the asset destination structure

synchronisation_frequency => JSON Object describing the synchronization frequency which should be applied if the import is a periodic task. Example of value for the parameter :

{
  "frequency":"daily", 
  "fetchingHour":"23:00:00"
}

The frequency value has to be : daily or weekly or monthly. This value will define the periodicity for the import task.

The fetchingHour value will define the hour at which the import task will begin.

Then according to the freqency, the import task will retrieve medias bought from now - 1 day, or now - 7 days or now - 30 days, with now beeing the moment when the import process starts

owner => Id of user which will be used as owner of the new assets

media_type => Media types of media to retrieve from the image bank.

For now the plugin can retrieve only image, video and audio files. If we want to retrieve media from all the media types available with the plugin we can use “ * “ as value for this parameter. Else we can choose media types by separating them with a “ , “. Exemple : image,video

synchro_task_on_startup => Boolean which defines if the periodic import task will be activated at the plugin activation or if it will be activated by post actions.

2/ Application : REST Actions

2.1/ Authentication test

We can test the authentication settings by making a GET API call to this endpoint :

api/packaged/dam/img-bank/authentication/test

There is no parameter to set to make the call but we have to be authenticated. The response will describe foreach access token if the connection is established or not, and if not we will have the reason.

2.2/ Manual import

We can make a manual import of media by making a POST API call to this endpoint :

api/packaged/dam/img-bank/import

There are parameters for this endpoint but they are not mandatory.

start_date : Date from which to consider assets as retrievable. Must follow this format : YYYY-MM-DD
end_date : Date until which to consider assets as retrievable. Must follow this format :YYYY-MM-DD and must be after start_date
max : Max number of retrieved medias by media type
per_page : Nb media per page (default 50)

We have to be authenticated to make the API POST CALL
The import will be made for each valid access token set in plugin parameters.

If end_date is set before start_date (start_date not empty) then only start_date will be used for the media retrieval.

When the import is finished, the process is returning a JSON response.

Example :

2.3/ Scheduled import task start

We can activate the scheduled periodic import task by making a POST API call to this endpoint :

api/packaged/dam/img-bank/import/scheduled/start

There is no parameter to set to make the call but we have to be authenticated.

If the frequency parameters are set correctly we will recieve a JSON response with a message, describing the periodicity of the import task and the launch hour.

Example :

If the frequency parameters are incorrect or if there has been an error, the response will be different.

When the scheduled task has been started, we should see this in the thread pool manager (admin)

When the thread is “alive”, it will launch the import task at the hour set in plugin parameters every day, or every 7 days or every 30 days…

2.3/ Scheduled import task stop

We can stop the scheduled periodic import task by making a POST API call to this endpoint :

api/packaged/dam/img-bank/import/scheduled/stop

There is no parameter to set to make the call but we have to be authenticated.

If there is as an error during the stop of the process, we will recieve a response which will indicate that there has been an error and which will invite us to check the logs, if everything went fine we will recieve a simple success message and we should see that the thread is terminated (in the thread pool manager)

When the thread is terminated, the import task will not be launched periodically anymore, we have to restart it (the thread) with the previous call to have a periodic import again.