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

Configuration wizard

One of the possible options for configuring our services is to use our configuration wizard. It make basic configuration easier.

Configuration wizard will run automatically when configuration file wasn't found. Also is additional possibility to run configuration wizard by run application with the following parameter: 

1
$  --edit-config
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 aren't 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
34
35
36
routesWithXMAPrefix: true
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
checkService:
    enabled: true

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 alias 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 aren't 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. More info
statistics/enabled true/false
Path to these files must be included in config file as described above.


Field Description
checkService checkService configuration
checkService/enabled false / true

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: ""
...

Disabling /xMA prefix

Since version 3.0.24 you can disable /xMA route prefixing. In order to use this feature, set routesWithXMAPrefix to false in your xma's configuration.

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.