The following conceptual example illustrates one of the possible scenarios of using DatumNode Service. Some car rental company (CR) decides to implement DatumNode Service in the present and future software developments. Like most of the others this company has a complex information system: numerous applications are working with different databases, some of them where developed inside the company and others are the products of outside companies. Also some part of the business logic must be accessible by internal applications as well as by the external users (for example travel companies, which need the information about cars that can be rented).

Some of the main problems that DatumNode addresses are listed below:

• Databases integration DatumNode is considered to be a common entry point to all of the data sources of the company. DBA will have an opportunity to control who and how interacts with databases. This increases greatly the manageability and reliability of the whole information system.
• Development of the client applications. DatumNode Service will greatly simplify the development of client application (especially in case of using .NET platform).
• Exposing functionality to external applications DatumNode Service offers the easiest way of the distributed and data-driven applications development. Now numerous web-services (based on some query or stored procedure or even on some external assembly) can be developed without writing a single line of code. This makes DatumNode Service very attractive in case of using some of the SOA integration software – all of them work with the web-services (as the lowest level of business logic abstraction).

Creating users

First of all we must define and create users of our system. Assume that there will be there groups of users:

• Developers – those who will be developing and testing the future application
• Intranet Users – internal users who will use application inside the company
• Internet User - external users who use some part of the functionality of the application (for example, getting the information about the vehicles that can be rented) from the internet

According to this we have created three windows groups:

• CR_Developers
• CR_Intranet_Users
• CR_Internet_Users

After creating windows groups we must we must add them to the roles of DatumNode Service:

Important Note: In order to access the DatumNode Service any user or group must be added to the predefined group DatumNode Users (or other if the default group was redefined after the installation).

Creating Data sources

At this step we must define all the data sources that our application will be working with. Assume that there will be four data sources:

• Vehicle Production (Microsoft SQL Server)
• Vehicle Development (Microsoft SQL Server)
• Payments Production (Oracle)
• Payments Development (Oracle)

Form for creating the data sources includes:

• Name – name of the data source
• Provider – namespace of the ADO.NET 2.0 provider (or name of the wrapper which, in turn, is mapped in the configuration file to the assembly)
• Connection– it is the constant part of the connection string of the data source (usually it includes name of the data source and other parameters except of user credentials)
• Key Mapping- this feature allows setting up some of connection string’s parameters from client’s code. For example the string "user=user id;pwd=password" means that user id and password will be offered by the client by the client as a parameters called "user" and "pwd" (which can be entered in some form)
• Note –any additional information about the data source
• Impersonate – this feature is useful when database authorization is integrated with client’s operating system authorization. For example you must use impersonation in case of using integrated security in MS SQL Server; otherwise client’s credentials will be the same as of the DatumNode Service process in windows (usually "network service" or "system")

Creating Solution and Project

Solutions and projects are on the top of Datum Node's object hierarchy. In our example there will be one solution and one project - "cars_rental_solution" and "car_rental_project".

• Name – name of the solution
• URL – you can specify URL of the application (or website)
• Note – any additional information about the solution.

Creating entities

In our example we will deal with two entities- vehicle and client. The first represents the vehicle that can be rented (information is stored in the Vehicle database) and the second represents the client that rents a vehicle (Payments database).

• Name – name of the solution
• Reference – the name (in format *.*.solution.project.entity) of the entity that will be used instead of current entity
• Note – any additional information about the solution.

Creating data source references and connections

In order to use data sources we must create data source references that point to one of them. All objects (except data source itself) can have any number of data source references with its own permissions. If some object doesn’t have any data source references then the data source references of the objects that stand higher in the hierarchal tree will be used.
If an object has more than one data source references with the same permissions then the data source reference with the highest priority will be used ( if it was not directly specified in the request string, of course). You can change the priority of the data source reference by changing its position in DatumNode Explorer.
Data source reference, in turn, can have any number of connections. Connection is the object that represents some part of the data source’s connection string that can differ for different users (for example user name and password, needed to connect to the database). As any other objects in DatumNode Service connections have theirs own permissions.

Important note. Keep in mind that the resulting connection string consists of constant and variable parts. The constant part is the attribute "connection" of the data source (which, in turn, is specified by the target data source reference –attribute "data source"). The second part can be found in several places:

• If the data source reference has any connections (and the current user has sufficient security permissions) then its attribute "connection" is used. If there are more then one connections then connection with the highest priority (position in the object tree) will be used
• If the data source reference has no connections then its attribute "Default Connection" is used (if it is not empty)
• If data source reference has an empty attribute "Default Connection" then the same attribute of the data source will be used as a default connection

In our example it will be better to create the data source references at the entity level. Each entity will have two data source references – "production" and "dev" (for development and testing purposes).

The form for creating data source references includes the following fields:

• Data Source – name of the data source
• Name – name of the data source reference
• Default Connection – variable part of the connection string
• Note – any additional information

Production data source references will have two connections –"internal" and "external". The first will be used by intranet users and the second by internet users

Setting up security

DatumNode Service has a role- based security. Each object has an ACL – access control list – a list of permissions which specifies who is allowed to access the object and what permissions are allowed.

DatumNode Service supports permissions listed below:

• Browse – is required for viewing object’s names in the DatumNode Explorer
• Change Permissions – allows users to change object’s permissions
• Create Subitems – allows to create child items of the current object (for example, creating entities for the project)
• Delete – allows deleting objects
• Execute – allows users to execute objects (some objects can’t be executed therefore this permission is not applicable for them)
• Read Attributes – allows reading object’s attributes
• Read Permissions – allows users to read object’s permissions
• Write Attributes – allows users to write object’s attributes.

First of all we must give execute permission for our solution and project to each of the free groups (created earlier). Besides "execution" permission developers must have "browse" permission to be able to see them the DatumNode Explorer.

After this we must set permissions for the entities. Users of our application will have only "execute" permission. Developers must have also "browse" and "create subitems" permissions to be able to create commands.

And the most interesting thing is setting up permissions for the data source references and connections. Developers must have access to the development servers, so they will have "execute" permission to "dev" data source references. As they don’t have "browse" permission they will not see any data source references and will have no idea to what database they are connected to.

Data source references named "Production" have to connections – "internal" and "external". This was made for to the security reasons: intranet and internet users must access data database using different credentials (or other parameters of the connection string). According to this intranet user will have "execute" permission to the "internal" connection and the internet users will have "execute" permission to the "external" connection.

Besides these users must have "execute" permission to the "production" data source references themselves.

Creating commands and generation client code

Now let's see how the developers will work with the DatumNode Service. According to the rights given to them, they will see only solution and project in the DatumNode Explorer.

To begin using DatumNode Service in the client applications developers must create commands. In our example entity "vehicle" the following commands: "check_in", "check_out" and "get_info". And for the entity "client" commands are listed below: "get_info", "get_payments" and "get_history".
The form for creating commands includes:

• Name - the name of the command
• Reference – the name of the command that will be executed instead of the current command
• Type- type of command: text or store procedure
• Column mapping – it is a convenient way for mapping column names of the result record set.This field must be set in proper format:"new_column_name"="old_column_name". If "old_column_name" is a number then the corresponding position of the column will be used instead of the name
• Note- any additional information about the command
• Maximum record – represents the maximum number of records the command can return
• Command Text – depended on the type of the command this field is filled by the name of the stored procedure or by the text of the sql query

Then we must add parameters to the commands. Form for creating parameters includes:

• Name - the name of the parameter
• Server Name - name of the parameter used in the database
• Direction - "Input”,”Output”, "InputOutput” or "ReturnValue”
• Type – type of parameter (some of them depends on the database)
• Behavior:- "normal” –parameter is used in normal way. When set to "constant” – some constant value is always used. "System” represents some system value.
• Note – any additional information about parameter
• Precision – indicates the precision of numeric parameters
• Scale – indicates the scale of numeric parameters
• Size – the size of the parameter
• Default value – this value will be used if the value of the parameter is not set

Important notes:

• If the field "server name” is empty then this parameter will not be used during command execution
• If behavior is set to "system” then the field "default value” represents some system value. DatumNode Service currently supports the following system values: user (returns the current user name), roles (returns the roles current user is belong to),request (full request string currently executing) and now (returns current date and time)
• Direction - "Input”,”Output”, "InputOutput” or "ReturnValue”

After the creation of commands is complete we can proceed and generate client code. To do this we must toggle to the selection mode and select objects for which we are going to generate code. Assume we generate code for the whole solution:

Then we press "generate” button. The form "Commands Generation” includes the following fields:

• Language namespace of the .NET code provider. You can choose any language that is supported by the current version of the .NET Framework
• File name - specifies the full path of the file with generated code (usually it is the folder with the solution where DatumNode Service will be used)
• Namespace- represents the namespace of auto generated class (default is "Solution")
• Object’s prefixes – any literal that will be concatenated with the name of the DatumNode object (e.g. solution, project, entity, command or parameter). This feature is used when an object has a name which concurs with some of the reserved word (for example "new”, "for” and so on)

To execute command and retrieve data we must write a few lines of code, as shown next:

cars_rental_solution.cars_rental_project.vehicle.get_info vehicle_info= new cars_rental_solution.cars_rental_project.vehicle.get_info();
vehicle_info.Parameters.id = 1;
vehicle_info.ExecuteReader();


Auditing and statistics

Being the common entry point for all the applications that interacts with different data sources, DatumNode Service offers the logging and auditing of all the client’s requests. This is accomplished in two ways: by the built-in windows mechanisms (logging, auditing, performance counters) and by the internal subsystem of DatumNode Service.

Windows logging

Information about any important DatumNode Service activity is stored in the windows event log (group "DatumNode Service” is created automatically during the installation).

Performance monitoring

DatumNode Service also supports windows built-in mechanisms for monitoring performance. It offers different performance counters, among them are: total rows fetched, number of requests, number of errors and others.

Logging request by DatumNode Service’s internal subsystems

The main aim of this mechanism is to gather different statistics about how the request was executed at the given period. This feature can be enabled by checking the "audit” checkbox at any object.
The information includes: full name of the request, count of calls, time of the execution (min, max, and total, average), and count of the requests failed during the execution, count of rows fetch by the requests and others.
DatumNode Service also stores the information about any errors occurring during execution. Since all the applications will access data sources threw DatumNode Service you will see any error occurred during the request processing, because no one among the developers will be able to "hide" them by using different exception handling technologies