Introduction

To retrieve a well-defined set of records, files or other objects from within Aprimo DAM you can use search expressions. Below are examples of the different syntaxes you can use when searching for objects in Aprimo DAM.

Note: even though the code samples in this section are using the .NET API, the search expressions in them are universal. You can, for example, use the same search expression constructions when using the REST API for custom developent, but also when searching in Aprimo DAM System, in setting values or in references.

You always start with an empty collection of objects, which you fill up using your search expression. All examples below load the search result set in a collection of users that was created before, e.g.:

UserCollection list = new UserCollection(app);

Simple search expressions

The basic syntax of a search expression in Aprimo DAM is:

new SearchExpression("mySearchString");

where mySearchString can be everything from a simple search expression using the object’s properties or field values to a complex search expression combining search criteria with operators, parameters, etc.

The most simple search expression is property=value, which looks for all objects that match the specified property value, e.g. this query will retrieve and load all users whose name is “Administrator”:

list.Load(new SearchExpression("Name = Administrator"));

In case the value of the field or property contains spaces, enclose the value in single or double quotes.

This second query combines 2 search criteria into one search expression: it loads all users whose name starts with an “a” (using the * wildcard) and who were created by a user named “John Doe” (via the CreatedBy property, which in turn contains a user object). Note that the name John Doe is enclosed in single quotes because of the included space:

list.Load(new SearchExpression("Name = a* CreatedBy.Name = 'John Doe'"));

Same query as above, only separated into 2 search expressions (which is slower than the previous one):

list.Load(new SearchExpression(
              new SearchExpression("Name = a*"),
              new SearchExpression("CreatedBy.Name = 'John Doe'")));

You can use square brackets to combine search criteria in underlying objects, e.g. this query looks for all users who were created by a user with the name “Administrator” which also have “ADAM” as Company field value.

list.Load(new SearchExpression("CreatedBy[Name = 'John Doe' AND Company = ADAM]"));

 

Using named and unnamed parameters

To simplify dynamically building search expressions in code, the search expression class also supports searching used named or unnamed parameters.

An unnamed parameter is a parameter that is identified using a question mark (?). These parameters are processed in the same order as they are specified in the search expression. So if you want to use the same value multiple times in an expression, you’ll also have to specify this parameter multiple times.

A named parameter is a parameter that starts with an @, e.g. @Name. Named parameters have the disadvantage that they are slightly more work to specify, but they make it easier to reuse the same parameter value and you can even ask Aprimo DAM to create a list of all the parameters specified in a search expression.

The first example loads all users whose name is “John Doe”, using 1 unnamed parameter:

list.Load(new SearchExpression("Name = ?", new object[] { "John Doe" }));

This example loads all users whose name begins with “a” or “b”, using 2 unnamed parameters:

list.Load(new SearchExpression("Name=? OR Name=?", new object[] { "a*", "b*" }));

This search expression looks for all users whose name or e-mail address is “John Doe”, using a named parameter “Word”:

SearchExpression expression = new SearchExpression("Name = @Word OR Email = @Word");
expression.NamedParameters["Word"] = "John Doe";
list.Load(expression);

This code extracts a list of all the named parameters used in a search expression:

expression = new SearchExpression("Name = @MyName OR Email = @MyEmail");
expression.Parse(app, true);
List parameters = new List(expression.NamedParameters.Keys);

// parameters now contains two items: one with value MyName and one with value MyEmail.

The parameters list now contains 2 items: one with value “MyName” and one with value “MyEmail”.

Working with operators and wildcards

Supported search operators

To define the relationship between the searchable property and the corresponding value, you can use these relational operators:

Operator Description Example
= is equal to
 CreatedBy.Name = "Pete Newcase"
> is greater than or after
 FileCount > 0
>= is greater than or equals
 FileCount >= 1
< is less than or before
 CreatedOn < 05/05/2015
<= is less than or equals
 CreatedOn <= 05/05/2015
<> is not equal to
 File.CheckedOutOn <> 05/05/2015
in matches one of

Use to match the property or field value to one of the listed values

The file count of the record is either 1,3 or 5:

 FileCount in '"1","3","5"'

User was created by Pete, Laura or James:

 CreatedBy.Name in '"Pete","Laura","James"'

Record was created today:

 CreatedOn in today
contains contains

Search through value of the property or field using the full-text index, only available on records and classifications.

Find all records for which the Comment property on a file version contains draft:

 File.Version.Comment contains "draft"

Depending on the data type of the property or field that you use in your search expression, you can use different operators.

Data Type Supported Operators
String =   >   >=   <   <=   <>   contains* in
Date/Time =   >   >=   <   <=   <>   in
(only the keyword today is supported with the in operator)
Guid =   <>   in
Numeric =   >   >=   <   <=   <> in
Boolean =   <>

*: the contains operator searches the full-text index, which means it’s only supported on full-text indexed objects: records and classifications.

 

Combining search expressions

A search expression can contain the following logical search operators: AND, OR, NOT and parentheses. An AND can also be replaced by a plus sign and a NOT by a minus sign. You can use these search operators to combine separate search expressions into a single complex expression. Just as you would combine search terms using logical operators, you can do the same for search expressions.

Aprimo DAM supports these logical operators:

Operator Used to …
AND (+) combine search expressions, search results must match both expressions
OR combine search expressions, search results must match either expression
NOT (-) combine search expressions, search results must match expression before operator but NOT the expression after the operator

In case you don’t write a correct search expression, Aprimo DAM will attempt to correct any faults in the specified expression, e.g. every time an operator is missing, Aprimo DAM will automatically use the operator specified in DefaultBooleanOperator, but you can make Aprimo DAM use another operator by using the BooleanOperatorType parameter. This makes your search expression syntax look like this:

list.Load(new SearchExpression(
    "mySearchString",
    null, // Set the parameters argument to null in case you don't use parameters
    BooleanOperatorType.And|Or|Not));

By default Aprimo DAM uses AND.

The following example makes Aprimo DAM use OR instead, looking for all users whose name begins with “a” or “b”:

list.Load(new SearchExpression("Name=? Name=?", new object[] { "a*", "b*" },
                               BooleanOperatorType.Or, true, null));

You can also use the IN operator. The following sample loads all users whose ID matches one of the IDs in the list, using the IN operator:

List ids = new List();
ids.Add(new Guid("117c5ef4-5505-435e-818f-0495ea434a8c"));
ids.Add(new Guid("2fa2ba22-8ae0-481b-a4fe-1d4c0edab6e3"));
ids.Add(new Guid("503dfa3a-debc-4add-96cf-da4d62feb13a"));

expression = new SearchExpression("Id IN ?", new object[] { ids });
list.Load(expression);

Wildcards

An * (asterisk) in a search expression is interpreted as a wildcard. This example looks for all users whose name starts with an “a”:

list.Load(new SearchExpression("Name = a*"));

You could however disable the use of wildcards by setting the supportWildcards argument in the constructor (which corresponds to the SupportWildcards property) of the search expression to false.

The example below will load all users whose name is literally equal to “a*” :

list.Load(new SearchExpression(
    "Name = a*", 
    null, 
    BooleanOperatorType.And,
    false, // supportWildcards: when set to false wildcards are treated as regular characters 
    null));