Available search methods using content information

Available search methods using content information

This article aims to highlight the best practices for content search in THRON through dedicated service findByProperties, exploiting all of the content information as reported in its getContentDetail.

Typically, content searches in THRON exploit the textual research, combined with different parameters that allow you to fine-tune the search filter. The other method is to search for content by its contentId.

 

Search content by ID

 

Let's start from this second case, which is the most simple. Among the criteria of the findByProperties, you will find the "contentIds" parameter, which allows you to specify an array of contentIds. Filling appropriately that array will return all the specific content associated with those IDs. The body of the request will be structured as follows:

{
    "client": {
        "clientId": ""
    },
    "criteria": {
        "contentIds": [""]
    }
}

 

Text search

 

The easiest search method exploiting text is the one that looks for the presence of a specific keyword in the title or description of content. This can be done by using the textsearch object which includes the following parameters: 

  • searchKey: (string, optional) the specific keyword (or keywords) to be used by the search.
  • searchKeyOption: (string, optional) this parameter is used to specify the search method to be used according to the provided keywords. You might want to retrieve all the content matching exactly the keyword provided, or you might want to retrieve all content containing one or more of the provided keywords: according to the method you prefer, you will have to use "EXACT_MATCH" or "BY_TOKEN.
  • searchOnFields: (string, optional) this is an array of available basic information on which the search has to operate. Available values are: NAME, DESCRIPTION, OWNER,ITAGS. The "OWNER" operator will search on the metadata related to the contents' author which typically matches the owner.

 

Remember that the "locale" parameter has to be included in the request body in order to perform a proper search. This is a sample JSON which can be included in the request body:

{
    "client": {
        "clientId": ""
    },
    "criteria": {
        "locale": "EN,IT",
        "textSearch": {
            "searchKey": "",
            "searchOnFields": [
                "NAME",
                "DESCRIPTION",
                "ITAGS"
            ],
            "searchKeyOption": "EXACT_MATCH"
        }

    }

}

This simple text search can be combined with all the other available parameters in order to perform advanced searches with more accurate filtering, let's have a look at the available parameters:

  • contentType: (string, optional) you can filter your search by content type, available values are: VIDEO, IMAGE, AUDIO, PLAYLIST, DOCUMENT, OTHER, PAGELET.
  • fromDate/toDate: (strings, optional) you can filter your search by a time interval to identify the creation date of the content you want to retrieve. Dates must be expressed in the form yyyy-mm-dd and they are recorded into platform with the UTC format, so that users can retrieve them according to their timezone.
  • linkedContentId:  (string, optional) you can filter your search in order to retrieve content that are linked to another specific content, providing its contentId
  • acl: you can filter your search by the acl status of the content related to the token you are using to perform the request, providing the following parameters:
    • onContext: (string, optional) this parameter is used to identify wether the specific acl is acquired because it has been specifically assigned to the user (DIRECT), because it has been inherited from a folder (DERIVED), or becuase it is an exclusive prerogative of the user (EXCLUSIVE)
    • rules: (string, optional) the specific acl you want to filter by; available values are: SEEN_BY (default), MODIFIED_BY, SHARED_BY, BELONGS_TO. They can both be expressed in a positive way (include the rule in the search) or in a negative way (exclude the rule from the search): "!_RULENAME".
  • itagOp: you might want to filter your search in order to retrieve only those content with one or more specific itags. In order to do so you will have to fill the following array:
    • itags (array, optional):
      • id: (string) the Id of the tags you want to include in the search (must belong to the same classification).
      • classificationId: (string) the id of the classification where the tags have been defined.
  • imetadataKeyOp: you might want to filter your search in order to retrieve only those content with a specific key metadata value (one or more). In order to do so you will have to fill the following array:
    • imetadata (array, optional):
      • classificationId: (string) the id of the classification where the key metadata has been defined.
      • key: (string) the id of the key metadata.
      • value: (string) the value of the key metadata that must be set on the content in order to be retrieved.
  • linkedCategoryOp: you might want to filter your search in order to retrieve only those content which have been published in a specific folder (or in a specific set of folders). In order to do so, you will have to fill the following array:
    • linkedCategoryIds: (array) the categoryIds of the folders where the content you want to retrieve has to be published.
    • cascade: (boolean, optional) by setting this parameter to "true", the search will automatically look also in the subfolder of the provided categories.
  • orderBy: (string, optional) this parameter can be used to set the sorting order of the result. They can both be expressed in the ascending mode (sortingvalue_A) or the descending one (sortingvalue_D).Available values are: contentName, creationDate, viewCounter, ratingCounter, lastUpdate, contentType or contentRead.

 

According to the information you want to retrieve in the response of your request, you will be able to flag the available parameters of the contentFieldOption object, which are boolean parameters whose default is "false":

  • returnLinkedContents
  • returnLinkedCategories
  • returnEmbedCodes
  • returnThumbnailUrl
  • returnItags
  • returnImetadata 

 

Fast request to retrieve content

 

If you need a fast way to retrieve content you can use the showContents web service. Such web service is a GET request, it means that the response is cached, and eventual updates on the content might require some time to be displayed in the response. For this reason we recommend to use this service only with particular attention, especially if you need to perform an integration which might involve a huge number of content, for which an export request is more suitable. More information can be found in this article.
The url of the showContents request is structured as follows:

https://[clientId]-view.thron.com/api/xcontents/resources/contentlist/showContents?clientId=[clientId]&locale=[locale]&categoryId=[categoryId]&searchOnSubCategories=true&xcontentIds=[xcontentIds]&contentType=[contentType]&searchKey=[searchKey]&orderBy=[orderBy]

 

Available parameters are:

  • clientId: (string, mandatory) the domain name used to access your THRON, usually your company name.
  • locale: (string, optional) this parameter can be used to specify a specific locale which must be set on the retrieved content.
  • categoryId: (string, optional) this parameter allows you to limit your search to a specific folder by providing its categoryId.
  • searchOnSubCategories: (boolean, optional) if categoryId is defined, this parameter allows you to enable the search even on its subfolders.
  • xcontentIds: (string, optional) this parameter allows you to limit your search to a specific set of content.
  • contentType: (string, optional) this parameter allows you to limit your search to a specific set of content type.
  • searchKey: (string, optional) this parameter allows you to add a text filter on your search by providing a keyword. The search operates on the following fields: NAME, DESCRIPTION, OWNER.
  • orderBy: (string, optional) you can use this parameter to set the sorting order of the response.

NOTE: This method does not return advanced information on the content such as itags or imetadata. To retrieve them, you will have to use the findByProperties request, as illustrated above.

Was this article helpful?
0 out of 0 found this helpful

Have more questions?

SUBMIT A REQUEST

Hai altre domande?

INOLTRA UNA RICHIESTA

Comments