Service Manager powered by HEAT

Using the Search Web Method

This web method retrieves one or more business objects satisfying the search criteria. This is a Microsoft SQL-style query. Compared to the other search web methods, this is a general purpose web method that can be used to express arbitrarily complex queries.

Request Syntax

FRSHEATIntegrationSearchResponse Search(string sessionKey, string tenantId, ObjectQueryDefinition query)

Parameters

•sessionKey: The session key from the Connect web method.

•tenantId: The tenant for which the session key is authenticated.

•query: A structure describing the search criteria. It follows the structure of a Microsoft SQL SELECT request and captures most of the possible parameters in SELECT queries, including TOP, WHERE, JOIN, ORDER BY clauses.

Return Value

FRSHEATIntegrationSearchResponse object, defined as follows:

public class FRSHEATIntegrationSearchResponse

    {

public string status { get; set; }

public string exceptionReason { get; set; }

public List<List<WebServiceBusinessObject>> objList { get; set; }

    }

The FRSHEATIntegrationSearchResponse class has the following fields:

•status: Provides a status value indicating whether the operation was successful. A full description of the available status values is provided in the table below.

•exceptionReason: Contains exception information, if the system throws an exception when running the Connect web method.

•objList: Contains a list of the results found, if the value of the status field is success. The outer list contains multiple business objects, if the search condition matched more than one business object. The inner list contains joined business objects if the search condition requested joins. Unlike Microsoft SQL response fields from each joined objects are kept in a separate list, they are not mingled together.

The following table lists the available status values and describes how to interpret them.

Status	Explanation
Success	Successfully found the business objects. Access the business object list from the objList field, which returns the results as a list of WebServiceBusinessObjects.
Error	Cannot find the business objects. The objList field is null.  Inspect the corresponding exceptionReason field to determine why the web method failed.   One typical error is Table not found, which occurs when the specified business object does not exist in the tenant. Ensure that the name of the business object is spelled properly.   Another common error is that the specified field does not exist for the business object. The error message is:   ObjectTableMap: field <FieldName> is not found in table <Business Object>#   Ensure that the field name is spelled correctly, and that it is defined for the given business object.
NotFound	The specified business object exists in the tenant, but the given RecID does not match any of the existing records in the object.   Since this is not an exceptional condition, no exception is stored in the exceptionReason field but the objList field is null. Ensure that the RecID for the intended record exists in the tenant.

Example

The following example searches for incident records where the priority is 1 and the status is active, and retrieves the corresponding incident number values from the matching results.

ObjectQueryDefinition query = new ObjectQueryDefinition();

query.Select = new SelectClass();

// Retrieve just the IncidentNumber field value from the Incident,

// when invoking the search

FieldClass[] incidentFieldObjects = new FieldClass[] {

new FieldClass()

       {

Name = "IncidentNumber",

Type = "Text"

}

};

 

query.Select.Fields = incidentFieldObjects;

query.From = new FromClass();

query.From.Object = "Incident";

 

query.Where = new RuleClass[] {

new RuleClass()

       {

Join = "AND",

              Condition = "=",

              Field = "Priority",

              Value = "1"

},

new RuleClass()

       {

Join = "AND",

              Condition = "=",

              Field = "Status",

              Value = "Active"

}

};

 

FRSHEATIntegrationSearchResponse searchResponse = frSvc.Search(authSessionKey, tenantId, query);

 

if (searchResponse.status == "Success")

{

WebServiceBusinessObject[][] incidentList = searchResponse.objList;

foreach (WebServiceBusinessObject[] incidentOuterList in incidentList)

       {

foreach (WebServiceBusinessObject incident in incidentOuterList)

              {

// Since we are just retrieving one field in the selection criteria

// (i.e. IncidentNumber), this corresponds to

// incident.FieldValues[0].Value when retrieving the results

Console.WriteLine("Incident {0} matches the selection criteria", incident.FieldValues[0].Value);

              }

       }

}