Training Database Support Process

This article details how to report, escalate, and fix issues on Academy training databases.

Background

The Academy is a place to train people on how to use IMS. Trainees and Trainers work inside dedicated training databases rather than customer environments. There are two things to keep straight:

• Academy Template – a full, clean reference site/database kept in a known-good state. It comes pre-built with users (each with a role, discipline, and approval/visibility rights), units, plants, equipment, schedules, etc. We are consolidating everything into a single "All IMS" Academy Template that covers all modules (PEI, S-RBI, RBI 581, RCM, SIS, PLSS and Civil; FCM and TAT still to come).

• Training database (also called a "site") – a live database that Trainees actually use. There are roughly 10, each holding about 200 users per module (PEI is the busiest). Some databases are for e-learning, others for live training.

Two operations matter throughout this document:

• Upgrade – moving a database to a newer IMS version. Done on request (not on a fixed schedule), usually to fix a specific Bug.

• Refresh – re-imaging the Academy Template onto a database to reset it to clean, reusable users. A database and the Academy Template must be on the same version to refresh; therefore, a refresh typically includes an upgrade.

Version Policy

Training databases are deliberately kept one version behind the latest, so Trainers don't have to explain brand-new Bugs to Trainees. Because Support cannot fix a Bug unless the database is on a current version, upgrades are rolled out one database at a time and tested before the rest are upgraded.

The Key Idea

An issue can live in one of three places — in the IMS product, in the Academy Template, or in a single database. Most of the workflow below is about finding out which one, because that decides who fixes it and how. Before any of that, check whether the issue has already been reported: a duplicate ticket costs Support and the Product Owner a triage round each.

Workflow Diagrams

Workflow Overview Diagram

Workflow Detailed Diagram

Who Does What - at a glance

• Trainers – verify that the training database is ready for their upcoming training sessions, report issues to Academy Support, and help reproduce issues in IMS Main.

• Academy Support (Students) – own the issue end to end: triage, search for existing tickets, investigate, test on IMS Main and Academy Template, report Bugs & database/configuration issues, raise INFRA tickets, verify, and communicate.

• Technical Writers – fix outdated instructions in alignment with the Trainers.

• Product Owner + Software Engineers – fix confirmed product Bugs and ship them in a release.

• Support + Database Engineer – fix database-level/configuration issues.

• DevOps – run upgrades and refreshes from INFRA tickets.

• PKM Lead (Elsa) – triggers the triage process after a ticket is assigned to her and guides the process.

• Support Lead (Andrea) – guides the process.

For more detail refer to the Detailed Role Description below.

Workflow – Reporting and Fixing an Issue

Follow these steps in order. Each step narrows down where the issue lives.

1. Identify the issue. A Trainee, Trainer, or another user identifies an issue in a training database and reports it to Academy Support. Issues may be reported through various channels, such as the Academy Inbox or a ticket in YouTrack or Zendesk. If reported via a ticket, it should initially be assigned to the PKM Lead (Elsa), who will trigger the triage process and ensure it is assigned to Academy Support for investigation.

2. Triage (Academy Support). Decide what kind of issue it is:

   • Knowledge-related → explain to the Trainee what to do or ask the Trainer to help. Done.

   • Outdated instructions → ask the Technical Writers to update the material. Done.

   • Deploy issue → create an INFRA ticket for DevOps. When fixed go to Step 6.

   • Possible defect → continue to Step 3.

3. Check whether it is a known issue. Search through existing tickets before investigating further — a "new" issue is often a known one that has not reached the training database yet. Search all states, not just open tickets. Record for tickets matching the issue: ticket ID, title, state, Fix version, and affected version. Also take note of the training database's current version.

   • No match → record the search and continue to Step 4.

   • Match, still open or in progress → do not raise a new ticket. Comment on the existing ticket with the training database (name and full URL), its version, the e-Learning or session affected and its dates, and whether training is blocked so the priority can be re-agreed.

   • Match, fixed or delivered in a version later than the database's version → the fix exists but has not reached this database. Request an upgrade (INFRA ticket) referencing that ticket as the reason, then re-test. Go to Step 6.

   • Match, fixed or delivered in a version at or before the database's version → the fix should already be on this site, so a new ticket is needed. Continue to Step 4 and route it as normal; in the new ticket reference the existing ticket ID(s) and state that the fix was expected in version x but the behaviour still occurs on version y.

4. Check the training database version. Is it on the latest version?

   • Not on the latest version → the issue may already have been fixed in later versions, so test the same scenario on IMS Main. If the issue was identified by a Trainer, ask him to help reproduce it in IMS Main.

     • If the issue is on IMS Main → it is a genuine product Bug. Report the Bug and assign to the Product Owner. Wait for the fix to ship in a release, then request the upgrade of the affected databases. Go to Step 6.

     • If the issue is not on IMS Main → it may have been fixed in a later version. Request an upgrade of the training database, then re-test. If fixed go to Step 6, else go to Step 5.

5. Test on the Academy Template. If the issue is still present after upgrading (or the database was already current), check whether it also appears on the Academy Template. This would indicate that it is a database-level / configuration issue.

   • Present on the Academy Template → the issue belongs to the Template. Report the database-level / configuration issue against the Academy Template only and assign it to Support, who fixes and reports back; for genuine schema problems request help from a Database Engineer via an INFRA ticket. Every training database is re-imaged from the Template, so no local fix is applied to an individual database. When tested and fixed, request an upgrade and refresh of the affected training databases from the corrected Academy Template. Go to Step 6.

   • Not on the Academy Template (and not on Main) → the issue is specific to that database's structure. Report the database-level / configuration issue and assign it to Support, who fixes and reports back; genuine schema problems go to a Database Engineer. When tested and fixed go to Step 6.

6. Verify and communicate. Academy Support confirms that the issue is fixed and informs the Trainees and Trainer. Following a training database upgrade (for a live training session), the Trainer re-verifies the exercises (with automated tests planned for the future). Done.

Note

If a database is blocking training, move the affected Trainees to a different, working database while the fix is in progress.

Preparing for an Upcoming Training

1. The Trainer selects a site for the session, allowing enough lead time for an upgrade if one is needed.

2. The Trainer tests the exercises on that site.

3. If something doesn't work, start the workflow above — and, depending on the time available, select another site (often on a different version).

Detailed Role Description

The table below details roles and responsibilities of the people involved in the training database Support process.

Agreed Time Frames

Target time frames let us tell Trainers and clients when to expect a fix, and when to switch to another database instead of waiting.

For every confirmed issue, agree a priority and a target date so it can be communicated to the client; if it is urgent, apply mitigation (move Trainees) straight away.

Creating Issue Reports and Raising INFRA Tickets

Currently both Bugs and Database-level / configuration issues are reported in YouTrack. In future this will move to Zendesk / Azure — once it does, search both the new system and YouTrack for known issues, because older reports stay behind in YouTrack. Always search the tracker before reporting, and investigate before reporting — the more precisely you locate the issue, the faster it gets fixed.

Reporting a Bug

In addition to including all the information mentioned in the Issue Reporting Template, a Bug report should also include:

• Project (field) – IMSFeedback

• Type (field) – Bug*

• Assignee (field) – Product Owner*

• Explicitly mention that this was reproduced on IMS Main (this is what confirms it as a product Bug)

• If this issue was reported before – reference the earlier ticket ID(s), the version the fix shipped in, and the version the behaviour still occurs on

• If DE / TW was involved in investigation – Mention name and tag the person

Note

*If unsure flag it to Elsa / Andrea before setting the Type and Assignee.

Issue Reporting Template

A good issue report includes:

• Prerequisites - what is the context of the situation? Provide import file, specific device, methodology, roles of users or other information which may be relevant for reproducing the Bug.

• Steps - provide steps taken in the right sequence which led to the reproducing the Bug.

• What happens - what is the outcome of the steps taken?

• Expected - what is expected outcome of the steps taken? Is this expectation aligned with the IMS Handbook or other material which is describing expected result.

• URL - give the full URL of every training database or Academy Template mentioned, not just the site name, written as training12 (https://ims-training12.cenosco.software).

• Screenshot - provide screenshot of the outcome if possible. Preferably take screenshot of the entire screen to provide as much context as possible.

• Known issues checked - State either "no existing ticket found" or the related ticket ID(s) and their state. If a fix was expected in this version, say which version it shipped in and that the behaviour persists.

• Versions - the version of every environment mentioned: the affected database, IMS Main (with the date it was tested), and the Academy Template whenever the Template is part of the picture.

• Additional fields to fill:

  • Priority (field) – training is typically "Normal."

  • SLA Product (field) – methodology, like IMS_PEI.

  • Current Product Version (field) – when identified in IMS Main it will be the latest version.

  • Module (field) – like Schedules.

  • Subsystem (field) – similar to Module. May not always be applicable.

Also pay attention to write a clear title for the ticket - for more examples and information on reporting issues see Bug Guidelines.

Reporting a Database-level / Configuration Issue

When it was not possible to reproduce in IMS Main, then it is a database-level / configuration issue, and a Support ticket is typically created. In addition to including all the information mentioned in the Issue Reporting Template, an issue report should also include:

• Project – IMSFeedback*

• Type – Support**

• Assignee – Support Engineer (Alan)**

• Where it occurs – mention explicitly if the issue is present on the Academy Template, with its version. If not on the Academy Template (and not on IMS Main) then mention on which training database, with its full URL and version. Add the version of IMS Main the scenario was tested against, and the test date.

• Environment to fix – when the issue is present on the Academy Template, the ticket is for the Template only: every training database is re-imaged from the Template, so a local fix on one database is thrown away at the next refresh while the Template keeps reissuing the problem. Name the reporting database as the place it surfaced, and once the Template fix lands request a refresh of the affected databases. When the issue is not on the Template, the ticket is for that one database.

• If DE / TW was involved in investigation – mention name and tag the person.

Note

*In some cases when it is clear it is a deploy or other database-level issues that Support won't be able to solve, then an INFRA ticket can be created instead of an IMSFeedback ticket. In this case still include the information mentioned here and under the Issue Reporting Template.

**If unsure flag it to Elsa / Andrea before setting the Type and Assignee. For INFRA tickets leave empty (DevOps team will assign, unless otherwise agreed with the assignee).

Requesting an Upgrade / Refresh (Raising an INFRA Ticket)

INFRA tickets are created in YouTrack and ask DevOps to action a database. Specify clearly:

• Project (field) – INFRA

• Type (field) – NA

• Assignee (field) – Leave empty (DevOps team will assign, unless otherwise agreed with the assignee).

• Which database(s) to action – give the site name, full URL and current version, one per line.

• Action required – upgrade only, or upgrade and refresh (re-image from the Academy Template). Remember a refresh needs the Template on the same target version, so when the Template itself needs upgrading, say so explicitly and list both sites under the databases to action. When a refresh is requested, also request that a default password is set for all users (CIVXXX, PLSSXXX, RCMXXX, INSPXXX, SRBIXXX, RBI-XXX, and USER-XXX).

• Target IMS version – typically this would be the latest version.

• Reason – e.g. the Bug being fixed, or routine preparation for a training.

• Also required – ask DevOps to start the Calc Service on the database once the upgrade or refresh is complete. In case of an RBI 581training the R Service has to be started.

• Dependency – if a configuration change or Template-level fix has been requested on the Academy Template, the refresh depends on that work finishing first. Name the ticket reference.

• Timing – confirm no active training will be disrupted; coordinate with Academy Support and Trainers.