DataService. Updating records
Glossary Item Box
General provisions
The DataService web service of Creatio is a RESTful (Representational State Transfer, REST) service. The RESTful data management interface does not require converting data to an external format, such as XML. In a simple RESTful service, each information unit is determined by a global Identifier such as URL. Each URL, in its turn, has a strictly specified format. This is not an optimal way to transfer large arrays of data.
With the use of the DataService, the data can be automatically configured in various data formats such as XML, JSON, HTML, CSV, and JSV. The data structure is determined by data contracts. A complete list of data contracts used by the DataService, can be found in the "DataService" article.
UpdateQuery data contract
The UpdateQuery data contract is used for updating section records. The query data is transferred to DataService via HTTP, with the help of POST by the following URL:
// URL format of the POST query to DataService to update data. http(s)://[Creatio application address]/[Configuration number]/dataservice/[Data fromat]/reply/UpdateQuery // URL example of the POST query to DataService to update data. http(s)://example.creatio.com/0/dataservice/json/reply/UpdateQuery
The UpdateQuery data contract has a hierarchical structure with a number of nesting levels. In the Creatio server core, it is represented by a UpdateQuery class of theTerrasoft.Nui.ServiceModel.DataContract namespace of the Terrasoft.Nui.ServiceModel.dll library of classes. For the hierarchical data structure of the UpdateQuery data contract can be conveniently viewed in JSON format:
{ "RootSchemaName":"[Root schema]", "OperationType":[Type of operation with record], "IsForceUpdate":[Force update], "ColumnValues":{ "Items":{ "Name of the added column":{ "ExpressionType":[Expression type], "Parameter":{ "DataValueType":[Data type], "Value":"[Column value]" } }... } }, "Filters":[Request filters] }
Primary properties of the UpdateQuery class and their possible values are available in table 1.
Table 1. UpdateQuery class properties
Property | Type | Notes | ||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|
RootSchemaName | string | String that contains root schema name of added record object. | ||||||||||
OperationType | QueryOperationType |
Type of write operation. Specified as a QueryOperationType enumeration value of the Terrasoft.Nui.ServiceModel.DataContract name space. The QueryOperationType.Insert value is set for InsertQuery. Values of the QueryOperationType enumeration:
|
||||||||||
IsForceUpdate | bool | Indicates force update. If the value is true, the entity will be saved on the server even if column values have been modified. Default value: false. | ||||||||||
ColumnValues | ColumnValues | Contains collection of column values for the added record. The ColumnValues type is defined in the Terrasoft.Nui.ServiceModel.DataContract name space. | ||||||||||
Filters | Filters | Collection of query filters. The Filters type is defined in the Terrasoft.Nui.ServiceModel.DataContract name space. |
The ColumnValues class has a single Items property, defined as a collection of keys and values Dictionary<string, ColumnExpression>. The key is the string with the name of the added column. The value is an object of the ColumnExpression type, defined in the Terrasoft.Nui.ServiceModel.DataContract name space. General properties of the ColumnExpression class used when adding records are available in table 2.
Table 2. Primary properties of the ColumnExpression class
Property | Description | ||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
ExpressionType |
Type of expression that determines the value that the added column will contain. Specified with a value from the EntitySchemaQueryExpressionType enumeration of the Terrasoft.Core.Entities name space defined in the Terrasoft.Core class library. The EntitySchemaQueryExpressionType.Parameter value is set for InsertQuery. Values of the EntitySchemaQueryExpressionType enumeration:
|
||||||||||
Parameter |
Determines the value that the added column will contain. The Parameter type is defined in the Terrasoft.Nui.ServiceModel.DataContract name space. |
The Parameter class has a number of properties, only two of which are used for adding records (table 3).
Table 3. Primary properties of the Parameter class
Property | Description | ||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
DataValueType |
Type of data for the value that the added column will contain. Specified as a DataValueType enumeration value of the Terrasoft.Nui.ServiceModel.DataContract name space. Values of the DataValueType enumeration:
|
||||||||||||||||||||||||||||||||
Value |
The object that contains the value of the added column. Has the Object type. |
The Filters class is defined in the Terrasoft.Nui.ServiceModel.DataContract name space. For details on the properties of this class and its use, please see the "DataService. Data filtering" article.
An instance of the UpdateQuery class must contain a link to a correctly initialized instance of the Filters class in the Filters property. Otherwise, new column values from the ColumnValues property will be set for ALL section records.