>, Getting Started, Tutorials>Search filters and access & deny codes

Search filters and access & deny codes

This article describes how you can control full text search results, and access to galleries, by use of so called access and deny codes. You may want to use this mechanism to exclude certain content from the searches executed by guests or specific users.

Some examples
  • Certain photos may not be seen by Newspaper X, while other photos may not be seen by Newspaper Y.
  • Hiding photos with adult content from guests (ie not included in search results unless one is logged in).
  • Within a subdomain that you have created for your video files, you want search results to return video content only.
  • You have clients for whom you do commissioned work and when they log in you want search results to return those files only.

Note that there are many other ways to control search results too, you can for instance mark a user as an “Agent” thereby excluding all files that are not available to agents.

Related articles:

Filter codes that the system generates

XS automatically generates a standardised set of filters as described here, but it also allows you to create custom filters. This is described in a separate article.

Based on the properties of a file, XS will automatically generate a number of filter codes. These are used for instance to make it possible to filter using date ranges, by orientation, by rights and so on. You can also create search queries using these codes. For instance to find photos from a specific supplier that were uploaded in a specific month.

Below is an overview of the most important codes that XS will always generate, note that most filters start with an @ sign and end with a # sign to make sure the codes can be uniquely identified as such:

Filter Description Example / Code
UAC Uploaded by user id (v32.14 or later) @UAC2881#
SG Supplier group @SG177#
SUP Supplier (i.e. photographer), Note that @SUP0# will exist if a file is not linked to a supplier @SUP211#
OH,OV,OP,OS Orientation:
Horizontal, Vertical, Panorama, Square
@OH# @OV# @OP# @OS#
CC,CB Color, Black & White @CC# @CB#
HR, LR LR Available as low res only @HR# @LR#
MTI, MTF, MTP, MTD, MTA, MTU Media type:
Image, Footage, PDF, Document, Audio, Unknown
@MTI# @MTF# @MTP# @MTD# @MTA# @MTU#
ITP,ITI Image type Photo or Illustration @ITP# @ITI#
HIDE Exclude from search results @HIDE#
MR,PR Model release, Property release @MR# @PR#
ED,CR Editorial, Commercial/Creative @ED# @CR#
CDR Contributor’s delete request @CDR#
RM,RF Rights managed, Royalty free @RM# @RF#
CY Creation year based on the creation date field in the metadata @CY2015#
UY Upload year @UY2015#
UM Upload month @UM03#
Q Database (upload) date stored as Q-code in the format YYMMDDHH Q13122417Q
U Last update date stored as U-code in the format YYMMDDHH U13122417U
XSMNOK, XSMNOC, XSMNOH Filter codes assigned to find files without keywords, captions and/or headlines @XSMNOK# @XSMNOC# @XSMNOH#
TA*T,TB*T Territory availability codes, where TA codes are used if a file is available in selected countries only, TB if available everywhere except in selected countries, and TAWWT for world wide availability. @TA27T @TB18T @TAWWT
RN0, RN1, RN2 Ranking codes 0,1 and 2 – followed by a number ranging from 0 to 5. E.g. ranking field 1 with a ranking value of 4 is @RN14# @RN02# @RN15# @RN23#

Besides the above codes, there are other filter codes that XS generates for file based restrictions, limiting access and so on.
Note that these are only created for file based properties, not for inherited properties.

Property Description Filter code
NS No syndication @NOSYN#
BX No 3rd party API’s @NOAPI#
BA No agents @NOAGENTS#
PS Available for prints @PRINTS#

Using filter codes in search queries

You can use the filter codes in search queries and you can also use the wildcards that the search engine supports. But, as opposed to using the # sign in the codes that you’re searching for, you can use the question mark (?) wildcard instead. For example:

((flower and spring and not garden) and @sup110?) and (Q1501* or Q1502*)

The above query returns files with the words flower and spring but not also having the word garden from supplier 110 and if uploaded in either January or February 2015.

How does search filtering work?

You can enter so called “access” and “deny” codes in the user account properties. These codes are used to create a Boolean search query that is invisibly added to each search query that the user executes. For example if the user has the access codes ABC,XYZ, each search query will have “and ABC and XYZ” added (note that the user will not see this). If the user then searches for people, the actual query will be “people and ABC and XYZ”, thereby limiting the search results to content that has the word “people” but also the codes ABC and XYZ. Note that multiple codes are separated with commas. You may use only letters, numbers and the characters @ and # in your codes.

The “deny” codes can be used in a similar manner. For example, if you have entered the “deny” codes BLK1,BLK2, then every search query will have “AND NOT BLK1 AND NOT BLK2” added to exclude files that have either code. E.g. the query that is executed when this user searches for people will actually be “people and not BLK1 and not BLK2”.

It is also possible to use both “access” and “deny” codes. E.g. a user has the access code XYZ and the deny code BLK1. Searching for “people” will then become “people and XYZ and not BLK1. So content will be found if it has the word people and the code XYZ and not the code BLK1.

Important
  • The codes that you are filtering for can be in any indexed field. If the code exists in the metadata but not in an indexed field, then it will not work. Normally speaking one would store such codes in a field that is part of the full text index but that is not visible on the client facing pages of your website. You can control which fields are visible via Site configuration, Metada repository. It is advised to use special codes that cannot exist as a normal word in any of the metadata fields. You can automatically create unique codes when your data is being processed by configuring Metadata processing rules.
  • Go to Site configuration and then click Website configuration. The checkbox next to User account codes must be checked for this function to work. You can untick it to temporarily disable search filtering for logged in users, for example if you are having problems with searching and you want to make sure that the problems are not caused by search filters.

Changing the codes for a specific user account

Load the User management page from the administrator menu and locate the user. Click its row to open the user properties dialog. Click the “Permissions” tab and enter the codes. Click the save button to store your changes. Note that if the user is logged in, his or her current session will not be affected by your changes. Such changes are effective from the moment the user logs in the next time. Search filters are not applied to administrator accounts (more about this below).

Default codes for new user accounts

If you use access and deny codes on user accounts, you may want to apply default codes to the accounts of new users too. You can of course change those codes at any time for each user. Go to Site configuration, and click “New user defaults” in the bar on the left.

Codes for guests

If you want to control the search results for guest users, you can specify access and deny codes that you want to use via Site configuration, Website configuration. The codes that you enter here are applied to all search queries by users who are not logged in. Once a user logs in, the guest codes are no longer used and the codes that you have entered in the user’s account properties (if any) are used instead. You can also use this mechanism to control what content guests can see without using such codes for any logged in user.

Limiting what can be searched with the 3rd Party API

If you want to restrict search results when executed by 3rd Party API’s, then find the API user account in User management and open the properties dialog. On the API tab sheet you can enter the access and deny codes. Certain filters are automatically applied to API searches, e.g. the code to exclude files marked as not accessible by API’s.

Staff members

Access and Deny codes are not applied to administrator (staff member) accounts. So even if you enter codes in the user properties of a user who is an admin, those codes will ignored – except for codes that you create for subdomains (which is a separate topic).

Subdomain access and deny codes

You can configure codes to be applied when a user visits your website on one of your subdomains. Such codes are added to already active codes. For example, if you have configured guest access codes via Website configuration and/or codes on a user’s account, and access or deny codes for the subdomain – then all of these codes are active. Note that a combination of codes may be conflicting resulting in users to not find any files at all.

Filtering by use of access and deny codes applies to search queries only

It is important to understand that the above explanation applies to full text search queries. Files that are part of galleries are not retrieved by use of the full text search engine, and as a result certain files may be visible in a gallery even though those files cannot be found by searching. The access and deny codes can however also be used for gallery access control which is explained next.

Gallery access control with access and deny codes

The access and deny codes that are described in this article can also be used to control access to specific galleries (as explained in the previous paragraph, gallery files are not retrieved by use of the full text search engine).

Important! Note that you will have to enable the setting “Use access control” via Site configuration, Gallery pages, General settings. Leave this setting unchecked if you don’t use access control on galleries. This will allow for more efficient caching and faster page generation.

To enable access control for a specific gallery, find the gallery in the Gallery manager (you must have enabled the admin toolbar for this) and click its title to open the gallery properties dialog. Note that if you open the Gallery manager while viewing a gallery on the client facing website, the Gallery manager will show with the correct top level selected which makes it easier to find the gallery. Click the checkbox “use access control” to reveal the additional settings. You can now enter one or more access and/or deny codes. Multiple codes must be separated with commas. If you want galleries to still appear in lists and overviews you can leave the “Hide gallery if no access” unchecked. If a user that has no access to the gallery clicks the title, the page will load and it will display the message “You have no access to this gallery”. If you use access and deny codes for galleries, it’s recommended to use the “Hide gallery if no access” option to prevent such galleries from appearing entirely.

How do the access and deny codes work for the gallery system?

If the user is a guest, then the guest access and deny codes are used or if the user is logged in, then the user’s access and deny codes are used to determine whether or not the user has access to a gallery. For instance if a user has the access codes “XYZ,ABC” and the gallery has an access codes “XYZ,GC1,GC2” then this user can access the gallery. If the user account (or guest account) does not have any of these three codes in his/her account then the gallery cannot be accessed. You can use the deny codes box to enter codes that will prevent users from seeing galleries too. So if a gallery has the deny codes “XYZ,GC1,GC2” then all users can see this gallery unless they have either of these three deny codes active on their account. Note that access to galleries is only limited if you have enabled “access control” on the gallery, if not, the gallery will be accessible to any user.

Disabling guest access to certain galleries

In stead of, or in addition to, using access and deny codes, you can also disable access to specific galleries for guest users by checking the “Users must be logged in” checkbox. Whether or not the gallery is completely hidden is controlled by the setting “Hide gallery if no access” as described in the above paragraphs. If you have not checked this option and a guest clicks a title of a gallery to which he or she has no access, the user will be prompted to log in.
Note that it is also possible to require users to always log in to access any of your galleries. This is a setting that you can find in back office (Site configuration > Gallery pages > General settings.

Setting a password on a gallery

Furthermore, you can password protect specific galleries. In Gallery manager, find the gallery and open its properties. Tick the “Use access control” setting and then tick the “Requires password” checkbox. Enter a password and save the gallery properties.

FAQ

Below are some commonly asked questions about this function
  • I have added a deny code to a user’s account but the search results are not filtered using this code.
  1. Is the user logged in? The codes that you apply on user accounts are only active when that user is logged in.
  2. Make sure that the filter codes actually exist in the photos and that the codes are in one of the indexed fields.
  3. In Site configuration, Website configuration make sure that the setting “User account codes” is checked (on).