Installation

The xMA Web Service is available to download from a gsd-ma folder.

Requirements

Linux

  • 64 bits version

On Linux machine make sure that ma-web-service_Linux executable file has rights to execute

Windows

  • 64 bits version

DOCUframe

  • Remote Access Server (GSD Fernzugriff-Server)
  • Processing server (GSD Verarbeitungs-Server)

xMA Web Service Configuration

xMA Web Service configuration should begin with double installation of provided file **ma-web-service.exe**. After performing this procedure in the folder where the **ma-web-service.exe** is located, one configuration file **web-service-config.json** will be created. The necessary configuration of this file is possible in any text editor. On server machine those files should be already generated


In the web-service-config.json file: 

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
{
   "limitterConfig": {
    "enabled": false,
    "limitDBOpen": false,
    "limitDBExecute": false,
    "maxRequest": 1000,
    "timeFrameMS": 500000,
    "delayMs": 10
  },
  "rasServerIP": "127.0.0.1",
  "databaseServerIP": "127.0.0.1",
  "databaseName": "testDB0",
  "databaseAlias": "",
  "userName": "GSDWebService",
  "userPassword": "",
  "timeout": 900,
  "readTimeout": 30,
  "databases": [
  {
    "rasServerIP": "127.0.0.1",
    "databaseServerIP": "127.0.0.1",
    "databaseName": "testDB1",
    "databaseAlias": "test",
    "userName": "GSDWebService",
    "userPassword": "",
    "timeout": 900,
    "readTimeout": 30
  }
  ],
  "listeners": [
    {
      "type": "HttpListener",
      "enabled": true,
      "port": 8080
    },
    {
      "type": "HttpsListener",
      "enabled": false,
      "port": 8334,
      "serverKey": "cert/key.pem",
      "serverCert": "cert/cert.pem"
    },
    {
      "type": "Http2Listener",
      "enabled": false,
      "port": 8335,
      "serverKey": "cert/key.pem",
      "serverCert": "cert/cert.pem"
    }
  ],
  "clusterConfig": {
    "minWorkers": 1,
    "maxWorkers": 1,
    "workerTimeout": 600000,
    "maxPendingRequests": 100
  },
  "loggerConfig": {
    "severity": 0,
    "targetConfigs": [
      {
        "name": "console-target",
        "enabled": true
      },
      {
        "name": "file-target",
        "enabled": true,
        "logFileLocation": "log"
      }
    ],
    "truncate": true,
    "truncateSize": 500
  },
  "proxyConfig": {
    "proxyServerAddressWS": "ws://127.0.0.1:8081",
    "enabled": false
  },

}

the following items should be filled:

Field Description
rasServerIP the server address where the remote access server is running
databaseServerIP the server address where the database with GSDAPI module is located
databaseName database name
databaseAlias alias for database, default aliast should be empty
userName Web user name, the default is "GSDWebService"
userPassword Web user password, encrypted with MD5
databases table which contains additional databases configuration. Requests for such a database depend on the alias, for example alias will be "test" and request - "/test/xMA/default.aspx" instead of default database request - "/xMA/default.aspx" where the alias is empty.

Info

Fields which are shown below are not required and should be left as default.

Field Description
listeners array with listeners
listeners/type type of listener, Available listeners: HttpListener, HttpsListener, Http2Listener
listeners/enabled false / true
listeners/port port on which listener listens
listeners/serverKey key for server in *.pem file
listeners/serverCert certificate for server in *.pem file
clusterConfig responsible for launching the next thread after exceeding the specified number of request [ Deprecated. Will be removed in near future]
clusterConfig/minWorkers minimum number of threads
clusterConfig/maxWorkers maximum number of threads
clusterConfig/workerTimeout time after which the thread ends
clusterConfig/maxPendingRequests maxium number of pending requests
loggerConfig dispatch logs to console / file
loggerConfig/trimLogs false / true
loggerConfig/maxLogLength max logs length
loggerConfig/prettyPrint enables log coloring, if your logs do not color and contain strange characters then turn this option off
proxyConfig configuration of proxy server [ Deprecated. Will be removed in near future]
proxyConfig/proxyServerAddressWS proxy server address
proxyConfig/enabled false / true
limitterConfig configuration of requests throttling
limitterConfig/enabled false / true
limitterConfig/limitDBOpen does not concern xMA web service
limitterConfig/limitDBExecute does not concern xMA web service
limitterConfig/maxRequest does not concern xMA web service
limitterConfig/timeFrameMS time frame in ms
limitterConfig/delayMs delay of each subsequent requests in time frame
loginLimitterConfig does not concern xMA web service
In case of using HTTPS protocol instead of HTTP, certificate for server in *.pem file and key for server in *.pem file will be required. Path to this files must be included in config file as described above.


Connecting to more than one database

In order to connect with more than one database, you should configure additional database entries in `databases` array. Requests for such a database depend on the alias, for example alias will be "test" and request - `http://127.0.0.1/test1/xMA/default.aspx` instead of default database request - `http://127.0.0.1:8080/xMA/default.aspx` where the alias is empty. 
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
{
  "rasServerIP": "127.0.0.1",
  "databaseServerIP": "127.0.0.1",
  "databaseName": "testDB0",
  "databaseAlias": "",
  "userName": "GSDWebService",
  "userPassword": "",
  "timeout": 900,
  "readTimeout": 30,
  "databases": [
  {
    "rasServerIP": "127.0.0.1",
    "databaseServerIP": "127.0.0.1",
    "databaseName": "testDB1",
    "databaseAlias": "test1",
    "userName": "GSDWebService",
    "userPassword": "",
    "timeout": 900,
    "readTimeout": 30
  },
  {
    "rasServerIP": "127.0.0.1",
    "databaseServerIP": "127.0.0.1",
    "databaseName": "testDB2",
    "databaseAlias": "test2",
    "userName": "GSDWebService",
    "userPassword": "",
    "timeout": 900,
    "readTimeout": 30
  }
  ]
}

Service startup

The OpenSSL is required for the Web Service to work properly. Download and Install OpenSSL for Windows before starting Web Service. To run Web Service as a service, it is necessary to use external software. Recommended software is Non-Sucking Service Manager. To install the service, you need to go to the folder where the software NSSM is installed. Then hold down the CTRL+Shift keys, use mouse right click and from the context menu select position „Open command window here”. In the command window that opens, type the following command:

1
$ nssm install <service name>

Confirm by clicking the Enter button. This command opens the service editor dialog shown below:

Screenshot

In the editor dialog, you need to fill the path to the application that runs the project. The application name is net-api.exe. The second field is the path to the folder with net-api.exe file. The last field is the service name. Other settings should remain by the default. To install this configured service click „Install service” button.