General information

The bpm'online DataService web service is a RESTfull service. RESTful is a quite simple information management interface that doesn't use any additional internal layers, i.e., the data doesn't need to be converted to any third-party format, such as XML. In a simple RESTful service, each record is uniquely identified by a global identifier such as a URL. Each URL has a strictly specified format. However, this service is not always convenient for transferring large amounts 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 web service" article.

DeleteQuery data contract

The DeleteQuery contract is used to delete sections. The data is transferred to the DataService via HTTP by using the POST request with the following URL:

// URL format of the POST query to DataService to delete data.
http(s)://[Bpm'online application address]/[Configuration number]/dataservice/[Data fromat]/reply/DeleteQuery
// URL example of the POST query to DataService to delete data.
http(s)://example.bpmonline.com/0/dataservice/json/reply/DeleteQuery

The DeleteQuery data contract has a hierarchical structure with multiple nesting levels. In the bpm'online application server part, the DeleteQuery data contract is represented by the InsertQuery class of the Terrasoft.Nui.ServiceModel.DataContract namespace of the Terrasoft.Nui.ServiceModel.dll class library. However, for simplicity, the hierarchical structure of the DeleteQuery data contract is conveniently presented as a JSON format object:

{
    "RootSchemaName":"[Root schema]",
    "OperationType":[Record operation type],
    "ColumnValues":[Column values. Not used.],
    "Filters":[Query filters]
}

The basic properties of the DeleteQuery class and their possible values are presented in table 1.

Table 1. DeleteQuery class properties.

The Filters class is defined in the Terrasoft.Nui.ServiceModel.DataContract namespace. The properties of this class are described in the "DataService. Data filtering" article.

IMPORTANT The DeleteQuery query class instance must contain a link to the correctly initialized Filters class instance in the Filters property. Otherwise ALL section records will be deleted.

Deleting records using a third-party application example

Case description

You need to create a console application that, using the DataService service, will delete the "John Best" contact record added in the example of the "DataService. Adding records" article.

Case realization

The complete source code for implementation of this case is available here.

Case implementation algorithm

1. Сreate and configure a C# console application project

Using the Microsoft Visual Studio (version 2017 and up) development environment, create a Visual C# console application project and name it DataServiceDeleteExample. The [Target framework] project property must be set to .NET Framework 4.7.

In the References section of the project you need to add dependencies of the following libraries:

• System.Web.Extensions.dll is a class library included in the .NET Farmework
• Terrasoft.Core.dll is a main class library of the application server kernel. Can be found by the following path: [Directory with the installed application]\Terrasoft.WebApp\bin\Terrasoft.Core.dll
• Terrasoft.Nui.ServiceModel.dll class library the application services. Can be found by the following path: [Directory with the application installed]\Terrasoft.WebApp\bin\Terrasoft.Nui.ServiceModel.dll.
• Terrasoft.Common.dll is a main class library of the application server kernel. Can be found by the following path: [Directory with the installed application]\Terrasoft.WebApp\bin\Terrasoft.Common.dll

Add using directives to the application source code file:

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 field declarations and constants to the application source code

To access the DataService features, you must add the following fields and constants to the application source code:

 // Main bpm'online URL. Has to be changed to a custom one.
 private const string baseUri = @"http://example.bpmonline.com";
// Query string to the Login method of the AuthService.svc service.
 private const string authServiceUri = baseUri + @"/ServiceModel/AuthService.svc/Login";
 // DeleteQuery query path string.
 private const string deleteQueryUri = baseUri + @"/0/DataService/json/reply/DeleteQuery";
 // Bpm'online cookie authentication.
 private static CookieContainer AuthCookie = new CookieContainer();

Three string constant fields that are used to carry out the authentication requests and requests to read data are declared here. The authentication data will be stored in the AuthCookie field.

3. Add a method that performs authentication in the bpm'online application

You need to authenticate the newly created application to access the DataService web service.

The algorithm and an implementation example of a method that performs a request to the AuthService.svc service for user authentication can be found in the Authenticating external requests to bpm'online services article.

4. Implement a query to add a record

As the previously declared updateQueryUri constant contains the path for sending data in JSON format, the data sent must be pre-configured in the form of a string containing a description of the JSON object corresponding to the UpdateQuery data contract. This can be done directly in a lowercase variable but it is much easier and safer to create an instance of the UpdateQuery class, fill its properties, and then serialize it to a string. This can be done by adding the following source code:

// Query class instance.
var deleteQuery = new DeleteQuery()
{
    // Root schema name.
    RootSchemaName = "Contact",
    // Query filters.
    Filters = new Filters()
    {
        // Filter type — group.
        FilterType = Terrasoft.Nui.ServiceModel.DataContract.FilterType.FilterGroup,
        // Filter collection.
        Items = new Dictionary<string, Filter>()
        {
             // Filtration by name.
            {
                // Key.
                "FilterByName",
                // Value.
                new Filter
                {
                    // Filter type — comparison filter.
                    FilterType = Terrasoft.Nui.ServiceModel.DataContract.FilterType.CompareFilter,
                    // Comparison type — starts with an expression.
                    ComparisonType = FilterComparisonType.Equal,
                    // Expression to be checked.
                    LeftExpression = new BaseExpression()
                    {
                        // Expression type — schema column.
                        ExpressionType = EntitySchemaQueryExpressionType.SchemaColumn,
                        // Column path.
                        ColumnPath = "Name"
                    },
                    // Filtration expression.
                    RightExpression = new BaseExpression()
                    {
                        // Expression type — parameter.
                        ExpressionType = EntitySchemaQueryExpressionType.Parameter,
                         // Expression parameter.
                        Parameter = new Parameter()
                        {
                            // Parameter data type — text.
                            DataValueType = DataValueType.Text,
                            // Parameter value.
                            Value = "John Best"
                        }
                    }
                }
            }
        }
    }
};
// Class instance serialization of the JSON string adding query.
var json = new JavaScriptSerializer().Serialize(updateQuery);

This creates an instance of the DeleteQuery class. The "Contact" value is set in the RootSchemaName property. To delete a particular record or group of records, you need to set a link to the correctly initialized Filters class instance to the Filters property. In this case, a single filter that selects only records with the "John Best" value in the [Full name] column is added to the filter collection.

In the final step you must perform POST query to the DataService service. To do this, create an instance of the HttpWebRequest class, fill in its properties, attach a previously created string with the JSON object to a request, and then execute and process the result of the query to the DataService service. To do this, add the following source code:

// Converting a JSON object string to a byte array.
byte[] jsonArray = Encoding.UTF8.GetBytes(json);
// Creating an insrance of HTTP request.
var updateRequest = HttpWebRequest.Create(updateQueryUri) as HttpWebRequest;
// Defining a request method.
updateRequest.Method = "POST";
// Determining type of request content.
updateRequest.ContentType = "application/json";
// Adding authentication cookie received earlier to a request.
updateRequest.CookieContainer = AuthCookie;
// Set length for request content.
updateRequest.ContentLength = jsonArray.Length;

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

// Plase a JSON-object to request content.
using (var requestStream = updateRequest.GetRequestStream())
{
    requestStream.Write(jsonArray, 0, jsonArray.Length);
}
// Executing HTTP request and getting a response from server.
using (var response = (HttpWebResponse)updateRequest.GetResponse())
{
    // Displaying response in console.
    using (StreamReader reader = new StreamReader(response.GetResponseStream()))
    {
        Console.WriteLine(reader.ReadToEnd());
    }
}

The complete source code for implementation of this case is available here.

See Also