DataService. Adding records
Glossary Item Box
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 URL. Each URL, in turn, has a strictly specified format. However, this service is not always convenient for transferring large amounts of data.
Since the DataService is based on ServiceStack .NET framework, 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.
InsertQuery data contract
The InsertQuery data contract is used to add records to 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 add data to DataService. http(s)://[Bpm'online application address]/[Configuration number]/dataservice/[Data fromat]/reply/InsertQuery // URL example for the POST query to add data to DataService. http(s)://example.bpmonline.com/0/dataservice/json/reply/InsertQuery
The InsertQuery data contract has a hierarchical structure with multiple nesting levels. In the bpm'online application server part, the InsertQuery 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 InsertQuery data contract is conveniently presented as a JSON format object:
{ "RootSchemaName":"[Root object schema name]", "OperationType":[Record operation type], "ColumnValues":{ "Items":{ "Added column name":{ "ExpressionType":[Expression type], "Parameter":{ "DataValueType":[Data type], "Value":"[Column value]" } }... } } }
The basic properties of the InsertQuery class and their possible values are presented in table 1.
Table 1. InsertQuery class properties.
Property | Description | ||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
RootSchemaName | A string containing the name of the root object schema of the added record. | ||||||||||
OperationType |
Operation type is set by the QueryOperationType namespace Terrasoft.Nui.ServiceModel.DataContract namespace enumeration value. For the InsertQuery theQueryOperationType.Insert value is set. QueryOperationType enumeration values:
|
||||||||||
ColumnValues | Contains a collection of column values of the added record. Its ColumnValues type is defined in the Terrasoft.Nui.ServiceModel.DataContract namespace. |
The ColumnValues class has a single Items property that is defined as a collection of the Dictionary<string, ColumnExpression> keys and values. The key is a string with the added column title, and the value is the object with the ColumnExpression type defined in theTerrasoft.Nui.ServiceModel.DataContract namespace. The basic properties of the ColumnExpression class used when adding records, are given in table 2.
Table 2. ColumnExpression class main properties
Property | Description | ||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
ExpressionType |
The expression type that defines the value that will be contained in the added column. Set by the EntitySchemaQueryExpressionType enumeration of the Terrasoft.Core.Entities namespace defined in the Terrasoft.Core class library. For the InsertQuery the EntitySchemaQueryExpressionType.Parameter value is set. EntitySchemaQueryExpressionType enumeration type:
|
||||||||||
Parameter |
Defines the value that will be contained in the added column. Its Parameter type is defined in the Terrasoft.Nui.ServiceModel.DataContract namespace. |
The Parameter class has multiple properties, two of which are used to add records (table 3).
Table 3 Parameter class main properties
Property | Description | ||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
DataValueType |
The data value type that defines the value that will be contained in the added column. Set by the DataValueType enumeration value of theTerrasoft.Nui.ServiceModel.DataContract namespace. DataValueType enumeration type:
|
||||||||||||||||||||||||||||||||
Value |
The object that contains the added column value. |
Creating a record using a third-party application example
Case description
You need to create a console application that will add the following data to the [Contact] section using the DataService service:
- Full name — John Best
- Full job title — Developer
- Business phone — +12 345 678 00 00.
Case realization
You can download a full source code of this example here.
Case implementation algorithm
1 Сreate and configure a C# console application project
Using the Microsoft Visual Studio (version 2012 Update 4) development environment, create a Visual C# console application project and name it DataServiceInsertExample. The [Target framework] project property must be set to .NET Framework 4.5.
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.
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;
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"; // InsertQuery query path string. private const string insertQueryUri = baseUri + @"/0/DataService/json/reply/InsertQuery"; // 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 add 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 Add the direct implementation of the add record query
As the previously declared insertQueryUri constant contains the path for sending data in JSON format, then the data sent must be pre-configured in the form of a string containing a description of the JSON object corresponding to the InsertQuery data contract. This can be done directly in a lowercase variable but it is much easier and safer to create an instance of the InsertQuery 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 insertQuery = new InsertQuery() { // Root schema name. RootSchemaName = "Contact", // Added column values collection. ColumnValues = new ColumnValues() }; // Expression class instance of the object schema query. // Used to configure the [Full name] column. var columnExpressionName = new ColumnExpression { // Query object schema expression type — parameter. ExpressionType = EntitySchemaQueryExpressionType.Parameter, // Query expression parameter. Parameter = new Parameter { // Parameter value. Value = "John Best", // Parameter data type — string. DataValueType = DataValueType.Text } }; // Expression class instance of the object schema query. // Used to configure the [Business phone] column. var columnExpressionPhone = new ColumnExpression { ExpressionType = EntitySchemaQueryExpressionType.Parameter, Parameter = new Parameter { Value = "+12 345 678 00 00", DataValueType = DataValueType.Text } }; // Expression class instance of the object schema query. // Used to configure the [Job title] column. var columnExpressionJob = new ColumnExpression { ExpressionType = EntitySchemaQueryExpressionType.Parameter, Parameter = new Parameter { // The "Developer" record GUID of the [Job title] system lookup. // Change to the record GUID in bpm'online. Value = "11D68189-CED6-DF11-9B2A-001D60E938C6", // Parameter data type — unique ID. DataValueType = DataValueType.Guid } }; // Query column collection initialization. insertQuery.ColumnValues.Items = new Dictionary<string, ColumnExpression>(); // Adding query expressions to the added column collection. // The [Full name] column. insertQuery.ColumnValues.Items.Add("Name", columnExpressionName); // The [Business phone] column. insertQuery.ColumnValues.Items.Add("Phone", columnExpressionPhone); // The [Job title] column. insertQuery.ColumnValues.Items.Add("Job", columnExpressionJob); // Class instance serialization of the JSON string adding query. var json = new JavaScriptSerializer().Serialize(insertQuery);
NOTE In this example, to reduce the article size, a unique identifier of the "Developer" record of the [Position] lookup is represented as a string literal. It can be defined, for example, using the SelectQuery query with the job title filter. |
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 JSON string object to a byte array. byte[] jsonArray = Encoding.UTF8.GetBytes(json); // Creating HTTP query instance. var insertRequest = HttpWebRequest.Create(insertQueryUri) as HttpWebRequest; // Defining method query. insertRequest.Method = "POST"; // Defining query content type. insertRequest.ContentType = "application/json"; // Adding the previously received authenticated cookie to the receiveing data query. insertRequest.CookieContainer = AuthCookie; // Define query content length. insertRequest.ContentLength = jsonArray.Length; // Adding a JSON object to the query. using (var requestStream = insertRequest.GetRequestStream()) { requestStream.Write(jsonArray, 0, jsonArray.Length); } // Executing the HTTP query and receiving answer from server. using (var response = (HttpWebResponse)insertRequest.GetResponse()) { // Displaying answer in console. using (StreamReader reader = new StreamReader(response.GetResponseStream())) { Console.WriteLine(reader.ReadToEnd()); } }
You can download a full source code of this example here.
Creating a record in bpm'online example
Case description
Add to the [Contact] section a button that when clicked invokes a method, using the InsertQuery class that adds a record with the following data:
- Full name — John Best
- Full job title — Developer
- Business phone — +12 345 678 00 00.
Case realization
You can download a full source code of this example here.
Case implementation algorithm
1 Add button to the [Contacts] section
The process of adding buttons to sections is described in the "How to add a button to a section" article.
For this particular case, you need to create a replacement client module of the [Contacts] section (Fig. 1).
Fig. 1 Replacement client module properties.
In the created client schema, add theInsertQueryContactButtonCaption localizable string, and set the "Add contact" value to it (Fig. 2).
Fig. 2 Localizable string properties
Add a configuration object with the button location settings to the diff array.
diff: /**SCHEMA_DIFF*/[ // Metadata to be added to the custom button section. { // The element is added to the page. "operation": "insert", // Parent interface element name to which the button is added. "parentName": "ActionButtonsContainer", // The button is added to the interface element collection // of the parent element (its metaname is specified in parentName). "propertyName": "items", // Added button metaname. "name": "InsertQueryContactButton", // Additional element properties. "values": { // Added element type — button. itemType: Terrasoft.ViewItemType.BUTTON, // Binding button caption to the localizable schema string. caption: { bindTo: "Resources.Strings.InsertQueryContactButtonCaption" }, // Binding method of processing the button click. click: { bindTo: "onInsertQueryContactClick" }, "layout": { "column": 1, "row": 6, "colSpan": 1 } } } ]/**SCHEMA_DIFF*/
2 Add the processing method for the button click event
In order for a record with the necessary data to be added when a button created in the section is clicked, add the following method to the methods section of the replacement client schema:
methods: { // Method of processing the button click. onInsertQueryContactClick: function() { // Creating the Terrasoft.InsertQuery class instance. var insert = Ext.create("Terrasoft.InsertQuery", { // Root schema name. rootSchemaName: "Contact" }); // Setting the Terrasoft.ParameterExpression value-parameters. // A value-parameter instance is created and added to the column value collection. // Creating a value-parameter instance for the [Job title] column. insert.setParameterValue("Name", "John Best", Terrasoft.DataValueType.TEXT); // Creating a value-parameter instance for the [Business phone] column. insert.setParameterValue("Phone", "+12 345 678 00 00", Terrasoft.DataValueType.TEXT); // Creating a value-parameter instance for the [Job title] column. insert.setParameterValue("Job", "11D68189-CED6-DF11-9B2A-001D60E938C6", Terrasoft.DataValueType.GUID); // Data update query. insert.execute(function(response) { // Displaying server answer window.console.log(response); }); // Updating list data. this.reloadGridData(); } }
NOTE Unlike the previous example, authorization is not required because the code is executed directly in the bpm'online application. |
The implementation of the InsertQuery class for the client part of the application kernel is different from the implementation of the InsertQuery in its back end. So, to create the parameters, the setParameterValue method is used, and for the query execution — the execute method. Learn about all the available properties and methods of the InsertQuery class implemented in the kernel client part in the API documentation.
You can download a full source code of this example here.