Skip to main content
Matrix42 Self-Service Help Center

Object Data Service: Update Object

Details 

Updates the Object of the specified Configuration Item by the Configuration Item name and object ID. The operation is designed for the complex update transactions, where the modified object attributes belong to different fragments (Data Definitions), or the object multi-fragments need to change (added, deleted, updated), or there is some business logic is triggered on Update transaction (see more Data Object CRUD operations Middleware).  For cases when just a few attributes from the same Data Definition are updating, it is recommended to use light-weight operation Update Fragment 

Better to use the Update Object operation in pair with the  “Get Object” method, which obtains the original Object with the right structure and the actual Timestamp (the marker of the current state).

Concurrency 

In a highly concurrent environment where many users and 3-rd Party applications are simultaneously working on and modifying the same data could lead to data saving conflicts.

For instance, it could happen that an agent (user or another application) tries to change the data, which has been already modified between the moment the agent obtained the latest version of the data (object) and the moment the Update operation is triggered.  As a result, the Update operation just overwrites the recent changes. All of that could lead to data inconsistency and overall Product misbehavior. To prevent such side-effect the Update operation supports two different modes:

  • Track Concurrency:
  1. Specify TimeStamp: include the TimeStamp attribute to the Request Body with the value received via the Service operation Objects.Get. 
  2. Compare values: the System checks the TimeStamp value and rejects the Update transaction if the values in the Database and in the Update request differ.  In this case, the Service operation returns Error 500. For more details see the example below.
  • Ignore Concurrency
    For cases when tracking of concurrency is not important or there is no other agent which modifies the data, the Update operation can be executed without checking Concurrency. For that, just do not include the TimeStamp in the Request Body.

The Server throws the Concurrency exception in case the updated fragment has been updated between Objects.Get operation and Objects.Update.

Full Update (with Multi-Fragmetns)

For the single fragments, the operation updates only the attributes mentioned in the Request body (partial object update), and do not touch attributes which not part of the Request. But for multi-fragments the operation fulfills only full update, what means the request should include all present fragment with required modifications.  As far as operations with the Multi-Fragments usually not needed,  the default Update operation fully ignores the changes in the Multi-Fragments. The Multi-Fragments update functionality needs to be activated on demand, using the Query String parameter "?full=true". 
The Update operation in mode Full update the only multi-fragment Data Definitions which are mentioned in the Request. If the Request does not have even property which keeps the Multi-Fragments objects, in such case, this Multi-Fragments are not effected on the update.

Try to avoid using Update Full operation until the operation with multi-fragments is required. 

Use operation Objects.Get?full=true to obtain the whole original object from Server and use it for preparing Full Update operation.

Multiple Relations

The Virtual attributes/relations, like N:M or 1:N relations, are not affected by the Object Update operation. For executing changes in relations, use the dedicated methods:

Request

URL

PUT https://{server_domain}/m42Services/api/data/objects/{ciName}?full={full}

URL Attributes and Query Parameters

Element Description Type Required
ciName Technical name of the Configuration Item (e.g. for Incident is "SPSActivityTypeIncident") string Required

full

Signals to update the whole Object with all related multi-fragments data, otherwise, all multi-fragments changes are ignored. Default value: false boolean Optional

Headers

For a list of available HTTP request headers see Web Services: REST API integration.

BODY  

JSON Object.  The object has the following format

{
   "ID":"aac1a421-e668-c7e3-fc90-08d491fbcf59",
   "DataDefinition1":{
      "ID":"36a0d1f3-d72f-e711-e580-005056af34ca",
      "TimeStamp":"AAAAADiGOAQ=",
      "Attribute1":"cf060d4d-5c47-462f-b5d1-7df6c865fd91",
      "Attribute2":null
   },
   "DataDefinition2":{      
      "ID":"35a0d1f3-d72f-e711-e580-005056af34ca",
      "TimeStamp":"AAAAADiGN/4=",
      "Attribute3":"TCK00002",
      "Attribute4":"9999-12-31T23:59:59.997Z"
   },
   "MultiFragmentDataDefinition1":[
      {       
         "TimeStamp":"AAAAADiGOAU=",
         "ID":"49368ccd-3ef8-48a1-97a1-012e1d526b40",
         "Attribute4":"Name 1"
      },
      {       
         "TimeStamp":"AAAAADiGOAU=",
         "ID":"49368ccd-3ef8-48a1-97a1-012e1d526b40",
         "Attribute4":"Name 2"
      },      
   ]
}

"ID" required attribute with the Id of the updated object. 

Concurrency tracking: if you want to track concurrency also include the TimeStamp attribute to each mentioned Data Definition

Reset the attribute value: in case you want to reset the attribute value add this attribute to JSON object with the value null.

RESPONSE 

The server does not return any data.

Status codes and errors

The following table lists the returned HTTP status codes.

Code Description
500 Concurrency. The object you want to update has been updated by another process!

 

Examples

Example #1: Update Incident Impact and Urgency

The example demonstrates how the changing of the "Impact" or "Urgency" triggers the Business logic which recalculates the Incident Priority and other attributes. 

PUT https://{server_name}/m42Services/api/data/objects/SPSActivityTypeIncident/ HTTP/1.1
Authorization: Bearer {token}
Content-Type: application/json;charset=UTF-8
{
   "ID":"d82c6fd2-6e07-4a42-a707-eaacec6d9987",
   
   "SPSActivityClassBase":{
      "ID":"eda2206b-2f4b-e911-f080-005056af34ca",
      "TimeStamp":"AAAAAEfgK8M=",
      "Urgency":3,
      "Impact":3
   }
}

Example #2: Add New Journal record to Incident

Journal record is the multi-fragment (SPSActivityClassUnitOfWork) of the Incident Configuration Item.

The example in Javascript code  demonstrates data update which involves such steps:

  1. Retrieve the whole Incident object, with all related multi-fragments;
  2. Add new Jounal records;
var objectId = '7777780d-71a0-df11-708c-000c2968299e';

//receive the whole Incident object with multi-fragments
var xhr = new XMLHttpRequest();
xhr.open('GET', 'http://localhost/m42Services/api/data/objects/SPSActivityTypeIncident/' + categoryId + '?full=true', true);
xhr.setRequestHeader('Authorization', 'Bearer ' + token);
xhr.setRequestHeader('Content-Type', 'application/json');
xhr.onreadystatechange = function() {
   if (this.readyState == 4 && this.status == 200 && this.responseText!==nul) {
      //covert response string to Object 
      var incidentObject = JSON.parse(this.responseText);
      //prepare new request for Update
      var svchttp = new XMLHttpRequest();
      svchttp.open('PUT', 'http://localhost/m42Services/api/data/objects/SPSActivityTypeIncident?full=true', true);
      svchttp.setRequestHeader('Authorization', 'Bearer ' + token);
      svchttp.setRequestHeader('Content-Type', 'application/json');
      //add new record for Journal
      incidentObject["SPSActivityClassUnitOfWork"].push({
         "TypeID":"fe098714-ac94-47f1-9724-df5bac86b3fb",
         "OriginalSolutionHtml":"Journal Comment",
         "ActivityAction":1, 
         "Creator":"93012973-64df-4b19-8e76-f3801d74932b"
      });
      //update Default Sender only
      svchttp.send(JSON.stringify(incidentObject));
   }
};

 

  • Was this article helpful?