Using fields when searching for records and classifications

Introduction

In Aprimo DAM most of your metadata on records, classifications, users and indexers is stored in various fields. This also means that you can use the values and/or properties of these fields in search expressions to find the objects you need.

Because of the difference in indexing of the various object types in Aprimo DAM Enterprise search, there are some differences in using fields in search expressions as well, depending on what you are searching for. This topic explains how to use fields when searching for records and classifications.

Basic guidelines

There is a slight difference between which fields and corresponding properties are available when searching for records and searching for classifications.

You can search for classifications based on:

  • The value of a simple field attached to a directly related classification or the classification itself
  • The ID of a record, language, user group or classification listed in a record list field, language list field, user group list field or classification list field attached to the classification itself
  • The ID, name or email of a user listed in a user list field attached to the classification itself

You can search for records based on:

  • The ID of the user who:
    • created/modified a record linked through a record list or record link field
    • Checked out a file on a record linked through a record list or record link field
  • A simple searchable property on:
    • on a record linked through a record list or record link field
    • a file or file version on a record linked through a record list or record link field
  • The value of a simple field attached to:
    • the record itself
    • a record linked through a record list or record link field
    • a file on the record itself
    • a file on a record linked through a record list or record link field
  • The ID, name or email of a user listed in a user list field attached to a file on the record or to the record itself
  • The ID of a language, user group or classification listed in a language list field, user group list field or classification list field attached to a file on the record or to the record itself
  • The ID of a record listed in a record list field attached to a file on the record

Syntax

To use fields when searching for records or classifications you can specify the field by its Id, Name or Label. Use any of these search expression formats:

Field identification Syntax Comment
Field Id
 FieldId("[TheFieldId]")[.property] = value
The advantage of using the field Id is that the Id is fixed and will never change.
Field name
 FieldName("[TheFieldName]")[.property] = value
Using the field name instead of the Id makes the search expression easier to read.
Field label
 FieldLabel("[TheFieldLabel]")[.property] = value
Using the field label is not recommended, because the language that will be used for searching depends on the user executing the code or search expression (current user). Search expressions with field labels are typically used by actual users, when searching in Aprimo DAM Assets or System.

Simple vs complex field data types

In Aprimo DAM there are simple field types, which contain a single or scalar value, e.g. a text or date field, and complex field types, which contain a reference to another Aprimo DAM object, e.g. a RecordLink or ClassificationList field.

The available properties you can use in a search expression depend on the type of field. Which properties are available for each of the field data types is listed in the two tables below:

  • Searchable properties for simple field data types: text, numeric, duration, datetime, dynamic option list fields and option list fields
  • Searchable properties for complex field data types: record link, record list, classification list, language list, user list and user group list fields

Searchable properties for simple field data types

DateTime, DynamicOptionList and OptionList fields give you some additional properties to use in search, but for most simple field data types there is only one property you can search: Value, which contains the field value. This is also the default property, which is the property that is searched if you don’t specify any, e.g.

the complete search expression to search for all records where the BrandName field contains “ADAM” is

 FieldName("BrandName").Value = "ADAM"

but you can also use

 FieldName("BrandName") = "ADAM"

which will give you the same results.

These are the available searchable properties for the simple field data types:

Field data type Property Type Description
Text Value String Search for all items where the specified field contains the specified value.

Example: find all records or classifications where the value of the text field Status is “Draft”

 FieldName("Status").Value = "Draft"
Numeric Value Number Search for all items where the specified field contains the specified value.

Example: find all records or classifications where the value of the numeric field BasePrice is above 100

 FieldName("BasePrice").Value > 100
Duration Value Number Search for all items where the specified field contains the specified value.

Example: find all records or classifications where the value of the duration field TotalLength is less than 1.5 hour

 FieldName("TotalLength").Value < "1:30:00"
Date Value Datetime Search for all items where the specified field contains the specified value.

Example: find all records or classifications where the value of the date field ExpirationDate is before Jan. 1st, 2000:

 FieldName("ExpirationDate").Value = "01/01/2000"

Be aware that the pattern in which to specify the datetime value depends on the patterns that were specified in the field definition itself.

Time Value Datetime Search for all items where the specified field contains the specified value.

Example: find all records or classifications where the value of the time field WarningTime is 8 AM:

 FieldName("WarningTime").Value = "08:00:00 AM"

Be aware that the pattern in which to specify the datetime value depends on the patterns that were specified in the field definition itself.

DateTime Value

UtcValue

Datetime Search for all items where the specified field contains the specified value.

The (default) Value property refers to the field value in the time zone of the Aprimo DAM server, but you can also search the datetime value in UTC time with the UtcValue property.

Examples:

Search for items where the expiration datetime stored in the field ExpiresOn is before Jan 1st, 2000 8 AM, where time is in the Aprimo DAM server’s time zone:

 FieldName("ExpiresOn").Value = "01/01/2000 08:00:00 AM"

Search for items where the expiration datetime stored in the field ExpiresOn is before Jan 1st, 2000 8 AM, where time is in UTC time:

 FieldName("ExpiresOn").UtcValue = "01/01/2000 08:00:00 AM"

Be aware that the pattern in which to specify the datetime value depends on the patterns that were specified in the field definition itself.

See the ADAM Administrator Guide > Basics & Architecture > Fields > Creating field definitions > Data type specific: DateTime for more information.

DynamicOptionList Key

Value

String Search for all items where the specified option is selected in the specified field.

In this field type Key is the default property, not Value!

Example: find all items where the key of the selected option in the DynamicOptionList field Department is “Marketing”

 FieldName("Department").Key = "Marketing"
OptionList Option

Id

Label

Option

Guid

String

A OptionList field contains a list of options. You can search for items by using the properties of the options that were selected in that field.

See Option search properties below for the complete list of search properties on options.

Example:

find all items where the option Draft was selected in the option list field Status:

 FieldName("Status").Option.Name = "Draft"

You can use the Id and Label properties to directly get to the option id or label, e.g.:

 FieldName("Status").Id= "381f76b9-a44d-433b-a1e3-a4bf00e31516"

Searchable properties for complex field data types

A complex field is a field that contains nested objects, e.g. a UserList field contains a list of users, a RecordLink field contains links to other records. When you use a complex field in a search expression, you can use the properties and fields of these nested objects to find what you need, e.g.

 FieldName("RelatedProducts").Record.FileCount > 0

will get you all records that have a linked record with at least one file in the RelatedProducts RecordList field.

Which properties are available depends on the field’s data type and also the configuration of search levels in Aprimo DAM.

See the ADAM Administrator Guide > Search configuration > Search behavior configuration for more information.

The complex field types and their search properties are listed in the table below:

Field data type Property Type Comments
ClassificationList Classification.Id

ClassificationId

Guid A ClassificationList field contains a list of classifications. You can search for items by using the Id of the classifications that were selected in that field.

Example:

find all items where the classification list field RelatedClassifications contains the classification with the specified Id:

 FieldName("SecondaryClassifications").Classification.Id = 
      "381f76b9-a44d-433b-a1e3-a4bf00e31516"

You could also use the ClassificationId property as a shortcut to directly get to the classification id:

 FieldName("SecondaryClassifications").ClassificationId = 
      "381f76b9-a44d-433b-a1e3-a4bf00e31516"
LanguageList Language.Id Guid A LanguageList field contains a list of languages. You can search for items by using the Id of the languages that were selected in that field.

Example:

find all items where the LanguageList field EnabledLanguagess contains the language with the specified Id:

 FieldName("EnabledLanguages").Language.Id = "381f76b9-a44d-433b-a1e3-a4bf00e31516"
RecordList Record

RecordId

Record

Guid

A RecordList field contains a list of records. You can search for items by using the Id of the records that were selected in that field. If the Allow searching on nested properties and fields option is enabled on the field you can also use the properties and simple field values of the selected records in the field. Searching using complex field data types attached to the linked record is not supported.

See Searching for records for the complete list of search properties on records.

If you are using a RecordList field on a classification or file in your search, you can only use the Id of the record.

Example:

find all items where the RecordList field RelatedProducts contains the record with at least one file:

 FieldName("RelatedProducts").Record.FileCount > 0

You could also use the RecordId property as a shortcut to directly get to the record id:

 FieldName("RelatedProducts").RecordId = 
      "381f76b9-a44d-433b-a1e3-a4bf00e31516"
RecordLink Child.Record

Parent.Record

Link.Record

Record A RecordLink field contains a list of records that are linked in a certain relationship (parent-child or flat – see the ADAM Administrator Guide > Basics & Architecture > Fields for more information). You can search for items by using the Id of the linked records in that field. If the Allow searching on nested properties and fields option is enabled on the field you can also use the properties and simple field values of the selected records in the field. Searching using complex field data types attached to the linked record is not supported.

See Searching for records for the complete list of search properties on records.

Example:

find all items where the RecordLink field LinkedImages contains a child link to the record with the specified Id:

 FieldName("LinkedImages").Child.Record.Id = 
      "381f76b9-a44d-433b-a1e3-a4bf00e31516"
UserList User User A UserList field contains a list of users. You can search for items by using the properties of the users that were selected in that field.

See Searching for records – user properties for the complete list of search properties on users.

Example:

find all items where the UserList field Owners contains a user with the name Pete Newcase:

 FieldName("Owners").User.Name = "Pete Newcase"
UserGroupList UserGroup.Id Guid A UserGroupList field contains a list of user groups. You can search for items by using the Id of the user groups that were selected in that field.

Example:

find all items where the UserGroup list field ManagingRoles contains a user group with the specified Id:

 FieldName("ManagingRoles").UserGroup.Id= 
      "381f76b9-a44d-433b-a1e3-a4bf00e31516"

Option search properties

An OptionList field contains a list of selected options. To search in this list you can use the following option properties:

Property Type Examples
Id Guid Search for items where the option list field Colors contains the option with the specified Id:

 FieldName("Colors").Option.Id = "381f76b9-a44d-433b-a1e3-a4bf00e31516"

This is the default property, so you could also use this shorthand expression to get the same results:

 FieldName("Colors") = "381f76b9-a44d-433b-a1e3-a4bf00e31516"
Name String Search for items where the option list field Colors contains the option with the name LBlue:

 FieldName("Colors").Option.Name = "LBlue"
Label String Search for items where the option list field Colors contains the option with the label Light blue:

 FieldName("Colors").Option.Label = "Light blue"

Note that using the label in code is not recommended, because the language that will be used for searching depends on the user executing the code (current user).

SortIndex Numeric Search for items where the option list field Colors contains the option with sort index 1:

 FieldName("Colors").Option.SortIndex = 1