Service Manager powered by HEAT

Using the UpsertObject Web Method

This web method tries to find an existing business object using search fields. If the business object is found, it updates the existing business object similar to how the UpdateObject web method works. If it does not find the business object, it creates a new business object similar to how the CreateObject web method works.

Request Syntax

FRSHEATIntegrationUpsertBOResponse UpsertObject(string sessionKey, string tenantId, ObjectCommandData commandData, string[] searchFields)

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 upsert request.

•searchFields: A list of field names whose values are used to uniquely identify the object.

Return Value

FRSHEATIntegrationUpsertBOResponse object, defined as follows:

public class FRSHEATIntegrationUpsertBOResponse

{

public string status { get; set; }

public string exceptionReason { get; set; }

public string recId { get; set; }

public WebServiceBusinessObject obj { get; set; }

}

The FRSHEATIntegrationUpsertBOResponse 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.

•recId: The RecID of the updated or newly created record, if the value of the status field is success.

•obj: Contains a list of the results found, if the value of the status field is success.

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

Status	Explanation
Success	Successfully updated or created the business object. Access the business object list from the obj field, which returns the results as a list of WebServiceBusinessObjects.
Error	Cannot update or create the business object. The recId and obj fields are 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.   Another common error is that the value for a specified field does not exist in the associated validation list. The error message is:   <BusinessObject>.<Field>:`<FieldValue>` is not in the validation list

Example

The following example creates a new employee record, and links the user to the respective roles and teams. If the employee already exists (identified using the login ID), the system updates the existing information. Notice that the password value is specified in plain text. The system automatically converts it to the internal hashed value, when saving 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"] = "[email protected]";

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.UpsertObject(authSessionKey, tenantId, data, new string ["LoginID" ]);

if (result.status == "Success")

{

Console.WriteLine("A new Employee record is createdor updated with recId of {0}", result.recId);

}