An object that holds information about an individual search parameter to use with the Search method. Allows client to restrict returned results to specific criteria.

Fields

FieldName

The LmsObject property the client wishes to query on. The FieldName string will always match the names of the LmsObject's properties. For LmsPersonObject, this might be 'FirstName', 'LastName', etc.

Operation

The search operator used when comparing the value of the specified field with the search term(s). The 'greater' and 'lesser' operators are not restricted to numeric searches and may be used on strings to compare alphabetical order.

SearchTerm

The string to perform the search against. Wild cards in the string may or may not be interpreted depending on the operator in use. SearchTerm is ignored for searches using the contains operator.

ContainsSearchTerms

The required list of values that the specified field array must contain in order to be returned in the result set. Objects containing more values than specified in the ContainsSearchTerms list are also returned as long as the contain the terms being searched for. Only applicable when using the contains operator.

Usage

A client application must instantiate an LmsSearchParam object for each search parameter to be specified. The client must pass in the FieldName they would like to search on, the operator they would like to use, and a string value that they would like to search against. This string may include wild card characters depending on the search operator being used. When searching using the contains operator, client applications must pass the array of search strings (ContainsSearchTerms) rather than a single value (SearchTerm). See below for details.

The following searchOperator strings are permissible:

• 'equals'
• 'unequals'
• 'like' (supports wild card characters)
• 'greater'
• 'geq'
• 'lesser'
• 'leq'
• 'contains' (only allowed on certain properties, must include an array of search values)

As indicated, only the 'like' operator supports wild card characters at the time of writing. The contains operator requires client applications to pass the ContainsSearchTerms array.

Wild Cards

The SearchTerm argument can contain zero or more of the following wild cards:

• %
• ?

The % wild card will match an indefinite number of characters (ungreedily). The ? wild card will match only one character. A literal % or ? can be included by escaping it with a backslash. A literal backslash can be included by escaping it with an additional backslash.

All wild card and escape-sequence substitutions will be performed only if the searchOperator supports it. In this case, this will only happen when the 'like' operator is being used. When using other operators, special characters such as % and ? need not be escaped.

All wild cards will match punctuation characters, notably the asterisk and the question mark.

Contains Operator

The contains operator is used to search fields that can contain multiple values. When searching using the contains operator, records with the specified field having all of the terms listed in the ContainsSearchTerms array are returned. The property specified by FieldName must allow searching using the contains operator, see the object's field documentation.

One such example is the property LmsItemObject.Activity.Tags. Using the contains operator, a client application can search for all items tagged as 'Course 101' and 'Post-Test'. Using multiple LmsSearchParam objects and a logical operation of OR, subsets can be combined.

Rules and Guidelines:

Permissions

As always the client must be authenticated with the web service as a user with sufficient privileges to view the data that the client expects to be returned.

The returned result set will always be a subset (never a superset) to that returned if the Search method had been invoked with no search parameters.

Case

All searches will be done in a case insensitive manner. This includes using the 'greater' and 'lesser' operators against string searches. For example, the expressions 'hello' > 'helloThere', 'meToo' < 'metoo', 'fun' > 'Joy' will all evaluate to FALSE.

Sample Code

Examples

LmsSearchParam[] mySearchParams = new Array[2];

// Only search for activties
mySearchParams[0] = new LmsSearchParam();
mySearchParams[0].FieldName = "IsActivity";
mySearchParams[0].Operation = SearchParamOperator.equals;
mySearchParams[0].SearchTerm = "true";

// That are tagged as course 101 post-tests
mySearchParams[1] = new LmsSearchParam();
mySearchParams[1].FieldName = "Activity.Tags";
mySearchParams[1].Operation = SearchParamOperator.contains;
mySearchParams[1].ContainsSearchTerms = new string[] { "Post-Test", "Course 101" } ;

// perform the search
SearchResult mySearchResult = lmsBinding.Search('MYLICENSEEID', 'LmsItemObject', mySearchParams, LogicalOperator.and);