Skip to main content
Matrix42 Self-Service Help Center

Fragments Data Service: Update fragment

Details

Updates the specified Data Definition fragment attributes.

The Service modifies only attributes which are explicitly specified in the Request Body. The attributes which are not mentioned in the request are not affected by the Update operation. 

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 status of the data (fragment) and the moment the Update operation is triggered.  As a result the Update operation just ignores the latest state of the fragment and just overwrites the recent changes. All of that could lead to data inconsistency and overall Product misbehavior. 

The Update operation supports different modes:

  • Track Concurrency:
  1. Specify TimeStamp: include the TimeStamp attribute to the Request Body with the value received via the Service operation Fragments.Get or 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 Get Fragment operation and Update Fragment.

Request

URL 

PUT https://{server_name}/m42Services/api/data/fragments/{ddName}

URL Attributes

Element Description Type Required
ddName The technical name of the Data Definition (e.g. SPSActivityClassBase) string Required

Headers 

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

Body 

JSON Object with fragment attributes with new values. 

"ID" attribute with the updated Fragment Id value is required.

Concurrency tracking: if you want to track concurrency also include the TimeStamp attribute.

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

{
   "ID":"7777780d-71a0-df11-708c-000c2968299e",
   "TimeStamp":"AAAAACeGa20=",
   "Attribute1":null,
   "Attribute2": "New Value"
}

Response 

The Service returns no data.

Status codes and errors 

The following table lists the returned HTTP status codes.

Code Description
204 The fragment has been successfully updated.
400
  • Concurrency. The object you want to update has been updated by another process.
  • Fragment with specified ID not found, or not defined.
500 Data Definition not found.

 

Examples

 Fragment's Simple Update

The following example shows how to update the Category "Facility Management":

PUT https://{server_name}/m42Services/api/data/fragments/SPSScCategoryClassBase/ 
Content-Type: application/json;charset=UTF-8
Authorization: Bearer {token}
{
"ID": "7777780d-71a0-df11-708c-000c2968299e",
  "DefaultSubject": "Facility Management Subject",
  "DefaultImpact": 3, 
  "Hidden": 1
}

Update with concurrency tracking

The example below shows how to update the Category "Facility Management" fragment with a specific TimeStamp.

Use the TimeStamp  for the safe-update data and in order to avoid the risk of overwriting other people updates.

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

  1. Retrieve the whole Category Fragment;
  2. Extract the  TimeStamp value;
  3. Send a new  request to update the category with the new Default Subject value:
var categoryId = '7777780d-71a0-df11-708c-000c2968299e';

//receive all data for Category fragment
var xhr = new XMLHttpRequest();
xhr.open('GET', 'http://localhost/m42Services/api/data/fragments/SPSScCategoryClassBase/' + categoryId, 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 categoryFragment = JSON.parse(this.responseText);
      //prepare new request for Update
      var svchttp = new XMLHttpRequest();
      svchttp.open('PUT', 'http://localhost/m42Services/api/data/fragments/SPSScCategoryClassBase/', true);
      svchttp.setRequestHeader('Authorization', 'Bearer ' + token);
      svchttp.setRequestHeader('Content-Type', 'application/json');
      //update Default Sender only
      svchttp.send(JSON.stringify({
         "ID": categoryId,
         "TimeStamp": categoryFragment.TimeStamp,
         "DefaultSubject": "Facility Management Subject",
      }));
   }
};

 

  • Was this article helpful?