OST documentation

1. Component diagram

Backend, frontend and database can be launched by one docker compose. Backend can connect with Testbed (Kafka) and with Keycloak (system to authorization).

2. User Manual

User can login to server as admin or observer. Admin can manage trials, session, stages, roles, add question to roles and stages, add and edit users and control active session. Observer can answer on question and comment it.

Admin

Goal of admin is creating working session for observers. This process contains three stages: creating trial with questions, creating roles and assign them to question set and preparing session with users. To create questions admin should create trial, stages in trial, question sets in stages and question in question sets. Description can be find in subsection named ,,Creating trial with questions". Second part is creating roles and assign them to question set (which already are assign to stage). It means, that question, which are available for observer, depends on stage and on role of logged observer. Last step is creating session with observers. Observers in other sessions can have other roles, so assignment user to role in session. Admin needn't create new users, if observers have their account in system. Description of this step can be find in subsection ,,Managing users and sessions".

Creating trial with questions

Trial list

If we choose "TRIALS" from launch window we will be redirected to Trial List.

There is a list of trials, which can be managed also we can upload after choosing "Import trial" button.

Trial details

After choosing trial from trial list and click edit or after double clicking left mouse button on trial from trial list, system redirects to trial details. There are basic details about trial and data about sessions, stages and roles in trial.

Also trial can be edited and removed there.

Stage details

After choosing stage from trial details and click edit or after double clicking left mouse button on stage from trial details, system redirects to stage details. There are basic details about stage, which can be edited. Also stage can be deleted by admin. Question set list of chosen stage is below basic stage details. You can redirect to trial by clicking trial name above save button.

Question set details

In question set details windows admin can change name or description also list of questions of this question set is shown. User can redirect to the chosen question by double clicking on question or clicking question and edit. You can redirect to trial or stage by clicking trial name or stage name above save button.

Question details

In question details admin can modify question, description or type of answer. Also admin can add new options of choice, show them or remove. In question details parameters like commented and required can be set. You can redirect to trial, stage or question set by clicking trial name, stage name or question set name above save button.

Question option can be add after saving question.

Creating roles and assign it to question set

Role details

After choosing role from trial details and click edit or after double clicking left mouse button on role from trial details, system redirects to role details. There are basic details about role, which can be edited. Also in role details we can manage of user assignment to role and question set, which should be show, when right stage is chosen. You can redirect to trial by clicking trial name above save button.

Managing users and sessions

Session details

New session can be created by clicking +New, when session window in trial detail is active.

After choose session from trial details and click edit or after double clicking left mouse button on session from trial details, system redirects to session details. There are basic details about session, which can be edited or deleted, also data from session can be downloaded. In the user role table admin can assign role to user in this session. User can answer on question only if session is active.

Session tracking details

After clicking session from launch window, system redirects to session tracking detail. In session tracking details admin can control active sessions. There are informations, which trial is currently used, if session is controlled by testbed or manually (manual column) and which stage is active at this moment.

User list

If we choosing "USERS" in launch window we will be redirected to User list. There are some basic data about user there.

User details

After choosing user from user list and click edit or after double clicking left mouse button on user from user list, system redirects to user details. There are basic details about user and data about sessions, stages and roles in trial.

Also user can be edited and removed there.

If we want to add new user, we should click +New on User list. Then system redirects to user detail and after filling data, system create new user. All fields are required.

Observer

Observer can login to server, when admin send him his login and password. After it he can login to system.

Question Set view

Observer after login to system can choosing from question set from active sessions (if question sets, during present stage in active session, are available to logged user).

Question view

Observer after choosing question set is redirected to questions from chosen question set. Observer can answer to question from this question set by writing text (textfield) or choosing option (checkbox, radiobutton, slider).

3. Deployment Manual

Download docker from https://www.docker.com/.
Create file and name it docker-compose.yml
Open this file and paste to this file text below:

version: 3
services:
  zookeeper:
    image: confluentinc/cp-zookeeper:latest
    hostname: zookeeper
    ports:
     - &quot;3500:3500&quot;
    environment:
      ZOOKEEPER\_CLIENT\_PORT: 3500
      ZOOKEEPER\_TICK\_TIME: 2000

  broker:
    image: confluentinc/cp-kafka:latest
    hostname: broker
    depends_on:
      - zookeeper
    ports:
      - &quot;3501:3501&quot;
    environment:
      KAFKA_BROKER_ID: 1
      KAFKA_ZOOKEEPER_CONNECT: zookeeper:3500
      KAFKA_ADVERTISED_LISTENERS: EXTERNAL://localhost:3501,PLAINTEXT://broker:9092
      KAFKA_LISTENER_SECURITY_PROTOCOL_MAP: EXTERNAL:PLAINTEXT,PLAINTEXT:PLAINTEXT
      KAFKA_LISTENERS: EXTERNAL://0.0.0.0:3501,PLAINTEXT://0.0.0.0:9092
      KAFKA_OFFSETS_TOPIC_REPLICATION_FACTOR: 1
      KAFKA_DEFAULT_REPLICATION_FACTOR: 1
      KAFKA_MESSAGE_MAX_BYTES: 100000000
      KAFKA_REPLICA_FETCH_MAX_BYTES: 100000000

  schema_registry:
    image: confluentinc/cp-schema-registry:latest
    hostname: schema\_registry
    depends_on:
      - zookeeper
      - broker
    ports:
      - &quot;3502:3502&quot;
    environment:
      SCHEMA_REGISTRY_HOST\_NAME: schema_registry
      SCHEMA_REGISTRY_LISTENERS: http://0.0.0.0:3502
      SCHEMA_REGISTRY_KAFKASTORE_CONNECTION_URL: zookeeper:3500
      SCHEMA_REGISTRY_KAFKASTORE_BOOTSTRAP_SERVERS: PLAINTEXT://broker:9092

  kafka_rest:
    image: confluentinc/cp-kafka-rest:latest
    hostname: kafka\_rest
    depends_on:
      - zookeeper
      - schema_registry
      - broker
    ports:
      - 8082:8082;
    environment:
      KAFKA_REST_HOST\_NAME: kafka_rest
      KAFKA_REST_BOOTSTRAP_SERVERS: PLAINTEXT://broker:9092
      KAFKA_REST_ZOOKEEPER_CONNECT: zookeeper:3500
      KAFKA_REST_LISTENERS: http://0.0.0.0:8082
      KAFKA_REST_SCHEMA_REGISTRY_URL: http://schema\_registry:3502&#39
      KAFKA_CONSUMER_REQUEST_TIMEOUT_MS: 30000
      KAFKA_REST_ACCESS_CONTROL_ALLOW_METHODS: GET,POST,PUT,DELETE,OPTIONS
      KAFKA_REST_ACCESS_CONTROL_ALLOW_ORIGIN: \*

  kafka_topics_ui:
    image: landoop/kafka-topics-ui:latest
    hostname: kafka_topics_ui
    depends_on:
      - kafka_rest
    ports:
      - 3600:8000;
    environment:
      KAFKA_REST_PROXY_URL: http://kafka\_rest:8082
      PROXY: "true" 

  kafka_schema_registry_ui:
    image: landoop/schema-registry-ui:latest
    hostname: kafka_schema_registry_ui
    depends_on:
      - schema_registry
    ports:
      - 3601:8000
    environment:
      SCHEMAREGISTRY_URL: http://schema_registry:3502
      PROXY: "true"

  postgres:
    image: postgres:9.6
    hostname: postgres
    environment:
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: postgres
      POSTGRES_DB: TRIAL_ADMIN
    volumes:
       - postgres-data:/var/lib/postgresql/data
_#  restart: unless-stopped_
 
  admintool:
    image: drivereu/test-bed-admin:latest
    depends_on:
      - postgres
      - broker
      - schema_registry
    ports:
      - 8090:8090;
    volumes:
      - ./admintool-config/gateways.json:/opt/application/config/gateways.json
      - ./admintool-config/solutions.json:/opt/application/config/solutions.json
      - ./admintool-config/topics.json:/opt/application/config/topics.json
      - ./admintool-config/standards.json:/opt/application/config/standards.json
      - ./admintool-config/testbed-solutions.json:/opt/application/config/testbed-solutions.json
      - ./admintool-config/testbed-topics.json:/opt/application/config/testbed-topics.json
      - ./admintool-config/configurations.json:/opt/application/config/configurations.json
    environment:
      KAFKA_BROKER_URL: broker:9092
      SCHEMA_REGISTRY_URL: http://schema\_registry:3502
      zookeeper_host: zookeeper
      zookeeper_port: 3500
      schema_registry_url: http://schema\_registry:3502
      testbed_secure_mode: DEVELOP
      testbed_init_auto: "false"
      management_ca_cert_path: http://localhost:9090
      cert_handler_url: https://localhost:8443
      cert_pem_handler_url: https://localhost:8443
      security_rest_path_group: https://localhost:9443
      security_rest_path_topic: https://localhost:9443

  afteractionreview:
    image: drivereu/after-action-review:latest
    depends_on:
      - postgres
      - broker
      - schema\_registry
    ports:
      - 8095:8095
    environment:
      KAFKA_BROKER_URL: broker:9092
      SCHEMA_REGISTRY_URL: http://schema_registry:3502
      zookeeper_host: zookeeper
      zookeeper_port: 3500
      schema_registry_url: http://schema_registry:3502

  pgadmin:
    image: fenglc/pgadmin4
    depends_on:
      - postgres
    ports:
      - 5050:5050
_#   restart: unless-stopped_

  time_service:
    image: drivereu/test-bed-time-service:latest
    depends_on:
      - broker
      - schema_registry
    ports:
      - 8100:8100
    environment:
      KAFKA_BROKER_URL: broker:9092
      SCHEMA_REGISTRY_URL: http://schema\_registry:3502
      AUTO_REGISTER_SCHEMAS: "true"

  large_file_service:
    image: drivereu/large-file-service:latest
    ports:
      - 9090:9090;
    environment:
      HOST: localhost
      PORT: 9090
 
  trial_management_tool:
    image: drivereu/trial-management-tool:latest
    depends_on:
      - broker
      - schema_registry
    ports:
      - 3210:3210
    environment:
      CLIENT_ID: TB-TrialMgmt
      KAFKA_HOST: broker:9092
      SCHEMA_REGISTRY: http://schema\_registry:3502
      TRIAL_MANAGER_SERVER_PORT: 3210
      PRODUCE: system_request_change_of_trial_stage,system_tm_phase_message,system_tm_role_player,system_tm_session_mgmt
      SSL: "false"
      SSL_PFX: certs/TB-TrialMgmt.p12
      SSL_PASSPHRASE: changeit
      SSL_CA: certs/test-ca.pem
    volumes:
      - trial-data:/app/trials
 
   ost_db:
     image: drivereu/ost_database
     ports:
       - 5437:5432
     volumes:
       - database-OST:/var/lib/postgresql/data
_#    restart: always_
  ost_web:
    image: drivereu/ost_frontend:without_keycloak
    links:
      - ost_api
    ports:
      - 127.0.0.1:85:80
      - 127.0.0.1:445:443
_#        restart: always_
  ost_api:
    image: drivereu/ost_backend:without_keycloak
    links:
      - ost_db
    ports:
      - 8080:8080
_#    restart: always_

  silent-producer:
    image: silent-producer
    depends_on:
      - broker
      - schema_registry
    environment:
      KAFKA_HOST: broker:9092
      SCHEMA_REGISTRY: http://schema_registry:3502
      PRODUCE_TOPICS: simulation_request_unittransport,simulation_request_startinject,simulation_entity_item,sumo_AffectedArea,standard_cap,system_timing,system_topic_access_invite

volumes:
  database-OST:
  postgres-data:
  trial-data:

Go back to the required folder.
If you are windows user
1.Press Shift + right click mouse button anywhere on the folder window (this folder must have file docker-compose.yml).
2.Choose open powershell
3.Write in terminal docker-compose up and press enter
If you are linux/ubuntu user
1.Press right click mouse button anywhere on the folder window (this folder must have file docker-compose.yml).
2.Choose open terminal
3.Write there docker-compose up and press enter
Congratulation, your application has been just turned on.

4. API

Get /api/answers

Api let us see answer of trial session including some text inside.

@RequestParam("trialsession_id") long trialSessionId,

@RequestParam("search") String text

Produces Json

** ** TrialUserDTO.ListItem user

        String Name

String observationTypeName

String observationTypeDescription

Get /api/answers/csv-file

    Api let us load CSV file with answers of session.

    @RequestParam(value = &quot;trialsession\_id&quot;) long trialSessionId

Return null

Delete /api/answers/{answer_id:\d+}/remove

Api let us delete answer.

@PathVariable(value = "answer_id") long answerId,

           @RequestParam(&quot;comment&quot;) String comment

Return null

GET /api/answers-events

Api let us see all answers and events in session of current user.

@RequestParam(value = "trialsession_id") long trialSessionId

Produces JSON

long id;

long observationTypeId;

String name;

String description;

ZonedDateTime time;

ZonedDateTime trialTime;

String type;

Get /api/event/search

Api returns list of events in session.

@RequestParam(value = "trialsession_id") long trialSessionId

Produces JSON

public String firstName;

public String lastName;

public String trialRoleName;

GET /api/observationtypes

Api returns list of question

sets

@RequestParam("trialsession_id") Long trialSessionId

Long answersId

String name

String description

GET /api/observationtypes/form

Api returns roles, which can answer on question set.

@RequestParam("observationtype_id") Long observationTypeId,

        @RequestParam(&quot;trialsession\_id&quot;) Long trialSessionId

Return json

List<TrialRoleDTO.ListItem> roles

JsonNode jsonSchema,

         where in roles are two variables:

          long id,

         String name

/api/observationtypes/admin/addNewQuestionSet

@RequestBody

String name

String description

long trailStageId;

long trailId;

boolean multiplicity;

boolean withUsers;

int position;

List<AdminQuestionDTO.ListItem> questions = new ArrayList<>();

** Return response with http status and json**

long id

String name

String description

long trailStageId;

long trailId;

boolean multiplicity;

boolean withUsers;

int position;

List<AdminQuestionDTO.ListItem> questions = new ArrayList<>();

GET /api/observationtypes/admin/getNewQuestionSet

Api let us get question set from chosen stage.

@RequestParam(value = "id") long id

** Return response with http status and json**

long id

String name

String description

long trailStageId;

long trailId;

boolean multiplicity;

boolean withUsers;

int position;

List<AdminQuestionDTO.ListItem> questions = new ArrayList<>();

PUT /api/observationtypes/admin/updateQuestionSet

Api let admin update question set.

@RequestBody

String name

String description

long trailStageId;

long trailId;

boolean multiplicity;

boolean withUsers;

int position;

List<AdminQuestionDTO.ListItem> questions = new ArrayList<>();

** Return response with http status and json**

long id

String name

String description

long trailStageId;

long trailId;

boolean multiplicity;

boolean withUsers;

int position;

List<AdminQuestionDTO.ListItem> questions = new ArrayList<>();

DELETE /api/observationtypes/admin/deleteQuestionSet
```
 Api let admin delete question set from a stage.
```

@RequestParam(value = "id") long id

Return response with http status and string

GET /api/questions-answers

Api returns data about answer and question.

@RequestParam(value = "answer_id") long answerId

@Produces JSON

     long answerId

    String name (of observatory type)

    String description (of observatory type)

    String time

    String trialTime

    JsonNode questionSchema

    JsonNode formData

     JsonNode trialRoles

POST /api/questions-answers/{answer_id:\d+}/comment

Api let observer add comment to answer.

@PathVariable(value = "answer_id") long answerId,

@RequestParam("comment") String comment

Return null

Get /api/trial-time

Api let us know server time.

Return String with date

Get /api/time-elapsed
```
 Api let us know local time.
```

Return String with date

GET /api/role

Api shows all roles in chosen trial.

        ** Return list of roles with:**

        long id

       String name

       String roleType

GET api/stages

Api shows all stages

      **  Return list of stages with:**

** ** long trialId

       String name

       LocalDateTime simulationTime

POST api/stages/admin/addNewTrialStage

Api let us add stage to chosen trial.

@RequestBody(

long id

long trialId

String name)

Return response with http request status and in body are:

Long trialId

Long id

String name

GET api/stages/admin/trialStageWithQuestions

Api returns stage with id

@RequestParam(value = "id") long id

Return response with http request status and in body are:

Long trialId

Long id

String name

LocalDateTime simulationTime;

List<AdminObservationTypeDTO.ListItem> questions = new ArrayList<>()

DELETE api/stages/admin/deleteTrialStage

Api delete a trial's stage.

@RequestParam(value = "id") long id

Return response with a http request status and a String

"Trial Stage id =" + id + " is deleted".

PUT api/stages/admin/updateTrialStage

Api update a trial's stage.

long id

long trialId

String name

Return

** long id**

** long trialId**

** String name**

GET /api/role

Api shows all roles in chosen trial.

        ** Return list of roles with:**

        long id

        String name

        String roleType

GET /api/trialsessions/{trialsession_id:\d+}

Api shows data about chosen trial session.

@PathVariable(value = "trialsession_id") long answerId

Return json with:

long trialId

String trialName

String trialDescription

String lastTrialStage

GET /api/trialsessions
```
    Api shows list of trial session.
```

Api shows all trials, which are available for logged user.

Return list of trials with:

long trialId

String trialName

String trialDescription

String lastTrialStage

GET /api/trialsessions/active

Api shows list of active trial session avaiable from logged user.

Return list of trials:

long trialId

String trialName

String trialDescription

String lastTrialStage

long initId

Boolean initHasAnswer

String name

PUT /api/trialsessions/{trialsession_id:\d+}/changeStatus

Api let us change status of trial session.

@PathVariable(value = "trialsession_id") long trialSessionId,

@RequestParam(value = "status") String status

Return null

GET /api/trialsessions/manual/{trialsession_id}/{is_manual}

Api let us choose if stages of trial will be change manually or automatically.

@PathVariable long trialsession_id,

@PathVariable boolean is_manual

Return String

"current stage in session " +trialSession.getId() + " is: " +trialSession.getLastTrialStage().getId() + "/"+trialSession.getLastTrialStage().getName()

            + &quot;  manual mode is &quot; +isManual

PUT /api/trialsessions

Api let change stage of trial session

@PathVariable(value = "id") Long trialSessionId,

@RequestBody @Validated TrialStageDTO.MinimalItem minimalItem,

Where minimalItem is json {id:value}

Return json

long trialId;

        Long lastTrialStageId;

LocalDateTime startTime;

LocalDateTime pausedTime;

POST /api/trialsessionscreateNewSessionFile

Api let administrator create new session users and create file with their usernames and passwords.

@RequestBody NewSessionForm newSessionForm,

Where newSessionForm is a json

{long trialId

String initialStage

String prefix

String status

List<UserForm> users}, where

UserForm is a json

{String email

List<String> role}

Return null

GET /api/trialsessions/trials

Api shows all trails, which current user is a session manager.

Return Map(Id : Long, name : String)

POST /api/trialsessionsnewSessionValues

Api returns data about trial.

@RequestParam(value = "trial_id") long trialId

Return trial node , in trial node we can find

trialStages, trialRoles, authUsers

POST /api/trialsession/admin/addNewUserRoleSession

Api let us add user to role in trial's session.

@RequestBody

long trialUserId

long trialRoleId

long trialSessionId

Return adminUserRoleDTO

DELETE /admin/deleteUserRoleSession

Api let us delete user from trial's session.

@RequestParam(value = "trialRoleId") long trialRoleId,

@RequestParam(value = "trialUserId") long trialUserId,

        @RequestParam(value = &quot;trialSessionId&quot;) long trialSessionId

** Return Response with http status and string "Trial user session is deleted"**

GET /api/ostAllQuestionsForMobile

Api returns data about questions set.

Return List<ObservationTypeDTO.SchemaItem>

List<Long> answersId

String name

String description

long id

List<TrialRoleDTO.ListItem> roles

JsonNode jsonSchema, where jsonSchema is schema of all questions in question set.

GET api/ostTrialId

Api returns id of Trial.

Return Long

GET api/ostTrialSessionId

Api returns id of Trial Session.

Return Long

GET api/ostTrialStageId

Api returns id of Trial Stage.

Return Long

POST api/admin/addNewTrial

Api let user create trial with name and default parameters

   private long trialIdString

    trialName

    String trialDescription

    String lastTrialStage

    private Boolean archived

Return json

** ** long trialIdString

    trialName

    String trialDescription

    String lastTrialStage

    Boolean archived

POST api/admin/updateTrial
```
 Api let edit trial.
```

Request Body AdminTrialDTO.ListItem

long trialId;String trialName

        String trialDescription

        String lastTrialStage

        Boolean archived

** Return json**

** ** long trialId

        String trialName

        String trialDescription

        String lastTrialStage

        Boolean archived

GET api/ostTrail

Api returns active Sessions and their actual stages.

RequestParam(value = "trial_name") String trialName

Return String of actual sessions and stages.

GET api/stages

Api returns stages of chosen session.

@RequestParam(value = "trial_id") long trialId, Pageable pageable)

Return PageDTO<** TrialStageDTO.ListItem>.**

In the json are:

long trialId

String name

LocalDateTime simulationTime,

long id.

GET api/user

    Api shows users in chosen trial session.

    RequestParam(value = &quot;trialsession\_id&quot;) long trialSessionId, Pageable pageable

** Return PageDTO<TrialUserDTO.ListItem>**

** ** In the json are:

        long id

        String firstName

        String lastName

GET api/user/version

    Api shows actual version of application.

** Return String**

POST api/questions/admin/addNewQuestion

Api let add question to question set.

@RequestBody

String name

String description

long observationTypeId

AnswerType answerType

int position

String jsonSchema

boolean commented

Return response with http status and json

** ** long id;

     String name;

    String description;

         long observationTypeId;

AnswerType answerType

         int position

         String jsonSchema

         boolean commented

GET api/questions/admin/getFullQuestion

Api let us get details about question.

@RequestParam(value = "id") long id

Return response with http status and json

** ** long id;

     String name;

    String description;

         long observationTypeId;

AnswerType answerType

         int position

         String jsonSchema

         boolean commented

DELETE api/questions/admin/deleteQuestion

Api let us delete question from question set.

(@RequestParam(value = "id") long id)

Return response with http status and string

"Question id =" + id + " is deleted"

PUT api/questions/admin/updateQuestion

Api let us update question.

@RequestBody

String name

String description

long observationTypeId

AnswerType answerType

int position

String jsonSchema

boolean commented

Return response with http status and json

** ** long id;

     String name;

    String description;

         long observationTypeId;

AnswerType answerType

         int position

         String jsonSchema

         boolean commented

5. Database

This database is used in OST system.

In this model ObservationType=Question Set.

Name		Name	Last commit message	Last commit date
Latest commit History 1,581 Commits
.gitlab/issue_templates		.gitlab/issue_templates
.idea		.idea
api		api
doc		doc
img		img
mobile		mobile
web		web
.gitignore		.gitignore
.gitlab-ci.yml		.gitlab-ci.yml
Documentation.pdf		Documentation.pdf
README.md		README.md

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

OST documentation

1. Component diagram

2. User Manual

Admin

Trial list

Trial details

Stage details

Question set details

Question details

Question option can be add after saving question.

Creating roles and assign it to question set

Role details

Managing users and sessions

Session details

Session tracking details

User list

User details

Observer

Question Set view

Question view

3. Deployment Manual

4. API

5. Database

About

Releases

Packages

Contributors 7

Languages

DRIVER-EU/ost

Folders and files

Latest commit

History

Repository files navigation

OST documentation

1. Component diagram

2. User Manual

Admin

Trial list

Trial details

Stage details

Question set details

Question details

Question option can be add after saving question.

Creating roles and assign it to question set

Role details

Managing users and sessions

Session details

Session tracking details

User list

User details

Observer

Question Set view

Question view

3. Deployment Manual

4. API

5. Database

About

Topics

Resources

Stars

Watchers

Forks

Releases

Packages 0

Contributors 7

Languages

Packages