Overview

The UBIK Enterprise Service is a Windows service designed to automate UBIK interface components and interface workflows.

Concept

The UBIK Enterprise Service typically runs on a server and monitors an arbitrary number of folders in the file system for changes, such as newly created or modified files.

When a change is detected, the service parses the file and checks whether its extension matches a UBIK command file signature. If it does, the file is processed.

Command File

A command file for the UBIK Enterprise Service is a plain text file with the extension .command or .json.command.

When the Enterprise Service starts processing such a file, it is parsed as either XML or JSON. For XML documents, any content outside the XML structure is ignored.

XML Command

A sample command file for starting an interface component:

<InterfaceManager>
  <Commands>
    <Interface FullName="UBIK.TEST, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null"
               File="F:\Test\UBIK.TEST.dll"
               Class="UBIK.TestInterface"
               Direction="E">
      <Parameter Key="Server" Value="AUGLNZ0SQL" />
      <Parameter Key="InitialCatalog" Value="UBIK.Sandbox.Dev.V2" />
      <Parameter Key="UserID" Value="sa" />
      <Parameter Key="Password" Value="secretpassword123" />
      <Parameter Key="RecordLifeTime" Value="-1" />
      <Parameter Key="MyIFNeedsThis" Value="TestValue" />
    </Interface>
  </Commands>
</InterfaceManager>

This command file attempts to instantiate the class UBIK.TestInterface from the assembly F:\Test\UBIK.TEST.dll.

If the connection succeeds, the methods of the export interface are invoked because Direction="E".

A sample command file for starting a workflow:

<InterfaceManager>
  <Commands>
    <Workflow Name="WF_XML_TEST"
              UID="5fdccb8c-85db-4dfc-861a-57be38267bfb"
              Async="False">
      <Parameter Key="Server" Value="AUGLNZ0SQL" />
      <Parameter Key="InitialCatalog" Value="UBIK.Sandbox.Dev.V2" />
      <Parameter Key="UserID" Value="sa" />
      <Parameter Key="Password" Value="secretpassword123" />
      <Parameter Key="RecordLifeTime" Value="-1" />
      <Parameter Key="MyWorkflowNeedsThis" Value="TestValue" />
    </Workflow>
  </Commands>
</InterfaceManager>

This command file attempts to load the workflow object with GUID 5fdccb8c-85db-4dfc-861a-57be38267bfb and invoke it synchronously because Async="False".

Tip

Leave UserID and Password empty to connect to SQL Server using Windows Authentication:

https://msdn.microsoft.com/en-us/library/dd787978.aspx

Tip

If the database server is running locally, use . as the value of the Server parameter.

Workflow Arguments

Every workflow started by the Enterprise Service requires an argument named UBIKObject of type UBIK.Kernel.BaseClass.

The Enterprise Service automatically initializes this argument with the workflow object itself.

Important

Any additional parameter passed from the command file to the workflow must have a corresponding workflow argument.

Tip

Configuration files can be created and edited manually, but can be created more conveniently by using the Interface Manager.

JSON Command

Using this command file type, the UBIK Enterprise Service starts a UBIK.Console instance and passes the scripts defined in the command file as parameters.

CommandFileAction corresponds to the same setting available in the Enterprise Service configuration. If specified in the command file, it overrides the configuration setting. If it is -1 or null, the configuration value is used instead.

This makes it possible to execute different actions for each command file.

{
  "PathToUbikConsole": "...\\UBIK.Studio\\UBIK.Console.exe",
  "InitStatement": "...\\UBIK.Studio\\Scripts\\init.cs",
  "PathToScriptFile": "...\\UBIK.Studio\\Scripts\\script.cs",
  "ConfigFilePath": "...\\UBIK.Studio\\Scripts\\config.cs",
  "CommandFileAction": 2
}

Web Interface

Since version 3.5.0, UBIK Enterprise Service supports a web interface.

Because the Enterprise Service already provides a file-based interface capable of executing code and workflows, the web interface was designed to remain backward compatible. Workflows, tasks, and code can therefore be enqueued through HTTP as well.

Note

Executable code must derive from UBIK.Interface.UBIKInterfaceBase and implement either IUBIKImport, IUBIKExport, or both.

How to Consume the Web Interface

Endpoints follow the pattern:

api/{controller}/{action}

For example, to call GetUpTimeInfo():

GET http://localhost:9000/api/basicenterpriseservice/getuptimeinfo

The web interface allows task execution similar to XML command files and introduces the concept of tasks.

A task represents any operation to be executed by UBIK and requires a .NET method as an entry point.

A task can be identified in two ways:

• By fully-qualified class name and method name.
• By implementing UBIK.ServiceTask.TaskExecution.ITask.

Parameters can be supplied as a JSON string. Deserialization is handled by the task implementation.

Required parameters:

bool SSPI;
string SQLUser;
string SQLPassword;
string SQLServer;
string SQLInitialCatalog;

// Full path ({Methodname}) to the method (task) to be executed.
string MethodName;

// Full path ({Namespacename}.{Classname}) to the class containing the method.
string ClassFullname;

// Serialized JSON parameter object.
string MethodParametersAsJson;

UBIK.EnterpriseService.WebInterface.Client

To consume the API, use the UBIK.EnterpriseService.WebInterface.Client .NET library.

The library is included in a standard UBIK installation and can also be used from inside UBIK Studio.

UBIK.EnterpriseService.BasicClient.App

Another option is UBIK.EnterpriseService.BasicClient.App, a standalone application built on the client library.

This application can be used together with the Windows Task Scheduler.

Configuration is done in:

UBIK.EnterpriseService.BasicClient.App.exe.config

The appSettings section contains:

• BaseAddress

  • Base URL of the Enterprise Service Web Interface.
  • Default: http://localhost:9000

• PathToBasicEnterpriseServiceRequestJsonFile

  • Path to a JSON file containing one or more task definitions.

Example:

{
  "Tasks": [
    {
      "ClassFullname": "namespace1.class1",
      "MethodName": "method1",
      "MethodParameterPathFullName": "pathToFileContainingAnyJson1"
    },
    {
      "ClassFullname": "namespace2.class2",
      "MethodName": "method2",
      "MethodParameterPathFullName": "pathToFileContainingAnyJson2"
    }
  ],
  "RepeateEveryMinutes": 0,
  "SqlConnectionDefinition": {
    "SSPI": false,
    "SQLUser": "user",
    "SQLPassword": "pw",
    "SQLServer": "server",
    "SQLInitialCatalog": "db"
  },
  "ClassFullname": null,
  "MethodName": null,
  "MethodParameterPathFullName": null
}

• PathToBasicEnterpriseServiceRequestJsonFileList
  • Path to a file containing multiple request file paths separated by line breaks.

Tip

The minimum value for RepeateEveryMinutes is 0.

When set to 0, the task is executed continuously without delay.

Tip

Since UBIK 4.9 Release 10013, RepeateEveryMinutes is of type double.

Values below 1 are supported, such as 0.3 (18 seconds).

Own Implementation

You may implement your own client technology or API consumer.

The recommended reference implementation is UBIK.EnterpriseService.WebInterface.Client.

How to Extend the Web Interface

To add your own controllers:

1. Create a controller derived from System.Web.Http.ApiController.
2. Place the compiled assembly into the Enterprise Service Injection directory.

Example:

using System.Web.Http;

namespace PluginLibrary
{
    public class MyExtentionController : ApiController
    {
        [HttpPost]
        public void DoThingsWithObject(string param)
        {
            // Do things here
        }
    }
}

Configuring UBIK Enterprise Service

Since version 2.6.3, command files can be:

• Left untouched
• Renamed as processed
• Deleted after processing

The configuration key ConsoleRunMode controls how UBIK.Console is launched:

Since version 3.5.0, the following settings configure the Web Interface:

Since version 4.9.0, additional scheduling controls are available:

Configuration example:

<configuration>
  <appSettings>
    <add key="ConsoleRunMode" value="1" />
    <add key="CommandFileAction" value="0" />
    <add key="ClearWatchFolders" value="0" />
    <add key="ExecuteWebInterface" value="1" />
    <add key="WebInterfacePort" value="1" />
    <add key="WebInterfaceHost" value="1" />
    <add key="IdleSleepDurationMillis" value="100" />
    <add key="SleepDurationMillis" value="0" />
  </appSettings>
</configuration>

Command File Action

Defines what happens to a command file after processing.

If Mark or Delete is configured, the Enterprise Service queues unprocessed files found during startup and processes them one-by-one.

To avoid this behavior, clear the watch folders first, for example using:

ClearWatchFolders=1

Enterprise Service Task Execution Mode

For troubleshooting or special compatibility scenarios, the Enterprise Service can be run as a desktop task instead of a Windows Service.

To start it in task mode:

UBIK.EnterpriseService.exe -tray

A tray icon appears in the Windows notification area.

Right-clicking the icon allows the user to:

• Start
• Stop
• Pause
• Continue

Note

Running in task mode requires an active Windows user session.

Logging

For complex integration tasks, detailed logging is essential.

See Configuration Files → Logging Configuration for log target, retention and log-level configuration.

Log entries are often the best way to understand Enterprise Service execution behavior and diagnose problems.

Recommended Best Practices

• Add detailed logging in custom Enterprise Service code.
• Log critical decision paths and runtime-dependent behavior.
• Log missing or unexpected parameters.
• Use the Verbose log level for diagnostic information.
• Generate a large random identifier for each log entry to simplify locating the related source code later.
• Avoid maintaining manually incremented log identifiers.