# Terminology
| A → | ← B |
|-------------------------:|-----------------------------|
| \[SOURCE\] | pake/logistiikka/rental |
| Tuntilaari | hourevent-datawarehouse |
| Tuntiferrari | aalto-tuntimersu |
| :hourglass_flowing_sand: | Requires re-calculation |

# User Story Template
## 0 User story header
Short description and/or example

### 0 Steps
- Step one
- Sub step / clarification
- Step two

# Common debug tips 'n tricks
Changes view

# User Stories

## 1 I need to add a new Client to Virtuaalitulkki :hourglass_flowing_sand:
Use the UI (once it's done)

## 2 Payroll asks for a new task addition :ok:
Use the UI (once it's done)
- Payroll usually provides the task id (in this user story: "1.7.1") whenever they ask for new task additions
- If it's not provided in the spec, just ask for it
- Add the provided task id to the appropriate place in `src/config/taskAdditions.ts`
- There are two properties in the `taskAdditions` object. `hourly` and `monthly`
- Payroll usually tells whether the additions should be payed for monthly and/or hourly workers
- Payroll usually also provides the wage code they want this addition to produce (in this user story: `WageCode.MuuLisa`). If not, ask them for it.
- If the wage code payroll is asking for does not exist follow the ["create new wage code"](#I-need-to-create-a-new-wage-code) instructions

{ task: "1.7.1", wageCode: WageCode.MuuLisa }

## 3 New allowance gets added to \[SOURCE\] Kellokortti :hourglass_flowing_sand:

## 4 I need to create a new wage code :ok:
> Payroll wants a new wage code Kotiarestilisä (code 96669)

Payroll wants a new wage code `96669`. Usually this happens when Payroll asks for new interpretations or requires new additions/allowances to be paid.

- Add the provided wage code to `WageCode` in `backend/src/services/tesInterpreter/types/wageEnums.ts`:file_folder:
- You get to translate the term payroll uses. In our example the wagecode `96669` has been referenced as "Kotiarestilisä", so we could name it to `WageCode.HouseArrestIncrease`

New WageCode additon in itself does not bring much. You also need to know the context in which the WageCode will be used in. If the WageCode represents a direct intepretation of work type value coming from tuntilaari hour entries, `HourTrackerWorkType` to `WageCode` mapping must be also done. A good starting point for this is `backend/src/services/tesInterpreter/getWageEntry.ts` and `backend/src/services/hourtrackers/types/kelloKorttiEnums.ts`

If the WageCode is used in tuntiferrari hour entries an additional mapping is needed for `FerrariWorkType` to `HourTrackerWorkType`.

## 5 New work type (tuntilaji) gets added to \[SOURCE\] Kellokortti :ok:
New work types are added to "tuntilaari" (repo is called hourevent-datawarehouse) codebase. Let's say the payroll has added a new work type for logistiikka kellokortti of `69` and it needs to be acknowledged in tuntilaari/virtuaalitulkki.

### 5.1 Steps in Tuntilaari
- Depending on which \[SOURCE\] is the target, e.g. `hourevent-datawarehouse/api/src/cron/mapper/logistiikka.mapper.ts`:file_folder:
- Find `hourEventMapping` and add to Map array:
- If work type does not need a new `HourEventType`: `[69, HourEventType.Work]`. Replace `HourEventType` enum to something appropiate for the specific work type (ask payroll)
- `[69, HourEventType.NewHourEventType]` add `NewHourEventType` to `HourEventType` enum
- New `HourEventType`s need to be handled in Virtuaalitulkki codebase

### 5.2 Steps in virtuaalitulkki

- If the `HourEventType` mapping exists, then nothing has to be done
- If the `HourEventType` is totally new
- Copy the new `Day/HourEventType` from Tuntilaari `Day/HourEventType` enum and paste it verbatum to `src/services/tuntilaari/types/laariTypes.ts` enum
- Then add a mapping from the new `LaariType` to `HourTrackerWorkType`, in `backend/src/services/hourTrackers/tuntilaari/laariTransformer.helper.ts`:file_folder: to `mapHourEventType` function.

    /*
     *  Here we're converting the enum strings from Laari to enum strings
     *  understood by Tulkki
     */
    export function mapHourEventType(type: HourEventType): HourTrackerWorkType {
        switch(type) {
            ...
            case HourEventType.NewHourEventType: 
                return HourTrackerWorkType.NewHourEventType
        }
    }
    

- Notice that if a new `HourTrackerWorkType` has been added, you need to define its wanted behaviour (e.g. is it considered work? Should this produce overtime? etc.) See [TODO: link](link)

## 6 New work type generates a new wage code :hourglass_flowing_sand:
Payroll wants to add a new work type that generates a wage code that doesn't exists in Tulkki

## 7 New customer through Tuntiferrari (aalto-tuntimersu) :ok:
Payroll wants to bring "Muumilaakso Oy" hours via Tuntiferrari. The hours are either already interpreted or they need to be interpreted with tulkki. The payroll provides you with an list of salary codes and absence codes that needs to be mapped e.g.

  salaryCodeMap: {
    "1001": "10004",
    "1310": "20020",
  },
  salaryCodeMap: {
    "11111": "232323",
    "55555": "434343",
  }

read the readme.md from aalto-tuntimersu repo: link [aalto-tunti-mersu-poc](https://gitlab.baronatechnologies.fi/virtuaalitulkki/aalto-tunti-mersu-poc)

### 7.1 Steps in Tuntiferrari (happy path)
- Add a new file called `muumilaakso-oy.ts` to `aalto-tuntimersu/src/csv_profiles`:file_folder:
- Look for an example implementation from existing files in this directory.
- Noninterpreted example: `aalto-tuntimersu/src/csv_profiles/gigantti.ts`:file_folder:
- Interpreted example: `aalto-tuntimersu/src/csv_profiles/dna.ts`:file_folder:
- If this addition of a new tuntiferrari customer brings in additional salarycodes or absencecodes that do not exist in Virtuaalitulkki, more steps needed.

### 7.2 Steps in Virtuaalitulkki
- a) Add a mapping

## 8 New salary code (tuntilaji) to an existing Tuntiferrari profile that maps to existing work type in virtuaalitulkki :ok:
Payroll wants to include a new salary code to an existing tuntiferrari profile.
> DNA Kauppa profile's CSV includes a new salary code "3031" that needs to map to standby wage code ("20303")

In an unlikely event that payroll informs that existing tuntiferrari profile has an additional salary code that has not already been included in `salaryCodeMap` object in its respective profile file (located in `src/csv_profiles/`:file_folder:), adding one might not be as straightforward as it might first appear to be.

### 8.1 Steps in tuntiferrari

Let's take DNA Kauppa profile as our example, tuntiferrari only needs one addition in `salaryCodeMap` object in `src/csv_profiles/dna-kauppa.ts`:

    salaryCodeMap: {
        ...
        "3031": "20303"
    }

`"3931"` is the salary code, `"20303"` is represents the wage code, which the aforementioned salary code gets mapped to.

We're not done however, as we still need to make changes in virtuaalitulkki's codebase.

### 8.2 Steps in Virtuaalitulkki

Here things become slightly confusing. While we map the new salary code to `"20303"` which we have made to represent the wage code we want DNA Kauppa's hours to be mapped to, it actually is treated as `HourTrackerWorkType` in virtuaalitulkki.

`backend/src/services/hourTrackers/ferrari/ferrari.helpers.ts`:file_folder:

export function parseHourTrackerWorkType(
  workType: string
): HourTrackerWorkType {
    ...
    case FerrariWorkType.Standby: // <- "20303"
      return HourTrackerWorkType.Standby; // <- "standby"
}

If you're lucky, this mapping is already present in `parseHourTrackerWorkType` function and no further additions are needed. In our example, `FerrariWorkType.Standby` is already being mapped to `HourTrackerWorkType.Standby` which ultimately maps to wage code that represents standby in virtuaalitulkki.

`backend/src/services/tesInterpreter/getWageEntry.ts`:file_folder:

export const getWageEntry = (hourEntry: NormalizedHourEntry, tes: Tes) => {
    ...
    case HourTrackerWorkType.Standby:
      return asWageEntry(
        hourEntry,
        isHourly(hourEntry.salaryType)
          ? WageCode.StandbyHourly
          : WageCode.StandbyMonthly,
        WorkType.Standby,
        tes
      ); 
}

## 10 Payroll asks for interpretation behaviour changes depending on shift :ok:
These requests only concern hour entries from the IT Kellokortti at the time of writing this document (2022-10-26).
E.g.

> Don't subtract lunch from evening shift

> Saturday-shift should produce some additions for the whole shift

### 10.1 Steps in Kellokortti
- Determine the "work time group" (FI: työaikaryhmä) of the shift
- You can get this from the payroll clercs
- Get the shift type ID from Kellokortti
- Go to app.kellokortti.fi/kirjaudu and login
- Open the menu in the top left corner
- Select `Työkalut > Henkilöasetukset > Työaikaryhmät`
- Find the work time group by name
- The filter icon disappears when you filter the results, but don't panic. It's just invisible :slightly_smiling_face:
- Click on the `Muokkaa` button for the work time group you're looking for
- Select `Työajat`
- Find the shift you're looking for and copy the `Työajan nro`. This is the ID you're looking for

### 10.2 Steps in Virtuaalitulkki
- Add a string representation of the shift to `RentalShiftTypes` enum in `rental.transformer.ts`:file_folder:
- Map the ID to the newly created string version in `parseShiftType()`
- :information_source: We do this to make it easier to see what shifts we have allocated to whom in the database. `ATEA_J_MONTHLY_EVENING_277` vs. `277`
- Now the shift can be found in the `HourTrackerTimeEntry` interface as `shiftType: string` and this can be used to change the interpretation behaviour in different places e.g. [adding a new lunch config](#I-want-to-add-a-new-lunch-configuration)

## 11 I want to add a new lunch configuration to a specific shift type :hourglass_flowing_sand:

## 12 I want to add interpretations for new TES :ok:
> A new TES has been added to S2 called "Rantavalvojan Paikallinen Sopimus" and employers of this specific tes has to be calculated in virtuaalitulkki. The hours come from kellokortti. Rantavalvojat adheres to HPL's TES but do not have lunch breaks.

Create a new file in `backend/src/config/interpretationRules/newRules` called `rantavalvojanTes.ts`

`backend/src/config/interpretationRules/newRules/rantavalvojanTes.ts`:file_folder

...
import { henkilostopalvelualanTesRules } from "./henkilostopalvelualanTesRules";

export const rantavalvojanTesRules: InterpretationRules = mergeWithParent(
    henkilostopalvelualanTesRules, {
        lunchConfig: {
          shouldSubtractLunch: false
    }
  });

Add a new rantavalvojanTes to `Tes` enum
`backend/src/services/tesInterpreter/types/wageEnums.ts`:file_folder:

export enum Tes {
    ...
    RantavalvojanTes = "rantavalvojanTes"
}

Add the new tes enum to `interpretationRules` record.
`backend/src/config/interpretationRules/newRules/index.ts`:file_folder:

...
import { rantavalvojanTesRules } from "./rantavalvojanTes";

export const interpretationRules: Record<string, InterpretationRules> = {
    ...
    [Tes.RantavalvojanTes]: rantavalvojanTesRules
}

`backend/src/services/tesInterpreter/interpreters/tesConfigs.ts`

export function determineTesForHourEntry(
  entries: HourEntryWithDuration[]
): HourEntryWithDuration[] {
  function getTes(timeEntry: HourEntryWithDuration) {
    // This calls the functions that were previously in the normalizeTimeEntries function
    const hourEntry = usePersonalTes(timeEntry)
      ? processPersonalTesForEntry(timeEntry)
      : timeEntry;

    // TODO: define the TES resolving function in the TES module
    switch (true) {
        ...
        case timeEntry.tes === Tes.RantavalvojanTes:
            return Tes.RantavalvojanTes
    }

## 13 I want to add a new TES that does not interpret hour entries :ok:
Usually the request goes along the lines of:
> "Please add a new no intepretation tes to Tulkki"

> "This Junaveturi TES doesn't get interpreted in Tulkki."

The TES name the payroll clercs provide is ususally the natural language name for the TES and 9 times out of 10 the string id for that is just kebab-case version that represents the natural language one. So "Junaveturi TES" could have an ID of `junaveturi-tes`

### 13.1 Steps
- Get the string ID from S2, e.g. `"collectiveIdRefId": "junaveturi-tes"`
- You can get this from the S2 team, currently no other way
- Add the string to the `NoInterpretationTesArray` in `./backend/src/services/tesInterpreter/types/wageEnums.ts`:file_folder:
- Deploy the changes

## 14 Interpretation is stuck, or Virtuaalitulkki is unresponsive :ok:
Interpretation state (`InterpretState` enum) is stuck in either `normalizing`, or `interpreting`, or server is unresponsive for other unkown reason. This usually can be fixed by restarting the server instance from AWS.

Payroll is usually communicating, that the interpretation has been stuck for a hot moment. This can be validated by the developer by going to the database and finding the `interpretation_record` table and finding the most recent row. If the `modified` column seem to have older than usual date time, and the state indeed does not update for a long time, it's usually a good idea to stop the server instance from AWS and let cloudformation restart. (TODO: link to a page that describes unresponsiveness in more detail)

### 14.1. Steps
- Log in to AWS
- Go to ECS dashboard, find Aalto cluster (e.g. "aalto-cluster-stage-EcsCluster-1EF6VC5WAEQVK")
- Find virtuaalitulkki service -> Tasks and find active running task
- Click "Stop" button on the top right corner of the page
- The service should auto-restart, this usually takes less than 5 minutes

## 15 Interpretation start date needs to be moved :ok:
This is something that we should do every time a new quinyx period starts and the data from the old period has been processed. Technically, this isn't something that **has** to be done, but smaller interpretation window equals faster processing times. Quinyx periods usually last for 13 weeks

### 15.1 Steps
- Depending on the environment
- Prod: Use `defaults.ts:defaults.kellokortti.firstDateToFetch`:file_folder:
- Stage: Use `defaults.json:defaults.kellokortti.firstDateToFetch`:file_folder:
- Demo: Use `demo.json:kellokortti.firstDateToFetch`:file_folder:
- Local: Use `local.json:defaults.kellokortti.firstDateToFetch`:file_folder:
- Update the value of `firstDateToFetch` to the new start date
- Deploy

## 16 I need to initiate re-calculation/reinterpretation :ok:
> Uudelleentulkitaan muutokset, ja viedään tuotantoon.

:information_source: Not to be confused with the procedure of "reinterpreting" existing, but incorrect wage entries.

This is usually done before release. Reinterpretation is done in staging environment. When reinterpretation is done, you'll make a release and deploy to production.

### 16.1 Steps
- Merge all changes to `develop`
- Wait for pipelines to pass
- Select `recalc_stage` from the final pipeline stage
- :information_source: `recalc_stage` (and for that matter; `recalc_demo`) nukes the environment's DB and reinterprets the hour entries from the specified interpretation window . This CI job also deploys the code changes.
- Wait for 2-6 hours and you're done
- If you need to get these changes into production, follow the instructions in [deploy to production](#TODO-link)

## Kellokortti entry has incorrect person ID

This causes the staffing contract not to be found in virtuaalitulkki.

Since Kellokortti doesn't register changing the person id as an update,
Laari doesn't get this information automatically.

There are two possible ways to solve this.
1) Change the incorrect IDs to correct ones by hand in the database
2) Initiate re-seeding in Laari for the erronous users

You usually want to use the second method, because the first one might cause issues when reprocessing has to be done in laari after the fact. You can consider the first option to be a temporary solution when the fix has to be done as fast as possible.

### Steps for re-seeding
- Make a POST request to tuntilaari

    curl --request POST \
      --url 'https://houreventdw.barona.fi/hours/seed/[START]/[END]?sources=[SOURCES]' \
      --header 'Authorization: Bearer [REDACTED]'

Where `[START]` and `[END]` is the timeframe where want to make the fix for. Where `[SOURCES]` is the kellokortti instance in which the hour entries are recorded. This request will run asynchronously, which means you should get a response saying the cron job has started, and you should keep an eye on the logs.
- You will see a log that the fetchHoursAndProcess has finished, and the re-seeding is done (e.g. `Finished fetchHoursAndProcess for ${start.toISOString()} - ${end.toISOString()} at: ${new Date().toISOString()}`)
- When the re-seeding is done, you need to either wait for virtuaalitulkki to interpret new hour entries, or initiate the request yourself.

### Steps for manual change
- Create connection to laari production database
- Open `hour_event` table
- Find the person which has the wrong `person_id` and manually change it to the correct one.
- ```sql
update hour_event set person_id = <CORRECT IF>
where person_id = <THE_WORNG ID>
and start_time >= <STARTING FROM>
and start_time <= <UNTIL>

- You need to either wait for virtuaalitulkki to interpret new hour entries, or initiate the request yourself.
    - It's better to use `https://virtuaalitulkki.barona.fi/interpret/person/:personId/:start/:end` to make the 

This will not remove the error caused by the incorrect person id and you will have to delete all erronous entries manually.

delete from periods
where hour_tracker_person_id = 'erronousId'

This will cascade and delete all erronous hour entries, wage entries, shifts and periods at once.


## 17 Virhe tilaussopimuksella

## 18 Virhe tuntimerkinnällä

## 19 Virhe tulkinnassa

## 20 Virhe tuntilajissa


## 21 Quinyx raportin lähetyspäivän muutos

## 22 


## 23 Uusi kohde + viite ja dimensiot :hourglass_flowing_sand:

## 24 I want to reset Tuntilaari