Using the CreateObject Web Method

this web method creates a new instance of a single business object and may also establish relationships with other objects it runs initialization rules first, then applies the supplied values to the fields and invokes autofill, calculated, save and business rules in the same way, if the object was being created interactively via user interface validation rules are also executed and they might prevent the saving operation, if the resulting object field values do not pass the validation this web method initializes fields in the order provided request syntax frsheatintegrationcreateboresponse createobject(string sessionkey, string tenantid, objectcommanddata commanddata) parameters sessionkey the session key from the connect web method tenantid the tenant for which the session key is authenticated commanddata a structure containing information about the creation request public class objectcommanddata { public string objectid; public string objecttype; public list\<objectcommanddatafieldvalue> fields; public list\<linkentry> linktoexistent; } objectid the recid of the object to be created objecttype the type of the object to be created fieldvalues a list of name value pairs that contain the field names and new values for the fields of the business object that should be populated linktoexistent references the linkentry class, which controls whether relationships between this object and other objects should be established public class linkentry { public string action; public string relation; public string relatedobjecttype; public string relationshipname; public string relatedobjectid; public list\<searchcondition> searchcriteria; } the linkentry class has the following fields action determines whether this object should be linked with the other objects the value can be either link or unlink, but only "link" is meaningful in createobject operation relation the relationship tag (shown as the internal reference name in the configuration console) for the relationship type to be established relationshipname the relationship name (shown as the display name in configuration console) for the relationship type to be established relatedobjecttype the type of the business object in an object reference notation to be linked with relatedobjectid (optional the class must have either the relatedobjectid or searchcriteria field ) the recid of the business object to be linked or unlinked searchcriteria (optional the class must have either the relatedobjectid or searchcriteria field ) a list of structures defining search criteria for matching objects that have to be linked with this object public class searchcondition { public string objectid; public string objectdisplay; public string joinrule; public string condition; public searchconditiontype conditiontype; public string fieldname; public string fielddisplay; public string fieldalias; public string fieldtype; public string fieldvalue; public string fieldvaluedisplay; public string fieldvaluebehavior; public string fieldstartvalue; public string fieldendvalue; public list\<searchcondition> subquery; } objectid the recid of the object to match objectdisplay no definition present joinrule determines how individual search criteria combine together possible values are "and" and "or" condition describes how the field value should be matched possible values are listed below operator meaning = equal to != not equal to > greater than < less than >= greater than or equal to <= less than or equal to > begin with {} contains !{} does not contain 0 is empty !0 is not empty () in list !() not in list >< in range conditiontype controls how text fields are searched can be 0 (uses regular microsoft sql field search \[sql like, contains clauses]) or 1 (uses full text microsoft sql field search) fieldname field name fieldvalue field value fieldvaluebehavior either single or list fieldstartvalue start value for "in range" condition only fieldendvalue end value for "in range" condition only return value frsheatintegrationcreateboresponse object, defined as follows public class frsheatintegrationcreateboresponse { public string status { get; set; } public string exceptionreason { get; set; } public string recid { get; set; } public webservicebusinessobject obj { get; set; } } the frsheatintegrationcreateboresponse class has the following fields status contains a status indicating whether the web method was successful the table below contains a full description of the available status values exceptionreason contains exception information, if the application throws an exception when running this web method recid the rec id of the newly created record obj returns the updated record as an webservicebusinessobject object, if the business object record is updated successfully the following table lists the available status values and describes how to interpret them status explanation success created the business object successfully the recid field of the response object contains the recid of the newly created record the obj field references the newly created webservicebusinessobject error cannot create the business object the recid and obj fields are null inspect the corresponding exceptionreason field to determine why the web method has 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 specified business object another common error is to specify a value for a field that does not exist in the associated validation list the error message is \<businessobject> \<field> `\<fieldvalue>` is not in the validation list to specify datetime values, specify the string value using iso 8601 format the value must be relative to utc the datetime value can be specified in one of the following two ways yyyy mm dd hh\ mm yyyy mm ddthh\ mm use either a space character or "t" character to separate the date and time values the following are two examples of specifying a datetime value of march 26th, 2013, 18 38 utc, relative to the above two formats 2013 03 26 18 38 2013 03 26 t 18 38 example the following example first creates a brand new change record with specific field values, then locates an existing ci computer record, using the search web method, and links the two records together using the createobject web method objectcommanddata data = new objectcommanddata(); data objecttype = "change#"; list\<objectcommanddatafieldvalue> datafields = new list\<objectcommanddatafieldvalue>(); dictionary\<string, object> fields = new dictionary\<string, object>(); fields\["requestorlink"] = "fb884d18f7b746a0992880f2dffe749c"; fields\["subject"] = "need to swap out the hard disk"; fields\["description"] = "the hard drive just crashed need to replace with a new drive from the vendor"; fields\["status"] = "logged"; fields\["typeofchange"] = "major"; fields\["ownerteam"] = "operations"; fields\["owner"] = "admin"; fields\["impact"] = "medium"; fields\["urgency"] = "medium"; fields\["cabvoteexpirationdatetime"] = "2013 03 26 18 38 30 "; foreach (string key in fields keys) { datafields add(new objectcommanddatafieldvalue() { name = key, value = fields\[key] tostring() }); } data fields = datafields toarray(); // here we will identify a ci computer record, to link to the // new change record // for this example, we will attempt to locate the ci computer record // with the name of "apac depot serv01", and retrieve its recid objectquerydefinition ciquery = new objectquerydefinition(); // just retrieve only the recid field for the ci computer record fieldclass\[] cifieldobjects = new fieldclass\[] { new fieldclass() { name = "recid", type = "text" } }; ciquery select = new selectclass(); ciquery select fields = cifieldobjects; ciquery from = new fromclass(); // search for the record against the ci computer member object ciquery from object = "ci computer"; ciquery where = new ruleclass\[] { // provide the criteria to search for the ci computer // here, we will search for the ci computer by its name new ruleclass() { condition = "=", field = "name", value = "apac depot serv01" } }; // pass in the objectquerydefinition for the query frsheatintegrationsearchresponse searchresponse = frsvc search(authsessionkey, tenantid, ciquery); webservicebusinessobject\[]\[] cilist = searchresponse objlist; // assuming that the ci record is uniquely identified by its name, and // because the above query does not join with other tables, we should be // able to locate the ci record, by accessing cilist\[0]\[0], in the // list of list of webservicebusinessobjects webservicebusinessobject ci = cilist\[0]\[0]; string cirecid = ci recid; // define the linkentry record, to link the new change record to the ci // record, by means of the recid of the change (i e cirecid), as // determined above data linktoexistent = new linkentry\[] { new linkentry() { action = "link", relation = "", relatedobjecttype = "ci#", relatedobjectid = cirecid } }; // if the record creation succeeds, the result variable will store the // recid of the new change record, otherwise it will be null frsheatintegrationcreateboresponse result = frsvc createobject(authsessionkey, tenantid, data); if (result status == "success") { console writeline("a new change record is created with recid of ", result recid); } the next example creates a new profile employee record and links the user to the respective roles and teams notice that the password value is specified in plain text; it is automatically converted to the internal hashed value when you save the record objectcommanddata data = new objectcommanddata(); data objecttype = "profile#employee"; list\<objectcommanddatafieldvalue> datafields = new list\<objectcommanddatafieldvalue>(); dictionary\<string, object> fields = new dictionary\<string, object>(); fields\["status"] = "active"; fields\["firstname"] = "brian"; fields\["lastname"] = "wilson"; fields\["loginid"] = "bwilson"; fields\["isinternalauth"] = true; // notice when setting the password for the employee, that the plain text // password is specified here it will be converted to the hashed value // upon save of the record fields\["internalauthpasswd"] = "manage1t"; fields\["primaryemail"] = " bwilson\@example com "; fields\["phone1"] = "14158665309"; // recid for the "admin" user, to serve as the manager for the new employee fields\["managerlink"] = "fb884d18f7b746a0992880f2dffe749c"; // recid for the "gmi" org unit, for the orgunit of the new employee fields\["orgunitlink"] = "4a05123d660f408997a4fee714dad111"; fields\["team"] = "it"; fields\["department"] = "operations"; fields\["title"] = "administrator"; foreach (string key in fields keys) { datafields add(new objectcommanddatafieldvalue() { name = key, value = fields\[key] tostring() }); } data fields = datafields toarray(); data linktoexistent = new linkentry\[] { // first we link the new employee to the "selfservice" and // "servicedeskanalyst" roles by recid // the internal reference name for the relationship between // profile employee and frs def role is empty, so we leave // the relation attribute in the linkentry empty in this case // link to "selfservice" role new linkentry() { action = "link", relation = "", relatedobjecttype = "frs def role#", relatedobjectid = "0a4724d8478b451abea3fb44d33db1b6" }, // link to "servicedeskanalyst" role new linkentry() { action = "link", relation = "", relatedobjecttype = "frs def role#", relatedobjectid = "06d780f5d7d34119be0d1bc8fc997947" }, // we then link the new employee to the "it" and "hr" teams // the internal reference name for the relationship between // profile employee and standarduserteam is "rev2", so we // specify this in the relation attribute in the linkentry // link to the "it" team new linkentry() { action = "link", relation = "rev2", relatedobjecttype = "standarduserteam#", relatedobjectid = "10f60157a4f34a4f9ddb140e2328c7a6" }, // link to the "hr" team new linkentry() { action = "link", relation = "rev2", relatedobjecttype = "standarduserteam#", relatedobjectid = "1ff47b9eda3049cc92458ce3249ba349" } }; frsheatintegrationcreateboresponse result = frsvc createobject(authsessionkey, tenantid, data); if (result status == "success") { console writeline("a new employee record is created with recid of ", result recid); }