How to set up a database for MaTaP

MATAP System Setup Guide

This document describes how to set up the MATAP system and its related components. It is intended as a step-by-step reference for administrators or engineers performing a new installation.

Recommended Setup Order

1. Install and configure the Webservice(s)
2. Configure the SQL Database
3. Verify access using Studio and AdminTool
4. Configure the Enterprise Service
5. Configure the Enterprise Orchestrator Service
6. Create scheduled jobs in Task Scheduler
7. Create multiple slots (optional)
8. Test access with client(s)

Required Plugins

The following plugins are needed for setting up MaTaP, these should be included automatically in your AdminTool package:

• UBIK.Interface.Module.Excel.dll
• UBIK.Interface.Module.Json.dll
• UBIK.Interface.Module.MaTaP.dll
• UBIK.Interface.Module.MRO.dll
• UBIK.Module.Push.dll
• UBIK.Interface.Module.iCalendar.dll
• NodaTime.dll
• Ical.Net.dll
• Portable.System.DateTimeOnly.dll
• Syncfusion.XlsIO.Base.dll
• Syncfusion.Licensing.dll
• Syncfusion.Compression.Base.dll

1. Webservice Setup

Purpose

The webservice hosts the MATAP application endpoints and provides the basis for slot-based deployment.

Required Services

• CONTENT
• PUSH
• USAM

These services are required for the system to function correctly.

Application Pools

Purpose

It is necessary to create a dedicated application pool for each slot. This is required to support the Recycle Application Pool functionality, enabling individual slots to be recycled after specific job executions.

Configuration Notes

Plugins
The plugins needed for the injection folder can be fetched from the AdminTool package.

AppSettings
Configure the AppSettings as usual for your environment.

Language Configuration
Set the LanguageID according to the required language. This should be done via the AppSettings of the CONTENT webservice. Currently the following are supported:

• English - 1
• German - 0

Slot Naming Convention

We recommend creating a folder named MATAP that contains all slot webservices. While this is not required for functionality, it helps to clearly separate these services from others. Each webservice should use the following naming convention:

C:\inetpub\wwwroot\MATAP
 \Slot01
  - CONTENT
  - USAM
  - PUSH
 \Slot02
  - CONTENT
  - USAM
  - PUSH
 \Slot03
  - CONTENT
  - USAM
  - PUSH
...

Do not deviate from this naming convention (Slot01, Slot02..) as this is necessary for the PUSH to work properly.

2. SQL Database Setup

Configuration

Connect to an empty Database via the UBIK.Studio and a SystemDefinitionsUpgrade window will appear where the highest version needs to be chosen for each component. After the SystemDefinitionsUpgrade the basic data structure for MaTaP is in the database.

Configure database settings

In the top left there is a tab called "Database" from where the Database settings window can be opened. The following settings need to be configured.

Data Path
Select a data path for your database.

Web Service Base Url
Enter the base URL of the web service. Example: If the URL to the content web service of Slot01 is eg. "https://dev.mycompany.net:888/UBIK/MATAP/Slot01/CONTENT/UBIKContent.svc" the base URL would be "https://dev.mycompany.net:888/UBIK/MATAP".

The MaTaP web services need to be structured in a certain way. The base URL/path can be chosen as liked. From there, a folder for every slot is needed and under each slot folder, there are the Content, Push and Usam folders containing the web service.

Customizing and ACM

The Customizing of the database needs to be build (F6) and released. The ACMs (MetaDefinitions) need to be build and released for each used slot context.

3. Enable Recycle App Pool Functionality

As the recycling of application pools must be performed via the AdminTool, additional configuration steps are required.

To do this, open the Application instance in the Bulk Editor using UBIK Studio. This instance can be found under the namespace: System.Matap.General The instance created by the MATAP plugin is named: APP_MATAP

Configuration of Properties

APPLICATION_POOL_NAME
As the name suggests, this property must contain the exact name of the corresponding Application Pool.

CONTENT_SERVICE_URL
This property should contain the URL path to the Content Webservice, like so: https://myserver:port/matap/slot01/CONTENT/UBIKContent.svc

4. Required Tools

UBIK Studio

Needed to initially set up the database and configure the necessary database settings (Check Point 2)

Plugins

The plugins needed for the injection folder can be fetched from the AdminTool package.

UBIK AdminTool

Needed to import and view the data and execute other calculations

Database Connection
To connect to the database, you can either configure it manually in AdminTool or import an .smconnection file which can be then provided to others as well. An example of such an .smconnection file is listed below.

.smconnection Example

<?xml version="1.0" encoding="utf-8"?>
 <DBSettingsProxy xmlns:i="http://www.w3.org/2001/XMLSchema-instance" z:Id="1"       xmlns:z="http://schemas.microsoft.com/2003/10/Serialization/"  xmlns="http://schemas.datacontract.org/2004/07/UBIK.SmartStudio">
   <AutoConnect>false</AutoConnect>
   <AutoSaveTime>-1</AutoSaveTime>
   <DataBase z:Id="2">YOUR DATABASE</DataBase>
   <DataSource z:Id="3">YOUR DATABASE SERVER</DataSource>
   <Language z:Id="4">en</Language>
   <Name z:Id="5">DATABASE NAME</Name>
   <Password z:Id="6">YOUR SQL PASSWORD</Password>
   <RecordLifeTime>10</RecordLifeTime>
   <RequestedPlugIns  xmlns:d2p1="http://schemas.datacontract.org/2004/07/UBIK.SmartModelling.UI.Environment.ViewModels" z:Id="7" z:Size="0" />
<User z:Id="8">YOUR SQL USER</User>
   <WindowsAuthentication>false</WindowsAuthentication>
 </DBSettingsProxy>

Notes

RecordLifeTime
Ensure that the RecordLifeTime is set to 10. If this value is not configured correctly, the refresh functionality in the AdminTool may not work properly when connected to the database.

Language
Set the language according to your project configuration. Supported options are:

• German (de)
• English (en)

5. Enterprise Service Setup

Folder Structure

• Create a copy of the Studio package and name the containing folder Enterprise
• Create a folder named json in it
• Create two files based on the the example MATAP.json and MATAP.PARAM.json below to the json folder and configure them accordingly

Configuration MATAP.json

{
   "RepeateEveryMinutes": 0.2,
   "SqlConnectionDefinition": {
   "SSPI": false,
   "SQLUser": "YOUR SQL USER",
    "SQLPassword": "YOUR SQL PASSWORD",
    "SQLServer": "YOUR SQL SERVER",
    "SQLInitialCatalog": "YOUR DATABASE"
},
"Tasks":
 [
		{
		   "ClassFullname": "UBIK.ServiceTask.Orchestration.ScheduledOrchestrator",
		   "MethodName": "Apply",
		   "MethodParameterPathFullName": "C:\\PATH\\Enterprise\\json\\MATAP.PARAM.json"   			
		}
   ]
}

Notes

RepeateEveryMinutes
No, RepeateEveryMinutes is not a typo – please don’t fix it otherwise it unfortunately won’t work.

Path to Json file
Ensure to escape the Backslashes!

Configuration MATAP.PARAM.json

{
   "InterfaceAdmin": "DDEAD266-7CB6-4894-A1CA-96E8FE81F510"
}

Configuration UBIK.EnterpriseService.config.exe

In order for the json files to be considered by the enterprise, the following changes need to be made in the respective Enterprise Service config:

<add key="PluginExecutionConfigPath" value="C:\Path\Enterprise\json\MATAP.json" />
<add key="ExecuteTaskByJsonFile" value="1" />

6. Enterprise Orchestrator Service Setup

• Create a copy of the Studio package and name the containing folder Enterprise_Orchestrator
• Create a folder named json in it
• Create three files, based on the examples RecalculateProjectJob.json, PublishCommissioningWallaper.json and RecycleAllAppPools.json below, save them to the json folder and configure them accordingly

Configuration RecalculateProjectJob.json

{
"SSPI": false,
"SQLUser": "YOUR SQL USER",
"SQLPassword": "YOUR SQL PASSWORD",
"SQLServer": "YOUR SQL SERVER",
"SQLInitialCatalog": "YOUR DATABASE",
"ClassFullname": "UBIK.MATAP.RecalculateProjectJobOrchestrator",
"MethodName": "Apply"        
}

Configuration PublishCommissioningWallaper.json

{
"SSPI": false,
"SQLUser": "YOUR SQL USER",
"SQLPassword": "YOUR SQL PASSWORD",
"SQLServer": "YOUR SQL SERVER",
"SQLInitialCatalog": "YOUR DATABASE",
"ClassFullname": "UBIK.MATAP.PublishCommissioningWallpaperJobOrchestrator",
"MethodName": "Apply"        
}

Configuration RecycleAllAppPools.json

{
"SSPI": false,
"SQLUser": "YOUR SQL USER",
"SQLPassword": "YOUR SQL PASSWORD",
"SQLServer": "YOUR SQL SERVER",
"SQLInitialCatalog": "YOUR DATABASE",
"ClassFullname": "UBIK.MATAP.RecycleAppPoolJobOrchestrator",
"MethodName": "Apply"        
}

Executables

Copy and paste the already existing UBIK.EnterpriseService.BasicClient.App.exe + the UBIK.EnterpriseService.BasicClient.exe.config so you have three each and name them the following:

• RecalculateProjectJob.exe & RecalculateProjectJob.exe.config
• PublishCommissioningWallpaperJob.exe & PublishCommissioningWallpaperJob.exe.config
• RecycleAllAppPoolsJob.exe & RecycleAllAppPoolsJob.exe.config

Notes

Ensure that the config ends with .exe.config, when copying and pasting the exe part sometimes gets removed which makes the config unusable.

Configuration RecalculateProjectJob.config.exe

<add key="PathToBasicEnterpriseServiceRequestJsonFile" value="C:\Path\Enterprise_Orchestrator\json\RecalculateProjectJob.json" />
<add key="PathToBasicEnterpriseServiceRequestJsonFileList" value="" />

Configuration PublishCommissioningWallpaperJob.config.exe

<add key="PathToBasicEnterpriseServiceRequestJsonFile" value="C:\Path\Enterprise_Orchestrator\json\PublishCommissioningWallpaperJob.json" />
<add key="PathToBasicEnterpriseServiceRequestJsonFileList" value="" />

Configuration RecycleAllAppPoolsJob.config.exe

<add key="PathToBasicEnterpriseServiceRequestJsonFile" value="C:\Path\Enterprise_Orchestrator\json\RecycleAllAppPoolsJob.json" />
<add key="PathToBasicEnterpriseServiceRequestJsonFileList" value="" />

Notes

It’s already defined in the configuration part but wanted to clarify that you must remove the content of the key PathToBasicEnterpriseServiceRequestJsonFileList, otherwise the value will be considered from the BasicClient exe.

Configuration UBIK.EnterpriseService.config.exe

In order for the BasicClient exe’s being executed accordingly, the following change needs to be made in the respective Enterprise config:

<add key="ExecuteWebInterface" value="1" />

7. Windows Task Scheduler

• Create three tasks for each job

Configuration Tasks

For each task you must point to the respective BasicClient exe which was created in the steps above. This can be done via the tab Actions in the Task Scheduler when creating a task. The needed action is Start a program and below the path defined to the respective exe.

Execution Order

The timing of the jobs must be adapted as needed for the project use case, usually we plan them for the night when no one is working. The only thing that needs to be considered is the sequence which is the following.

1. RecalculateProjectJob
2. PublishCommissioningWallpaperJob
3. RecycleAllAppPoolsJob

8. Multiple Slot Setup

If there is the need to create multiple slots for a project, some things must be considered. For each new slot webservice there is the need to create a new application, context and view. The respective MetaClasses for these can be found below.

Application Namespace

System.Matap.General.MATAPAPPLICATION

Note
Make sure to adapt the Application Pool Name and Content Service URL properties accordingly as described in point 3.

Context Namespace

System.Matap.General.MATAPCONTEXT

Note
No need to configure everything, just use the template view (CTX_MATAP_TEMPLATE) to derivate from it. Make sure to adapt to the correct slot in property SHOW_ON_WALLPAPER.

View Namespace

System.Matap.Content.MATAP_VIEW

Note
No need to configure everything, just use the template view (VIEW_MATAP_TEMPLATE) to derivate from it. Make sure to adapt to the correct slot in property SHOW_ON_WALLPAPER.

9. Access to Clients

The client installation packages can be provided either by our project engineers or developers responsible for the MATAP product.

Matap Desktop Client & Customizing

Currently we also provide the Desktop Matap client via the Microsoft Store. Make sure this client is fitting for your project use case by getting in contact with the development team. The XAML Customizing can be fetched from our Matap Repository depending on your project use case. Please get in contact with the development team to access them.

Matap Mobile Client & Customizing

As there is no specific Matap Mobile Client, you can just download the newest Xamarin or Maui version from either the Android Play Store or Apple Appstore. The XAML Customizing can be fetched from our Matap Repository depending on your project use case. Please get in contact with the development team to access them.