Keepeek - Best practices: mass update (bulks)

Context

If you need to apply a specific update on multiple media, it is not a good practice to update the media one by one. For this specific use case, you can use the mass update feature!

Limits:

There are 3 steps to execute mass update of medias:

1. Create a selection of media to update
   
   
2. Populate the selection
   Warning: 10 000 medias max, if more medias needed, contact the support
   
   
3. Build and execute the update on the selection
   Warning: the processus is synchronous, so it might takes up to some minutes if the update is large.

Step 1 - Creation of selection

A selection is like a selection of media you can do on the Back-office application.

To create a media selection on the API, do a POST request on:

/api/dam/users/{{userId}}/selections with the ids of the medias :

curl --request POST \
--url https://{{KeepeekInstance}}/api/dam/users/{{userId}}/selections \
--header 'authorization: Basic baseEncodedLoginPassword' \
--header 'content-type: application/json'

This request create a selection.

You should receive a response of the form:

{
    "id": "{{selectionId}}",
    "expirationDate": "2025-03-12T18:05:46.000Z",
    "mediaCount": 0,
    "_links": {
        "self": {
            "href": "https://{{KeepeekInstance}}/api/dam/users/{{userId}}/selections/{{selectionId}}"
        },
        "curies": [
            {
                "name": "kpk",
                "href": "https://{{KeepeekInstance}}/api/doc/rels/{rel}",
                "templated": true
            }
        ],
        "kpk:medias": {
            "href": "https://{{KeepeekInstance}}/api/dam/users/{{userId}}/selections/{{selectionId}}/medias"
        },
        "kpk:terms-of-use": {
            "href": "https://{{KeepeekInstance}}/api/dam/users/{{userId}}/selections/{{selectionId}}/terms-of-use"
        },
        "kpk:media-types": {
            "href": "https://{{KeepeekInstance}}/api/dam/users/{{userId}}/selections/{{selectionId}}/media-types"
        },
        "kpk:exports": {
            "href": "https://{{KeepeekInstance}}/api/dam/users/{{userId}}/selections/{{selectionId}}/exports"
        },
        "kpk:bulks": {
            "href": "https://{{KeepeekInstance}}/api/dam/users/{{userId}}/selections/{{selectionId}}/bulks"
        },
        "kpk:available-export-formats-by-media-type": {
            "href": "https://{{KeepeekInstance}}/api/dam/users/{{userId}}/selections/{{selectionId}}/available-export-formats?groupBy=mediaType"
        }
    }
}

Step 2 - Populate the selection

Currently, the selection does not contain any media, we need to populate it with medias.

To do so, you need to do a POST request on the path: /api/dam/users/{{userId}}/selections/{{selectionId}}/medias-collection

curl --request POST \
--url https://{{KeepeekInstance}}/api/dam/users/{{userId}}/selections/{{selectionId}}/medias-collection \
--header 'authorization: Basic baseEncodedLoginPassword' \
--header 'content-type: application/json' \
--data '{
          "ids": [
            64,
            66,
            67
          ]
        }'

Now the selection is populated, in order to check it, you can do a GET request on:

api/dam/users/{{userId}}/selections/{{selectionId}}/medias

curl --request POST \
--url https://{{KeepeekInstance}}/api/dam/users/{{userId}}/selections/{{selectionId}}/medias \
--header 'authorization: Basic baseEncodedLoginPassword' \
--header 'content-type: application/json'

Step 3 - Build and execute the update on the selection

What field can I update with my current selection ?

First, we need to know what field we can update, meaning what updatable field are in common within all medias in the selection. It works with media with different media sheet as long as they have the sheet fields in common.

To know this information, do GET request on the path 

curl --request GET \
--url https://{{KeepeekInstance}}//api/dam/users/{{userId}}/selections/{{selectionId}}/bulks/fields \
--header 'authorization: Basic baseEncodedLoginPassword' \
--header 'content-type: application/json'

You should receive a response like:

{
    "_links": {
        "curies": [
            {
                "name": "kpk",
                "href": "https://{{KeepeekInstance}}/api/doc/rels/{rel}",
                "templated": true
            }
        ],
        "self": {
            "href": "https://{{KeepeekInstance}}/api/dam/users/{{userId}}/selections/{{selectionId}}/bulks/fields"
        }
    },
    "_embedded": {
        "field": [
        {
              "id": "couleur",
              "title": "Colors",
              "type": "THESAURUS",
              "mandatory": false,
              "forceSelection": true,
              "summary": false,
              "publicDisplay": true,
              "portalDisplay": true,
              "visible": true,
              "editable": true,
              "_links": {
                "self": {
                  "href": "https://{{KeepeekInstance}}/api/dam/forms/1/fields/200"
                },
                "kpk:thesaurus": {
                  "href": "https://{{KeepeekInstance}}/api/dam/thesauruses/916"
                }
              }
            },
            {
                "id": "title",
                "title": "Title",
                "type": "TEXT",
                "mandatory": true,
                "summary": true,
                "publicDisplay": true,
                "portalDisplay": true,
                "visible": true,
                "editable": true,
                "_links": {
                    "self": {
                        "href": "https://{{KeepeekInstance}}/api/dam/forms/1/fields/2"
                    }
                }
            },
        ...
        ]
    },
    "totalCount": 41
}

Choose the mode

There are 3 modes for the update, you can specify modes for each metadata:

• CLEAR (It clears the field)
• REPLACE (replace the current value with the specified one)
• APPEND (add the specified value after the current field value)
• REMOVE (remove the specified value from the current field value) (available on Backoffice 4.124.0 version)

By default, REPLACE is used.

To use CLEAR, do not specify a value for your field

To use APPEND, add the boolean append with a value true or use the mode attribute with value APPEND

Example :

// with append attribute
{
  "id": "turtle",
  "value": "is blue",
  "append": true
}

// with mode attribute
{
  "id": "turtle",
  "value": "is blue",
  "mode": "APPEND"
}

To use REMOVE, add the mode attribute with REMOVE value

Example :

{
  "id": "turtle",
  "value": "is blue"
  "mode": "REMOVE"
}

For information the mode attribute override the append one. This means that if both append and mode attribute are present at the same time, the mode value will be take into account while the append value will be ignored.

Example :

{
  "id": "turtle",
  "value": "is blue",
  "append": true
  "mode": "REMOVE"
}

Will prepare a Bulk in REMOVE mode

Choose the language(s) of the update

You can update your fields in one or multiple languages, for that, you need to use the Content-Language header with country codes. If no Content-Language header is specified, the default language of the user making the call is used.

Examples :

• Content-Language: fr -> The update is made on the french language only
• Content-Language: fr,en,de -> The update is made on French, English and German.

Change status of medias

To change medias status, we need to send link of the wanted status in the:

_links.kpk:custom-status.

To know the available status, do a GET request on the path:

{{apiUrl}}/api/dam/medias/custom-statuses.

WARNING: Be mindful that the rules of published status apply here. Trying to publish medias while their mandatory fields are not filled will resolve into an error, and none of the medias in the selection will be updated. However, if you fill the mandatory fields in the same request, it works !

Execute request on a simple example!

Example:

If you want to replace the title of the medias with "newTitleMassUpdate" in french only

and then add the value with id 922 and 933 for the thesaurus couleurs

and also change the status of the medias to the PUBLISHED status.

Finally, execute the POST request on :

api/dam/users/{{userId}}/selections/{{selectionId}}/bulks

Make sure to specify the Content-Language header with the value "fr".

We need to add the mode APPEND to thesaurus field.

We need to add the link to the new status.

Note: You need to specify the id for each metadata and its value. For the thesaurus, the value is wrapped into an _embedded field.

curl --request POST \
--url https://{{KeepeekInstance}}/api/dam/users/{{userId}}/selections/{{selectionId}}/bulks \
--header 'authorization: Basic baseEncodedLoginPassword' \
--header 'Content-Language: fr' 
--header 'Content-Type: application/json' \
--data '
{
  "_links": {
    "kpk:custom-status": {
      "href": "https://{{KeepeekInstance}}/api/dam/medias/custom-statuses/{{publishedStatusId}}"    
    }
  },
  "_embedded": {
    "metadata": [
      {
        "id": "title",
        "value": "newTitleMassUpdate"
      },
      {
        "id": "couleur",
        "mode": "APPEND",
        "_embedded": {
          "value": [
            {
              "id": 922
            },
            {
              "id": 933
            }
          ]
        }
      }
    ]
  }
}'

Result:

With that request, all the medias will have the title newTitleMassUpdate and the thesaurus values of id 922 and 933 added for the thesaurus couleur. It will also change the media status to PUBLISHED.