Skip to content

Changes from 3.1

Major difference in configuration files between 3.1 and 3.2 is that we no longer use JSON in favor of YAML file format.

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.yml** will be created. The necessary configuration of this file is possible in any text editor. On server machine those files should be already generated


Using quotes in config values

We recommend to miss quotes or use single quotes in config values, because those values are not interpreted. According to YAML specification, values which are surrounded with double quotes are interpreted, so it can cause errors during reading config values.


In the web-service-config.yml 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
loggerConfig:
    trimLogs: false
    maximumLogCharacters: 1000
    ansiColoring: true
statistics:
    enabled: true
databases:
    -
        rasServer: 127.0.0.1
        rasServerPorts:
            - 54332
        databaseServer: 127.0.0.1
        databaseName: testDB
        databaseAlias: ""
        userName: GSDWebService
        userPassword: ""
listeners:
    -
        type: HttpListener
        enabled: false
        port: 8080
    -
        type: Http2Listener
        enabled: false
        port: 8335
        serverKey: cert/key.pem
        serverCert: cert/cert.pem
    -
        type: HttpsListener
        enabled: true
        port: 8334
        serverKey: cert/key.pem
        serverCert: cert/cert.pem

the following items should be filled:

Field Description
databases/rasServer the server address where the remote access server is running
databases/rasServerPorts Array of ports the RAS is listening. When you have multiple ports then the first to respond will handle your request.
databases/databaseServer the server address where the database with GSDAPI module is located
databases/databaseName database name
databases/databaseAlias alias for database, default aliast should be empty
databases/userName Web user name, the default is "GSDWebService"
databases/userPassword Web user password, encrypted with MD5

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
statistics statistics configuration
statistics/enabled true/false
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
...
databases:
    -
        rasServerIP: 127.0.0.1
        rasServerPorts:
            - 54332
        databaseServerIP: 127.0.0.1
        databaseName: testDB
        databaseAlias: dbalias1
        userName: GSDWebService
        userPassword: ""
    -
        rasServerIP: 127.0.0.1
        rasServerPorts:
            - 54332
        databaseServerIP: 127.0.0.1
        databaseName: testDB2
        databaseAlias: dbalias2
        userName: GSDWebService
        userPassword: ""
...

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.