Skip to content

Installation

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

Requirements

Linux

  • 64 bits version
  • openssl

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
{
  "loggerConfig": {
    "trimLogs": true,
    "maximumLogCharacters": 300,
    "ansiColoring": true
  },
  "limitterConfig": {
    "enabled": false,
    "limitDBOpen": true,
    "limitDBExecute": false,
    "maxRequest": 10000,
    "timeFrameMS": 300000,
    "delayMs": 1
  },
  "rasServerIP": "127.0.0.1",
  "databaseServerIP": "127.0.0.1",
  "databaseName": "dbPath",
  "timeout": 9000,
  "readTimeout": 10000,
  "maxNumOfInstances": 15,
  "databaseAlias": "",
  "userName": "GSDWebService",
  "userPassword": "***",
  "databases": [],
  "listeners": [
    {
      "type": "HttpListener",
      "enabled": true,
      "port": 8080
    },
    {
      "type": "Http2Listener",
      "enabled": false,
      "port": 8335,
      "serverKey": "cert/key.pem",
      "serverCert": "cert/cert.pem"
    },
    {
      "type": "HttpsListener",
      "enabled": false,
      "port": 8334,
      "serverKey": "cert/key.pem",
      "serverCert": "cert/cert.pem"
    }
  ],
   "statistics": {
    "enabled": true,
    "salt": "",
    "publicKey": "./cert/encryption-pub.pem",
    "privateKey": "./cert/encryption.pem"
  },
}

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
loggerConfig dispatch logs to console / file
loggerConfig/trimLogs false / true
loggerConfig/maximumLogCharacters max logs length
loggerConfig/ansiColoring enables log coloring, if your logs do not color and contain strange characters then turn this option off
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
statistics statistics configuration
statistics/enabled true/false
statistics/salt salt
statistics/publicKey path to public key
statistics/privateKey path to private key
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

Windows

Since version 3.0.16

To run application as a service, we need to run run.service.bat (Web Service location) as administrator and answer for questions:
Do you want send statistic to GSD?[Y/N] - If you agree for sending statistic to GSD, we will be able to get better diagnostic information about possible WebService's problems and update licenses automatically.
Enter the service identifier [GSD-service-name(-yourId)] - If you want run more than one service on the system, you must add a unique ID for everyone. [default=GSD-service-name]

Linux/MacOS

Please refer to the guide here: https://docs.gsd.pl/restapi/information/installation/ under Linux/MacOS section.