Aller au contenu principal
Scroll to top

Keepeek - Advanced Search

Lucas Simon
  • dam --> search --> advanced: represents all the available advanced searches for current user. Those can be either advanced searches saved from the backoffice or temporary searches built from API to be used once ready. Shared advanced searches also appear here. Only advanced searches saved with fields values will appear in the collection.

Sine 4.84.0 shared advanced search will be part of the API response, the share attribute indicates if the advanced search is a shared one. In the case of a share advanced search, the link kpk:shared-by-user indicates wich user has shared the advanced search.

This relation targets the resource representing an advanced search with all its associated filters

GET http://baobab.keepeek.com/api/dam/search/advanced/31 HTTP/1.1
[...]
HTTP/1.1 200 OK
Content-Type: application/hal+json;version=1;charset=UTF-8
[...]
{
  "id": "31",
  "name": "Example saved advanced search",
  "type": "SAVED",
  "shared": false,
  "_links": {
    "self": {
      "href": "http://baobab.keepeek.com/api/dam/search/advanced/31"
    },
    "curies": [
      {
        "name": "kpk",
        "href": "http://baobab.keepeek.com/api/doc/rels/{rel}",
        "templated": true
      }
    ],
    "kpk:filters": {
      "href": "http://baobab.keepeek.com/api/dam/search/advanced/31/filters"
    }
  },
  "_embedded": {
    "filter": [
      {
        "internalFieldName": "metamodelId",
        "modifier": "EQUALS_NO_VALUES",
        "showSub": false,
        "type": "LISTFIELD",
        "fieldType": "MEDIAFIELD",
        "saveValues": true,
        "values": [
          6,
          9
        ],
        "_links": {
          "self": {
            "href": "http://baobab.keepeek.com/api/dam/search/advanced/31/filters/0"
          }
        }
      },
      {
        "internalFieldName": "couleur",
        "modifier": "CONTAINS_ONE",
        "showSub": false,
        "type": "THESAURUSFIELD",
        "fieldType": "METAFIELD",
        "saveValues": true,
        "values": [],
        "_links": {
          "self": {
            "href": "http://baobab.keepeek.com/api/dam/search/advanced/31/filters/1"
          }
        }
      },
      {
        "internalFieldName": "keywords.FR",
        "modifier": "CONTAINS_ONE",
        "type": "MULTIPLELISTFIELD",
        "fieldType": "METAFIELD",
        "saveValues": true,
        "values": [
          "volcan"
        ],
        "_links": {
          "self": {
            "href": "http://baobab.keepeek.com/api/dam/search/advanced/26/filters/2"
          }
        }
      }
    ]
   }
 }

filters

This relation targets the collection of filters of an advanced search.

media

This relation targets the collection of media matching an advanced search filters.

Search results can be narrowed down using the same query parameters as for standard media search :

Query parameter Description Arity
q Full-text search parameter, terms are searched in all indexed fields. Its supports Lucene Query parser syntax. [0-1]
f Field based search. Multiple parameter can be used simultaneously [0-n]
fq Filter query parameter. Search terms (f or q parameters) only applies against filtered documents. [0-n]
sort Define the field and the direction to sort results on. [0-1]
page The requested page number in the result list. [0-1]
size Number of media to return per page. [0-1]
fields Specify which field from the representation must be returned  
facet-fields Specify a list of facet fields to return instead of the ones configured backoffice side (comma-separated list of facet field IDs, see facet-fields resource) [0-1]
facet-values-number Specify the number of facet values in api response [0-1]

See media-search section above for more details and examples

GET http://baobab.keepeek.com/api/dam/search/advanced/31/media HTTP/1.1
[...]
HTTP/1.1 200 OK
Content-Type: application/hal+json;version=1;charset=UTF-8
[...]
{
  "_links": {
    "self": {
      "href": "http://baobab.keepeek.com/api/dam/search/advanced/rk16ay4x/media?page=1&size=20"
    },
      "curies": [
      {
        "name": "kpk",
        "href": "http://baobab.keepeek.com/api/doc/rels/{rel}",
        "templated": true
      }
      ],
      "next": {
        "href": "http://baobab.keepeek.com/api/dam/search/advanced/rk16ay4x/media?page=2&size=20"
      },
      "last": {
        "href": "http://baobab.keepeek.com/api/dam/search/advanced/rk16ay4x/media?page=62&size=20"
      }
  },
    "_embedded": {
      "media": [
      {
        "id": 4176,
        "title": "Media-4176-NotPublish",
        "permission": "WRITE",
        "mediaType": "image/jpeg",
        "fileSize": 18402,
        "fileSizeString": "18 Ko",
        "updateDate": "2018-11-28T12:05:45.000Z",
        "duplicationStatus": "NO_DUPLICATES",
        "thumbnailGenerationStatus": "GENERATED",
        "_links": {
[...]
        }
      },
      {
        "id": 4177,
        "title": "Media-4177-NotWrite",
        "permission": "READ",
        "mediaType": "image/jpeg",
        "fileSize": 18402,
[...]

criterias

This relation targets all the criteria available for building an advanced search

GET http://baobab.keepeek.com/api/dam/search/advanced/criterias HTTP/1.1
[...]
HTTP/1.1 200 OK
Content-Type: application/hal+json;version=1;charset=UTF-8
[...]
"_embedded": {
  "criteria": [
    {
      "internalFieldName": "couleur",
      "availableModifiers": [
        "CONTAINS_ONE",
        "CONTAINS_ALL",
        "CONTAINS_NONE",
        "EMPTY",
        "NOT_EMPTY"
      ],
      "type": "THESAURUSFIELD",
      "fieldType": "METAFIELD",
      "_links": {
        "self": {
          "href": "http://baobab.keepeek.com/api/dam/search/advanced/criterias/couleur"
        },
        "kpk:sheet-field": {
          "href": "http://baobab.keepeek.com/api/dam/sheet-fields/couleur"
        }
      }
    },
    {
      "internalFieldName": "end_date",
      "availableModifiers": [
        "DATE_TODAY",
        "DATE_YESTERDAY",
        "DATE_LAST_7_DAYS",
        "DATE_LAST_30_DAYS",
        "DATE_LAST_MONTH",
        "DATE_CURRENT_MONTH",
        "FROM_TO",
        "EQUALS",
        "EMPTY",
        "NOT_EMPTY"
      ],
      "type": "DATEFIELD",
      "fieldType": "METAFIELD",
      "_links": {
        "self": {
          "href": "http://baobab.keepeek.com/api/dam/search/advanced/criterias/end_date"
        },
        "kpk:sheet-field": {
          "href": "http://baobab.keepeek.com/api/dam/sheet-fields/end_date"
        }
      }
    },
    {
      "internalFieldName": "product",
      "availableModifiers": [],
      "type": "LISTFIELD",
      "fieldType": "METAFIELD",
      "_links": {
        "self": {
          "href": "http://baobab.keepeek.com/api/dam/search/advanced/criterias/product"
        },
        "kpk:sheet-field": {
          "href": "http://baobab.keepeek.com/api/dam/sheet-fields/product"
        },
        "kpk:lookup": {
          "href": "http://baobab.keepeek.com/api/dam/forms/lookups/1"
        }
      }
    },
[...]

Sharing options

Since 4.84.0, sharing options of a permanent advanced search can be accessed and updated by its owner through the /share resource.

View sharing options

GET /api/dam/search/advanced/14/share

{
  "sharedWithUsers": [
    {
      "id": 4,
      "lastName": "Siteur",
      "firstName": "Vi",
      "email": "visiteur@keepeek.com",
      "_links": {
        "self": {
          "href": "http://baobab.keepeek.com/api/dam/users/4"
        }
      }
    },
    {
      "id": 28,
      "lastName": "Scott",
      "firstName": "Michael",
      "email": "michael.scott@keepeek.com",
      "_links": {
        "self": {
          "href": "http://baobab.keepeek.com/api/dam/users/7"
        }
      }
    },
    {
      "id": 17,
      "lastName": "Tyler",
      "firstName": "Rose",
      "email": "rose.tyler@keepeek.com",
      "_links": {
        "self": {
          "href": "http://baobab.keepeek.com/api/dam/users/71"
        }
      }
    }
  ],
  "sharedWithGroups": [
    {
      "id": 3,
      "name": "Contributeurs",
      "_links": {
        "self": {
          "href": "http://baobab.keepeek.com/api/dam/groups/3"
        }
      }
    }
  ],
  "sharedToAll": false,
  "_links": {
    "self": {
      "href": "http://baobab.keepeek.com/api/dam/search/advanced/14/share"
    },
    "curies": [
      {
        "name": "kpk",
        "href": "http://baobab.keepeek.com/api/doc/rels/{rel}",
        "templated": true
      }
    ]
  }
}

An advanced search can be shared:

  • with one or several users > sharedWithUsers property
  • with one or several groups > sharedWithGroups property
  • with all users > sharedToAll property

Update sharing options

It is possible to update the sharing options of the advanced search with a PUT request.

Adding and/or removing users and/or groups:

PUT /api/dam/search/advanced/14/share

{
  "sharedWithUsers": [],
  "sharedWithGroups": [
    {
      "id": 3
    },
    {
      "id": 4
    }
  ]
}

Sharing to all users:

PUT /api/dam/search/advanced/14/share

{
  "sharedToAll": true
}

Disabling the share:

PUT /api/dam/search/advanced/14/share

{
  "sharedWithUsers": [],
  "sharedWithGroups": [],
  "sharedToAll": false
}

4.84.0+

A new advanced search can be created by sending POST request on the dam/search/advanced resource.

The body of the request must be a valid advanced search representation. It must include a valid array of advanced search filters as an embedded property named filters.

POST /api/dam/search/advanced
Content-Type: application/json

{ 
  "_embedded": {
    "filter": [
      { 
        "internalFieldName": "metamodelId",
        "modifier": "CONTAINS_ONE",
        "type": "LISTFIELD",
        "fieldType": "MEDIAFIELD",
        "values": [
          1
        ]
      },
      { 
        "internalFieldName": "folderId",
        "modifier": "EQUALS_NO_VALUES",
        "showSub": false,
        "type": "FOLDERFIELD",
        "fieldType": "MEDIAFIELD",
        "values": [
          523
        ]
      }
    ] 
  } 
}

Api returns the url of the created advanced search in the Location response header, ex.: Location: http://baobab.keepeek.com/api/dam/search/advanced/ndvcq9vu The newly created advanced search will also appear

/!\ Temporary searches have an expiration date, and might be automatically removed The expiration date is not guaranteed by the API as temporary resources may be wiped out for maintenance purpose. *

Filters can be built using the criterias resource which show all internalFieldName, with their corresponding fields values. Note that every filter representation must have internalFieldName, modifier, type, fieldType fields defined. internalFieldName, type and fieldType fields have fixed values, as defined in criterias. values field might be required, depending on the modifier field value (for exemple, EMPTY or DATE_TODAY modifiers do not require values to be set).

The acceptable values for modifier field depend on the type of sheet-fields, and are listed in the criteria resource. Here are all the possible modifier values, and their meaning. Not all values are available for one filter !

Modifier Description
EQUALS Field value is strictly equals to
EQUALS_ONE Field value is strictly equals to one of the values
CONTAINS_ONE (Multivalue) Field value contains one of the values
CONTAINS_ALL (Multivalue) Field value contains all the values
CONTAINS_NONE (Multivalue) Field value does not contain any of the values
BEGINS_WITH Text field begins with value
ENDS_WITH Text field ends with value
EQUALS_NO_VALUES Field value is strictly different from any value
FROM_TO Numeric/Date field value is in range FROM-TO
EMPTY Field is empty
NOT_EMPTY Field is not empty
DATE_TODAY Date field value is equals to today (at the time the search is executed)
DATE_YESTERDAY Date field value is equals to yesterday (at the time the search is executed)
DATE_LAST_7_DAYS Date field value is equals to any date in the last 7 days (at the time the search is executed)
DATE_LAST_30_DAYS Date field value is equals to any date in the last 30 days (at the time the search is executed)
DATE_LAST_MONTH Date field value is equals to any date in previous calendar month (at the time the search is executed)
DATE_CURRENT_MONTH Date field value is equals to any date in current calendar month (at the time the search is executed)
GROUP_CONTAINS_ONE Users/Group value is one of the group ids
GROUP_CONTAINS_NONE Users/Group value is none of the group ids
DATE_UPCOMING_DAYS Date field value is equals to any date in the requested next days
DATE_FROM_TO_UPCOMING_DAYS Data field is contained in the days the configured days interval

The showSub field in only applicable for tree-based sheet-fields, like folderId or any thesaurus field. If set to true, children nodes of current value will also be considered in the filter.

The values field is always an array of values, which might contain only one element. Values can be String or Integer. Except for numeric fields, Integer values represent ids of elements (ex folder id, thesaurus node id,...). Dates values are set using RFC 3339 §5.6 date/time format String representation (ie "2019-11-13T21:33:45+0200" ) If FROM_TO or DATE_FROM_TO_UPCOMING_DAYS modifiers are used, the values array must contain two elements. First one corresponds to the 'FROM' value, and the second one is the 'TO' value.

Since 4.36.0, it is now possible to do an advanced search on theduration mediafield in seconds using the following type of criteria filter: DURATIONFIELD. (it is always possible to search in minutes using the criteria filter type NUMBERFIELD).

Since 4.84.0, it is now possible to create not temporary advanced search, to do it, the paylod of api call must contains type and title attributes.

POST /api/dam/search/advanced
Content-Type: application/json

{ 
  "type" : "SAVED",
  "name": "Advanced search name",
  "_embedded": {
    "filter": [
      { 
        "internalFieldName": "metamodelId",
        "modifier": "CONTAINS_ONE",
        "type": "LISTFIELD",
        "fieldType": "MEDIAFIELD",
        "values": [
          1
        ]
      },
      { 
        "internalFieldName": "folderId",
        "modifier": "EQUALS_NO_VALUES",
        "showSub": false,
        "type": "FOLDERFIELD",
        "fieldType": "MEDIAFIELD",
        "values": [
          523
        ]
      }
    ] 
  } 
}

Attachments filter

Since 4.73.0, it is possible to add a filter related to element attachments.

The internalFieldName to use is advancedSearchByAttachment, the type is ATTACHMENTSFIELD and the fieldType MEDIAFIELD.

The advanced search can then be filtered on elements having at least one attachment (CONTAINS_ONE modifier) or no attachment at all (EMPTY modifier).

When filtering on elements having an attachment, the attachment cloud provider status can be specified by adding a statuses array in the filter values. Possible statuses are ONLINE, OFFLINE and PENDING_TO_ONLINE.

For example, to filter on elements having only offline attachments or no attachment at all, the following advanced search can be created:

POST /api/dam/search/advanced

{
  "_embedded": {
    "filter": [
      {
        "internalFieldName": "advancedSearchByAttachment",
        "modifier": "CONTAINS_ONE",
        "type": "ATTACHMENTSFIELD",
        "fieldType": "MEDIAFIELD",
        "values": [
          {
            "statuses": [
              "OFFLINE"
            ]
          }
        ]
      },
      {
        "internalFieldName": "advancedSearchByAttachment",
        "modifier": "EMPTY",
        "type": "ATTACHMENTSFIELD",
        "fieldType": "MEDIAFIELD"
      }
    ]
  }
}

4.73.0+

Linked medias filter

Since 4.76.0, it is possible to add a filter related to linked medias.

The the type is MEDIALINKEDFIELD and the fieldType MEDIAFIELD.

The advanced search can then be filtered on elements having at least one linked media (NOT_EMPTY modifier) or no linked media at all (EMPTY modifier).

The "value" field allow filtering on a particular linked media type with NOT_EMPTY modifier. If no specified, search returns medias with at least one linked media.

To filter on elements having at least one linked media, the following advanced search can be created:

POST /api/dam/search/advanced

{
  "_embedded": {
    "filter": [
      {
        "modifier": "NOT_EMPTY",
        "type": "MEDIALINKEDFIELD",
        "fieldType": "MEDIAFIELD"
      }
    ]
  }
}

To filter on elements having no linked media at all:

POST /api/dam/search/advanced

{
  "_embedded": {
    "filter": [
      {
        "modifier": "EMPTY",
        "type": "MEDIALINKEDFIELD",
        "fieldType": "MEDIAFIELD"
      }
    ]
  }
}

And a search with a linked media type :

POST /api/dam/search/advanced

{
  "_embedded": {
    "filter": [
      {
        "modifier": "NOT_EMPTY",
        "type": "MEDIALINKEDFIELD",
        "fieldType": "MEDIAFIELD",
        "value": 1
      }
    ]
  }
}

4.76.0+

Text Filter

Since 4.74.0 it is possible to add a text filter to advanced search.

The internal name to use in searchFullText, the type is SEARCHFULLTEXTFIELD and the field type is MEDIAFIELD

No modifier is necessary for this kind of search.

The value to search is set in the value attribute of the request body.

POST /api/dam/search/advanced

"_embedded": {
    "filter": {
        "internalFieldName": "searchFullText",
        "type": "SEARCHFULLTEXTFIELD",
        "fieldType": "MEDIAFIELD",
        "saveValues": true,
        "values": []
    }
}

4.74.0+

Get advanced search result

As for backoffice-saved advanced searches, results for a temporary advanced search are available through the media resource of the advanced search.

GET http://baobab.keepeek.com/api/dam/search/advanced/ndvcq9vu/media HTTP/1.1

Even if temporary searches might be automatically removed, please be kind on system resources and delete them when they are no longer needed. Send a DELETE request on an advanced search resource.

DELETE /api/dam/search/advanced/ndvcq9vu

4.32.0+

Since 4.84.0 even non-temporary ressources can be deleted.

Articles associés

Commentaires

0 commentaire

Vous devez vous connecter pour laisser un commentaire.