Searching for Records

the frs heat integration web service provides several means to search for records in a given tenant the following table summarizes the four web methods providing for searching records webmethod applicability search general purpose method for searching for records, using an arbitrary query criteria use this webmethod, if the other three available convenience webmethods mentioned below, cannot be used to express the desired query criteria findbusinessobject search for the business object record, by means of its recid field value in the database since records are uniquely identified by the recid (i e the primary key), this web method will return exactly one record, assuming the provided recid does match one of the existing records in the business object if the recid of the record to search for is not readily available, then the other webmethods should alternatively be used findsinglebusinessobjectbyfield search for the business object record, by means of the provided field / value criteria, and return the exact record match, if it can be found for example, this webmethod can be used to identify a profile employee record, by means of either the loginid or primaryemail field (assuming the field values for the column is unique in the database table) as the name suggests, this web method will return exactly one matching record, if it can be located note that if the search returns multiple records, it will not return any results if you are unsure of whether multiple results will be returned, use either the findmultiplebusinessobjectsbyfield or findbusinessobject web methods, as an alternative findmultiplebusinessobjectsbyfield search for the business object record, by means of the provided field / value criteria, and return all of the results in an array for example, this webmethod can be used to identify all incident records with a status of “resolved” as the name suggests, this web method will return one or more matching results via an array if it is known beforehand that the search criteria will return exactly one record, the findsinglebusinessobjectbyfield web method provides a more convenient way of accessing the record directly otherwise the findmultiplebusinessobjecsbyfieldwebmethod can still be used, where the record can be retrieved via the first item in the array from the above table, it can be seen that the findbusinessobject , findsinglebusinessobjectbyfield , and findmultiplebusinessobjectsbyfield web methods are all special cases of the search webmethod – the latter web method can be used to express any arbitrarily complex query the following sections will describe the four query web methods in further detail findbusinessobject retrieves a single business object using its primary identifier (recid field in the database) request syntax frsheatintegrationfindboresponse findbusinessobject(string sessionkey, string tenantid, string botype, string recid) parameters sessionkey key received in the earlier connect request tenantid tenant for which the key is authenticated botype type of the business object to retrieve, for example incident or change recid unique identifier for the object return value an frsheatintegrationfindboresponse object, defined as follows public class frsheatintegrationfindboresponse { public string status { get; set; } public string exceptionreason { get; set; } public webservicebusinessobject obj { get; set; } } the frsheatintegrationfindboresponse class comprises the following fields status – this field 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 – if there is an exception thrown in the course of running the connect webmethod, the exception information will be captured in this field obj – if the exact record can be found via the findbusinessobject webmethod call (i e the value of the status field is “success”), the business object record can be accessed via this field the following table lists the available status values, and describes how to interpret them status explanation success the business object can be successfully found – access the record via the obj field in the response object error the business object cannot be successfully found – the obj field will be null, and the exception will be stored in the exceptionreason field the most typical error is the table not found exception, which occurs when the specified business object does not exist in the tenant double check to make sure that the name of the business object is spelled properly (e g “incident”, “profile employee”, etc ) notfound the specified business object does exist in the tenant, but the provided recid value does not match any of the existing records in the object since this is not an exceptional condition, there will not be an exception stored in the exceptionreason field, and the obj field will be null double check to make sure the recid field for the intended record does in fact exist in the tenant an alternate query web method (e g “findsinglebusinessobjectbyfield”) might be alternatively used for retrieving the record example frsheatintegrationfindboresponse res = frsvc findbusinessobject(authsessionkey, tenantid, "incident", "a981fbebaa8b4ee2820364505855abc2"); if (res status == "success") { foreach (webservicefieldvalue f in res obj fieldvalues) { if (string compare(f name, "lastmoddatetime", true) == 0) { datetime lastmod; if (f value != null) { lastmod = (datetime)f value; console writeline("the lastmoddatetime of the record is " + lastmod tostring()); } } } } findsinglebusinessobjectbyfield this web method retrieves a single business object, by means of the specified field / value criteria this is a convenience web method introduced for searching for a matching record, by means of a unique field here are some common use cases, where this query web method can come in handy search for a specific profile employee record, by means of the loginid field search for a specific profile employee record, by means of the primaryemail field search for a specific standarduserteam record, by means of the team field search for a specific organizationalunit record, by means of the name field request syntax frsheatintegrationfindboresponse findsinglebusinessobjectbyfield(string sessionkey, string tenantid, string botype, string fieldname, string fieldvalue) parameters sessionkey key received in the earlier connect request tenantid tenant for which the key is authenticated botype type of the business object to retrieve, for example incident or change recid unique identifier for the object fieldname the name of the field in the business object, to search against (e g “status”) fieldvalue the value for the field to search for in the matching record (e g “active”) return value an frsheatintegrationfindboresponse object, defined as follows public class frsheatintegrationfindboresponse { public string status { get; set; } public string exceptionreason { get; set; } public webservicebusinessobject obj { get; set; } } the frsheatintegrationfindboresponse class comprises the following fields status – this field 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 – if there is an exception thrown in the course of running the connect webmethod, the exception information will be captured in this field obj – if the exact record can be found via the findbusinessobject webmethod call (i e the value of the status field is “success”), the business object record can be accessed via this field the following table lists the available status values, and describes how to interpret them status explanation success the business object can be successfully found – access the record via the obj field in the response object error the business object cannot be successfully found – the obj field will be null, and the exception will be stored in the exceptionreason field one typical error is the table not found exception, which occurs when the specified business object does not exist in the tenant double check to make sure that the name of the business object is spelled properly (e g “incident”, “profile employee”, etc ) the other common error encountered, is when the specified field does not exist for the business object – here, the error message would be of the form objecttablemap field \<fieldname> is not found in table \<business object># double check to make sure that the field name is spelled correctly, and is actually defined for the given business object notfound the specified business object does exist in the tenant, but the provided recid value does not match any of the existing records in the object since this is not an exceptional condition, there will not be an exception stored in the exceptionreason field, and the obj field will be null double check to make sure the fieldvalue field for the intended record does in fact exist in the tenant an alternate query web method (e g “findsinglebusinessobjectbyfield”) might be used for retrieving the record multipleresults the provided search criteria returned more than one matching result since the intent of this webmethod is to return a single matching business object, the obj field in the response object will remain null, whenever the status of the response object is “multipleresults” if there is a possibility for returning multiple matching results, the “findsinglebusinessobjectbyfield” web method should be used instead example frsheatintegrationfindboresponse res = frsvc findsinglebusinessobjectbyfield(authsessionkey, tenantid, "incident", "incidentnumber", "10001"); if (res status == "success") { foreach (webservicefieldvalue f in res obj fieldvalues) { if (string compare(f name, "lastmoddatetime", true) == 0) { datetime lastmod; if (f value != null) { lastmod = (datetime)f value; console writeline("the lastmoddatetime of the record is " + lastmod tostring()); } } } } findmultiplebusinessobjectsbyfield this web method retrieves one or more business objects, by means of the specified field / value criteria, and returns the result as an array of business objects for example, this web method can be used to retrieve all incident records with status of “active”, all changes with type of “major”, etc this web method only allows for searches based on a single field / value criteria – if more complex queries need to be expressed, the search web method should be used instead also, this web method will always return the results in an array, even if there is exactly one matching record returned in that case, the findsinglebusinessobjectbyfield web method might be more convenient to use, if the desired query criteria will return exactly one record request syntax frsheatintegrationsearchresponse findmultiplebusinessobjectsbyfield(string sessionkey, string tenantid, string botype, string fieldname, string fieldvalue) parameters sessionkey key received in the earlier connect request tenantid tenant for which the key is authenticated botype type of the business object to retrieve, for example incident or change recid unique identifier for the object fieldname the name of the field in the business object, to search against (e g “status”) fieldvalue the value for the field to search for the matching record (e g “active”) return value a 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 comprises the following fields status – this field 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 – if there is an exception thrown in the course of running the connect webmethod, the exception information will be captured in this field objlist – if one or more records can be found via the webmethod call (i e the value of the status field is “success”), the results will be returned via this field, which is a list of lists of webservicebusinessobject objects the outer list contains multiple business objects, if the search condition matched more than one object the inner list contains joined business objects if the search condition requested joins unlike 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 the business objects can be successfully found – access the matching records via the objlist field in the response object, which returns the results as a list of list of webservicebusinessobjects error the business objects cannot be successfully found – the objlist field will be null, and the exception will be stored in the exceptionreason field one typical error is the table not found exception, which occurs when the specified business object does not exist in the tenant double check to make sure that the name of the business object is spelled properly (e g “incident”, “profile employee”, etc ) the other common error encountered, is when the specified field does not exist for the business object – here, the error message would be of the form objecttablemap field \<fieldname> is not found in table \<business object># double check to make sure that the field name is spelled correctly, and is actually defined for the given business object notfound the specified business object does exist in the tenant, but the provided recid value does not match any of the existing records in the object since this is not an exceptional condition, there will not be an exception stored in the exceptionreason field, and the objlist field will be null double check to make sure the fieldvalue for the intended records does in fact exist in the tenant example frsheatintegrationsearchresponse res = frsvc findmultiplebusinessobjectsbyfield(authsessionkey, tenantid, "incident", "status", "active"); if (res status == "success") { webservicebusinessobject\[]\[] incidentlist = res objlist; foreach (webservicebusinessobject\[] incidentouterlist in incidentlist) { foreach (webservicebusinessobject incident in incidentouterlist) { webservicefieldvalue\[] incidentfieldlist = incident fieldvalues; webservicefieldvalue incidentnumberfield = incidentfieldlist singleordefault(f => f name == "incidentnumber"); console writeline("incident matches the selection criteria", incidentnumberfield value); } } } search this web method retrieves one or more business objects satisfying the search criteria this is an sql style query compared to the earlier three query web methods, this is a general purpose web method which can be used to express arbitrarily complex queries request syntax frsheatintegrationsearchresponse search(string sessionkey, string tenantid, objectquerydefinition query) parameters sessionkey key received in the earlier connect request tenantid tenant for which the key is authenticated query a structure describing the search criteria it follows the structure of a sql select request and captures most of the possible parameters in select queries, including top, where, join, order by clauses return value an 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 comprises the following fields status – this field 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 – if there is an exception thrown in the course of running the connect webmethod, the exception information will be captured in this field objlist – if one or more records can be found via the webmethod call (i e the value of the status field is “success”), the results will be returned via this field, which is a list of lists of webservicebusinessobject objects the outer list contains multiple business objects, if the search condition matched more than one object the inner list contains joined business objects if the search condition requested joins unlike 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 the business objects can be successfully found – access the matching records via the objlist field in the response object, which returns the results as a list of list of webservicebusinessobjects error the business objects cannot be successfully found – the objlist field will be null, and the exception will be stored in the exceptionreason field one typical error is the table not found exception, which occurs when the specified business object does not exist in the tenant double check to make sure that the name of the business object is spelled properly (e g “incident”, “profile employee”, etc ) the other common error encountered, is when the specified field does not exist for the business object – here, the error message would be of the form objecttablemap field \<fieldname> is not found in table \<business object># double check to make sure that the field name is spelled correctly, and is actually defined for the given business object notfound the specified business object does exist in the tenant, but the provided recid value does not match any of the existing records in the object since this is not an exceptional condition, there will not be an exception stored in the exceptionreason field, and the objlist field will be null double check to make sure the fieldvalue for the intended records does in fact exist in the tenant example the following example will search for incident records where the priority is equal to 1, and the status is equal to “active”, and retrieves the corresponding incidentnumber 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 matches the selection criteria", incident fieldvalues\[0] value); } } }