qubership-virtual-secretary

Local development

To connect to the DB using DBeaver, use the following steps:

1. Select the H2 Embedded database type.
2. Go to "Driver settings/properties" -> "Libraries":

   1. Remove the existing driver (if any).

   2. Click "Add artifact".

   3. Paste the Maven declaration for H2 into "Dependency Declaration", i.e.:

      <dependency>
          <groupId>com.h2database</groupId>
          <artifactId>h2</artifactId>
          <version>2.2.224</version>
      </dependency>

   4. Apply settings.

3. URL = jdbc:h2:${CORRECT_PATH}\qubership-virtual-secretary\data\mapdb.db;CIPHER=AES
4. Enter the username.
5. Password field consists of two passwords: FILE_PASSWORD + one space + USER_PASSWORD.
6. Test connection.
7. Finish.

Note

It is recommended to set the DEBUG_ONLY_EMAIL_TO_SEND_MESSAGES property in the app.properties file, because messages will be sent via the Mattermost bot during application runtime. To avoid spamming everyone, send messages only to yourself. For this purpose, set your email address in the mentioned property. The email address will be used to identify your Mattermost account.

Setup

all-qs-members.json

List of team members to be notified is managed via the ALL_QS_MEMBERS secret. It must contain a JSON structure such as:

{
  "qubership-members": [
    {
      "email": "user1@example.com",
      "full-name": "FirstName1 LastName1",
      "lead-full-name": "LeadFirstName1 LeadLastName1",
      "lead-email": "lead1@example.com"
    },
    {
      "email": "user2@example.com",
      "full-name": "FirstName2 LastName2",
      "lead-full-name": "LeadFirstName2 LeadLastName2",
      "lead-email": "lead2@example.com"
    }
  ]
}

During the run, the content of this secret will be mounted into a local temp file, which is referenced in app.properties. See details in the ./.github/workflows/main.yml action file.

app.properties

Important

If you use Windows-style path delimiters, use escaped backslashes, i.e. c:\\temp\\my_prompt.txt.

version=1
MATTERMOST_HOSTNAME=mattermost.example.com
MATTERMOST_TOKEN=mattermost_secret_token
WEEKLY_REPORT_SHEET_ID=google_sheet_id
WEEKLY_REPORT_SHEET_NAME=Sheet1
WEEKLY_REPORT_API_KEY=google_sheets_api_key
WEEKLY_REPORT_START_DATE_MONDAY=YYYY-MM-DD
QUBERSHIP_TEAM_CONFIG_FILE=./all_qs_members.json
WEEKLY_REPORT_PROMPT_TEMPLATE_FILE=./weekly_report_prompt.txt
DB_USER_NAME=db_user_name
DB_USER_PASSWORD=db_user_password
DB_FILE_ENCRYPTION_PASSWORD=pass_to_encrypt_file_with_database
WEEKLY_REPORT_GOOGLE_FORM_URL=https://forms.gle/qwerty123
MATTERMOST_MANAGEMENT_CHANNEL_ID=abcde12345fghij67890klmno
# For GENAI properties use any OpenAI-compatible provider. Example for DeepSeek GenAI.
GENAI-URL=https://api.deepseek.com/chat/completions
GENAI-TOKEN=sk-deepseek-token
GENAI-MODEL=deepseek-chat

Properties description:

PROPERTY	DESCRIPTION
version	Informational property that may be printed in logs for troubleshooting.
MATTERMOST_HOSTNAME	Mattermost instance domain used by Virtual Secretary for notifications.
MATTERMOST_TOKEN	Mattermost bot token used by Virtual Secretary.
WEEKLY_REPORT_SHEET_ID	All results from the Google Forms questionnaire must be collected into a table in Google Sheets (see format below). Virtual Secretary will fetch user reports from the Google Sheet.
WEEKLY_REPORT_SHEET_NAME	Google Sheets sheet name to read data from.
WEEKLY_REPORT_API_KEY	Token generated by the Google Sheets API to allow access to Google Sheets.
WEEKLY_REPORT_START_DATE_MONDAY	Start date to process user reports from. All others are ignored. Useful when too many reports exist.
QUBERSHIP_TEAM_CONFIG_FILE	Reference to JSON file with list of team members to process. The Mattermost instance may contain a lot of users, but not all must be processed/covered by Virtual Secretary. Identification by email is used.
WEEKLY_REPORT_PROMPT_TEMPLATE_FILE	Path to the prompt template used for GenAI weekly report analysis.
DB_USER_NAME	All data (statistics) between runs is stored in the local database using H2. The DB user name is required and can be any simple string.
DB_USER_PASSWORD	Password for the database.
DB_FILE_ENCRYPTION_PASSWORD	Database file encryption password. The database file is stored in the repository and is checked out/committed back during the run. If you care about security, encrypt it additionally at the file-system layer.
GENAI-URL	OpenAI-compatible host used by GenAI for report analysis.
GENAI-TOKEN	Token used to authenticate with GenAI.
GENAI-MODEL	Model name used by OpenAI-compatible API.
WEEKLY_REPORT_GOOGLE_FORM_URL	All answers of the team must be collected into a Google Sheet in a special format; see details below.
MATTERMOST_MANAGEMENT_CHANNEL_ID	Mattermost channel ID used to publish the management summary report. If not set, the report is not sent to a channel and is printed to logs only.

Important

Weekly report prompt must contain a directive for GenAI to reply strictly in the following format (where X is a scalar):

{
  "scores": {
    "content_score": X,
    "impact_score": X,
    "proactivity_score": X,
    "context_score": X,
    "final_score": X.X
  },
  "analysis": {
    "content_justification": "text...",
    "impact_justification": "text...",
    "proactivity_justification": "text...",
    "context_justification": "text..."
  },
  "recommendations": {
    "strengths": ["strength 1", "strength 2"],
    "improvements": ["recommendation 1", "recommendation 2"]
  }
}

See com.netcracker.qubership.vsec.genai.GenAIResponseModel class for response model details.

Google Sheet format

The data comes in JSON with the following fields:

Field	Description
timestamp	Timestamp of the answer in the format dd.MM.yyyy HH:mm:ss. This field should be produced automatically when Google Forms exports data into Google Sheets.
blueStreamLead	Some identifier (enumeration) to understand which department the reporter belongs to. Currently optional; later intended for summary reports.
weekStartDate	The date (in format dd.MM.yyyy) to identify the week the report is created for.
completedWork	Text field: the report itself, to be analyzed with GenAI.
nextWeekPlans	Text field: currently optional.
email	Email to identify the reporter. It is recommended to enable authentication in Google Forms.

Summary results

Summary results are collected for the last 3 months and can be sent to the Mattermost channel (if set) or jsut printed into logs. The format is follow:

REPORTER	Week (past)	Week (closer)	Week ...	Week (now)