Update/replace publication metadata - Fluid Topics - Latest

Fluid Topics API Reference Guide
Category
Reference Guides
Audience
public
Version
Latest

As documentation evolves, it may be necessary to modify the metadata associated with it. This web service modifies the metadata of the publication defined in the endpoint by either updating or replacing the metadata specified in the request body.

  • Users or API keys with the CONTENT_PUBLISHER role can only update the metadata of a publication published through a source they have permissions for.
  • Reuploading a publication with its original metadata overrides changes made using this web service.
  • Using the replace mode deletes all of the metadata previously assigned to a publication or its topics in structured documents.
  • It is necessary to provide an Ft-Calling-App value when using Fluid Topics web services. See Fluid Topics calling app.
  • It is possible to update or replace all custom metadata with this web service.
  • It is possible to update or replace the following built-in metadata with this web service: ft:title, ft:locale, ft:openMode, ft:originUrl, ft:clusterId, ft:lastEdition, ft:editorialType, and ft:description.
  • By default, a document's topics inherit the updated metadata. It is possible to override this behavior by setting the value of the inheritance parameter to false in the JSON request body.
  • It is not necessary to reprocess content for the metadata update to take effect.
Method Endpoint
PUT 
/api/admin/khub/publications/update-metadata?metadata1=value1&...&metadataN=valueN
Query string parameter Type Required? Description
metadata=value String Yes Any metadata key-value set that is unique to the publication to update.

Targeting publications by using the same metadata key with two different values (audience=internal&audience=external) relies on the Behavior parameters of the Search facets menu:

  • If the Value selection and combination of the audience metadata key is Multiple — Or, all publications with internal or external receive the metadata update.
  • If the Value selection and combination of the audience metadata key is Multiple — And, all publications with internal and external receive the metadata update.
  • The document's originId is often a good candidate for use in the endpoint as it is the publication's unique identifier.
  • The metadata targeted in the endpoint is only used to identify the publication to be updated and is not itself updated.

Updating metadata deletes the previous value and replaces it with the newly defined value.

Request example

The following lines show an example of JSON request body:

{
  "mode": "update",
  "metadata": [
    {
      "key": "product",
      "value": "Fluid Topics"
    },
    {
      "key": "audience",
      "values": [
        "public",
        "internal"
      ]
    },
    {
      "key": "versions",
      "hierarchicalValues": [
        [
          "3.x.x",
          "3.6.x",
          "3.6.2"
        ],
        [
          "3.x.x",
          "3.6.x",
          "3.6.3"
        ]
      ]
    }
  ],
  "inheritance": false
}

The request body expects the following fields:

Field Type Required? Description
mode String Yes The mode parameter has two possible values:
  • update (default): keeps the publication's previous metadata keys and replaces the specified key / value pairs with the newly defined metadata keys.
  • replace: deletes all of the publication's previous metadata keys and replaces them with only the newly defined metadata keys from the request body.
metadata Array Yes Expects the list of the new metadata key-value sets.
key String Yes The metadata key associated with the values to be updated.
value String Yes Defines a single value for the selected key.
values String Yes Defines values for the selected key.
hierarchicalValues Array Yes Defines hierarchical values for the selected key. It can have an unlimited number of arrays, each representing a hierarchical metadata key. Inside an array, the first string is the value highest in the hierarchy. Each following value is one level down.
inheritance Boolean Yes The inheritance parameter has two possible values:
  • true: the document's topics inherit the new metadata.
  • false: the document's topics do not inherit the new metadata.
The default value is true.

If mode is set to replace and inheritance is set to true, metadata are replaced at the document level but updated at the topic level.

If a user wants to update a metadata with multiple values, the request field must be values instead of value.

Return code Description
202 ACCEPTED The update instruction was sent to the Fluid Topics processing pipeline.
400 BAD REQUEST Invalid query.

Update versus replace

When defining the update value for the mode parameter, the publication's previous metadata is visible along with the newly defined metadata as follows:

A document metadata view displaying custom metadata. In a highlighted section labeled 'audience: internal', there are two entries. The first entry has a key 'audience' and value 'public'. The second entry has a key 'audience' and value 'internal'. A tag labeled '1 change' is present at the top right corner of this section.

When defining the replace value for the mode parameter, all of the publication's previous metadata is deleted and replaced by only the newly defined metadata as follows:

A document metadata view with the title 'Document "Upload Author-it Content to Fluid Topics"'. At the bottom, a highlighted section labeled 'Custom metadata' displays one item: 'audience' with the value 'internal'.