Skip to main content
Version: 8.1

Add and update a record in the section using DataService

Level: advanced
Example

Create a console application that will use DataService to:

  • add a contact record with the value "John Smith" in the Full name column;
  • change the value of the Business phone column to 012 345 67 89 for all contact records that have "John Smith" as the value in the Full name.

Records must be added and modified via a batch query.

Example implementation algorithm

1. Create and set up a C# application project

Using the Microsoft Visual Studio development environment (version 2017 and up), create a Visual C# console application project and specify the project name, for example, DataServiceBatchExample. Set ".NET Framework 4.7" for the project property Target framework.

In the References section of the project, add dependencies from the following libraries:

  • System.Web.Extensions.dll – class library included in .NET Framework;
  • Terrasoft.Core.dll – library of base Creatio server core classes. It can be found using the following path: [Creatio setup catalog]\Terrasoft.WebApp\bin\Terrasoft.Core.dll;
  • Terrasoft.Nui.ServiceModel.dll – application service class library. It can be found using the following path: [Creatio setup catalog]\Terrasoft.WebApp\bin\Terrasoft.Nui.ServiceModel.dll;
  • Terrasoft.Common.dll – library of base Creatio server core classes. It can be found using the following path: [Creatio setup catalog]\Terrasoft.WebApp\bin\Terrasoft.Common.dll.

Add the using directives to the application source code file.

Adding the using directives
using System;
using System.Text;
using System.IO;
using System.Net;
using System.Collections.Generic;
using Terrasoft.Nui.ServiceModel.DataContract;
using Terrasoft.Core.Entities;
using System.Web.Script.Serialization;
using Terrasoft.Common;

2. Add fields and constants and field declarations to the source code

To access DataService features, add the fields and constants to the application source code.

Adding the fields and constants
// Primary URL of Creatio application. Must be replaced with a custom one.
private const string baseUri = @"https://example.creatio.com";
// Request string to the Login methid of the AuthService.svc service.
private const string authServiceUri = baseUri + @"/ServiceModel/AuthService.svc/Login";
// Path string for the BatchQuery.
private const string batchQueryUri = baseUri + @"/0/DataService/json/reply/BatchQuery";
// Creatio authentication cookie.
private static CookieContainer AuthCookie = new CookieContainer();

Here, three string fields are declared. These fields will be used to form authentication query and read data queries execution paths. Authentication data will be saved in the AuthCookie field.

3. Add method that performs Creatio application authentication

Authentication is required to enable access of the created application to the DataService.

4. Implement query adding request

Because the batchQueryUri constant declared previously earlier contains a path for sending data in the JSON format, sent data must be configured beforehand as a string that contains a JSON object description. Use data contract classes to create separate queries then serialize them in a string.

For a query to add a contact record with the name "John Smith", add the following program code:

Implementation the request for adding a record
// Insert query.
var insertQuery = new InsertQuery()
{
RootSchemaName = "Contact",
ColumnValues = new ColumnValues()
{
Items = new Dictionary<string, ColumnExpression>()
{
{
"Name",
new ColumnExpression()
{
ExpressionType = EntitySchemaQueryExpressionType.Parameter,
Parameter = new Parameter
{
Value = "John Smith",
DataValueType = DataValueType.Text
}
}
}
}
}
};

To change the value of the Business phone column to 012 345 67 89 for all contact records that have "John Smith" value in the Full name column, add the code.

Implementation the request for updating a record
// Update query.
var updateQuery = new UpdateQuery()
{
RootSchemaName = "Contact",
ColumnValues = new ColumnValues()
{
Items = new Dictionary<string, ColumnExpression>()
{
{
"Phone",
new ColumnExpression()
{
ExpressionType = EntitySchemaQueryExpressionType.Parameter,
Parameter = new Parameter()
{
Value = "0123456789",
DataValueType = DataValueType.Text
}
}
}
}
},
Filters = new Filters()
{
FilterType = Terrasoft.Nui.ServiceModel.DataContract.FilterType.FilterGroup,
Items = new Dictionary<string, Filter>()
{
{
"FilterByName",
new Filter
{
FilterType = Terrasoft.Nui.ServiceModel.DataContract.FilterType.CompareFilter,
ComparisonType = FilterComparisonType.Equal,
LeftExpression = new BaseExpression()
{
ExpressionType = EntitySchemaQueryExpressionType.SchemaColumn,
ColumnPath = "Name"
},
RightExpression = new BaseExpression()
{
ExpressionType = EntitySchemaQueryExpressionType.Parameter,
Parameter = new Parameter()
{
DataValueType = DataValueType.Text,
Value = "John Smith"
}
}
}
}
}
}
};

After serializing the created instances of the query class, add information about the qualified name of the corresponding data contract to the strings with JSON objects. Compose the string with batch query.

Batch query
// Serialization of update query class instance in a JSON string.
var jsonInsert = new JavaScriptSerializer().Serialize(insertQuery);
// Inserting query type in a JSON string.
jsonInsert = jsonInsert.Insert(1, @"""__type"": ""Terrasoft.Nui.ServiceModel.DataContract.InsertQuery"",");
// Serialization of instance of the update query class in a JSON string.
var jsonUpdate = new JavaScriptSerializer().Serialize(updateQuery);
// Inserting query type in a JSON string.
jsonUpdate = jsonUpdate.Insert(1, @"""__type"": ""Terrasoft.Nui.ServiceModel.DataContract.UpdateQuery"",");
// Creating batch query.
var json = @"{""items"": [" + jsonInsert + "," + jsonUpdate + "]}";

The next step is to execute the POST DataService query. To do this, create an instance of the [HttpWebRequest](https://msdn.microsoft.com/en-us/library/system.net.httpwebrequest(v=vs.110).aspx) class, fill its properties and connect the string with JSON object, created earlier, then execute the DataService query and process its result. To do this, add the source code.

Request implementation
// Converting a JSON object string in a byte array.
byte[] jsonArray = Encoding.UTF8.GetBytes(json);
// Creating an instance of HTTP request.
var batchRequest = HttpWebRequest.Create(deleteQueryUri) as HttpWebRequest;
// Defining request method.
batchRequest.Method = "POST";
// Determining request content.
batchRequest.ContentType = "application/json";
// Adding authentication cookie received earlier to a query.
batchRequest.CookieContainer = AuthCookie;
// Set the ContentLength property of the WebRequest.
batchRequest.ContentLength = jsonArray.Length;

// Adding CSRF token to the request header.
CookieCollection cookieCollection = AuthCookie.GetCookies(new Uri(authServiceUri));
string csrfToken = cookieCollection["BPMCSRF"].Value;
batchRequest.Headers.Add("BPMCSRF", csrfToken);

// Adding JSON object to the query contents.
using (var requestStream = batchRequest.GetRequestStream())
{
requestStream.Write(jsonArray, 0, jsonArray.Length);
}
// Executing HTTP request and getting reply from server.
using (var response = (HttpWebResponse)batchRequest.GetResponse())
{
// Displaying response in console.
using (StreamReader reader = new StreamReader(response.GetResponseStream()))
{
Console.WriteLine(reader.ReadToEnd());
}
}
// Application execution delay.
Console.ReadKey();

Resources

Example implementation (GitHub)