Advanced Search
- 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.
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+
Create an advanced search
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
Delete advanced search
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.