TIM-palveludokumentaatio

This documentation describes the architecture of the TIM system at application, hardware and functional level. The aim of the documentation is to clarify the functioning of the TIM system from the perspective of the service as a whole and to provide a basis for further development.

The content of the document is based on the documents produced during the 2021 TJTA1181 course.

TIM(The Interactive Material) is a material management system developed by the Faculty of Information Technology at the University of Jyväskylä, based on interactive material production. The system also includes a number of functionalities specific to learning management environments.

At the University of Jyväskylä, the system is used in particular for the production of learning materials and for course management. Compared to other environments used at the University of Jyväskylä, such as Optima, Moodle or Koppas, TIM offers its users the possibility of much more versatile and detailed development along the learning path.

The TIM system is presented from five perspectives:

• System Architecture, covering system architecture structure, software, functionality and interfaces;
• Hardware Architecture;
• Storage Solutions;
• Monitoring and Maintenance and;
• Service Requests.

Dokumentaatio on pyritty kirjoittamaan yleiskäyttöiseksi kuvaukseksi TIM-järjestelmästä. Tästä huolimatta jotkin dokumentaatiossa olevat asiat koskevat juuri Jyväskylän yliopistossa käytettävää TIM-järjestelmän asennusta. Tästä syystä tässä dokumentissa

• TIM-järjestelmällä viitataan yleisesti kaikkiin TIM-järjestelmän asennuksiin, ja
• JYU TIM -instanssilla viitataan Jyväskylän yliopistolla käytettävään TIM-järjestelmän asennukseen.

JYU TIM -instanssin käytänteet voi käyttää esimerkkinä muiden TIM-järjestelmien asennusten ylläpitämiseksi.

1. System architecture

In terms of system architecture, the TIM architecture consists of the software running in Docker containers, the servers, the software for running the system and the interfaces. The figure below shows a simplified TIM system architecture:

1.1 Containers

TIM leverages the Docker container technology and on top of that TIM is structured as a set of lightweight virtual machines, or containers, with their own interfaces. The TIM system software is packaged in image packages from which Docker automatically creates containers to run. The TIM system is split into multiple containers to improve isolation between programs and to facilitate maintenance.

The containers in a TIM system can be roughly divided into five types:

• The main container, or TIM container, is where the TIM server implementation runs. The containers communicate with the TIM container in such a way that TIM sends requests to the containers for the desired action. For the most part, all containers communicate only through the TIM container.

• Plug-incontainers, which contain plug-ins to materials written in the TIM system. TIM provides services for the various plug-ins, such as a method to register for TIM. The plug-ins depend on TIM and need their host application to function. These include, for example

  • stack: provides STACK plugin,
  • csplugin: provides csplugin-plugin

• External containers, through which additional services can be provided to the user, e.g. tools for mathematical modelling or visualisation. In addition, a few external containers provide services to the main container, such as a database and a cache. The library of software packages contained in the associated containers is very large and has virtually unlimited flexibility and extensibility. These include, for example:

  • postgreqsl, running PostgreSQL database software,
  • dumbo, providing Pandoc document compiler over a REST interface

• Runtimecontainers, which other containers can create while the TIM system is running. For example, a csplugin container creates new csplugin containers whenever a program is run through the container, after which the container disappears.

• Test containers that are only used for automated testing. Test containers are not in production.

There are 20 containers in use at run time in the TIM system, but run-time containers can momentarily increase the number of containers that can be run. All standard container definitions can be found in the docker-compose.tmpl.yml file in the TIM system:

tim-jyu/tim:cli/templates/docker/docker-compose.tmpl.yml

This file is the base file; the contents are used to create the actual docker-compose.yml based on the installer’s settings.

1.1.1 Tärkeimmät ulkopuoliset kontit

Alla on kuvattu joitain tärkeimmät ulkopuoliset kontit, jotka tarvitaan pääkontin toimintaa varten.

• caddy-kontti ottaa Caddy-ohjelmalla käyttäjän selaimesta tulevia HTTP-pyyntöjä vastaan ja välittää ne muille konteille. Kontti välittää suurimman osan pyynnöistä TIM-kontille, jossa pyörii gunicorn-palvelin, joka käsittelee niitä ja välittää TIM-järjestelmän palvelinpuolen koodille käsiteltäväksi.
• dumbo-kontti muuntaa TIM-järjestelmään kirjoitettujen materiaalien markdown-kielellä kirjoitetun tekstin HTML- tai PDF-muotoon.
• postgres-konttiin tallentuu lähes kaikki TIMin tiedot PostgreSQL-tietokantaan.
• redis-kontissa ajetaan KeyDB-välimuistipalvelin, johon TIM-kontti tallentaa väliaikaista tietoa, kuten materiaalien esikäännetyt HTML-tiedostot. KeyDB on puolestaan Redis-välimuistipalvelimen forkki, joka parantaa tietojen varastointi- ja kyselynopeutta moniajoympäristöissä. TIMissa käytetään monin pakoin termiä redis historiallisista syistä.

1.2 Ohjelmat

The TIM system uses a variety of software inside and outside the containers . At the time of writing, the software used by the TIM system is shown in the table below.

The table has a filtering and search feature.

Ohjelmalistauksessa versionumero on suuntaa antava ja ollut käytössä dokumentin tekohetkellä. Ohjelmien tämänhetkiset versiot voi katsoa Docker-konttien asennuspakettien konfigurointitiedostoista:

• TIM: TIM-imagen Dockerfile
  
• csPlugin: csPlugin-imagen Dockerfile
  
• STACK: STACK-imagen Dockerfile
  
• Haskell-plugins: haskellplugins-imagen Dockerfile

1.3 Rajapinnat

The interfaces allow integration with the software and allow requests to be made to the software from which data is to be retrieved or imported. The TIM system uses various interfaces for both communication between containers and between external systems and the TIM system.

The exchange of messages within the TIM system is called internal interfaces. Internal interfaces are used to communicate between containers over a closed Docker virtual network. In turn, the external interfaces of the TIM are used to connect to external services, without which the TIM can operate and which themselves operate without the TIM. Unlike internal interfaces, communication on external interfaces is secured by a secret key or IP lock.

1.3.1 Sisäiset rajapinnat

The REST interface is mainly used for exchanging information between containers. REST (Representational State Transfer) is an architectural model for implementing programming interfaces based on the HTTP protocol. The REST interface is primarily used for communication between plugins and the TIM container. The exact protocol between the TIM container and plugins is documented in the Plugin spec.

RESP-protokolla toimii TIM-palvelimen ja Redis-palvelimen rajapinnassa. RESP on eräänlainen serialisointiprotokolla, joka tukee seuraavia tietotyyppejä: yksinkertaisia merkkijonoja (Simple Strings), virheitä (Errors), kokonaislukuja (Integers), bulkkijonoja (Bulk Strings) ja taulukoita (Arrays).

SQL-protokolla, joka on myös kyselykieli, toimii TIM-palvelimen ja PostgreSQL-tietokannanhallintajärjestelmän rajapinnassa. SQL:n avulla yhdistytään tietokantaan ja sillä toteutetaan tietokantakyselyt ja erilaiset muutokset tietokantaan.

Celery-protokolla toimii Redis-palvelimen ja Celery-palvelimen rajapinnassa. Celery on Python-pohjainen tehtäväjono-ohjelmistopaketti ja Redis toimii eräänlaisena välimuistina. Redis-palvelin tallentaa viestit, jotka ovat kotoisin ohjelmakoodista ja niissä kuvataan, että työ tulee laittaa Celeryn tehtäväjonoon. Redis toimii myös Celeryn tehtäväjonosta tulevien tulosten varastointina, jotka sitten jonon kuluttajat noutavat. Celery-protokolla toimii tässä siis viestinvälittäjänä ja se on kirjoitettu Pythonilla, mutta protokolla voidaan toteuttaa millä tahansa kielellä.

1.3.2 Ulkoiset rajapinnat

REST/HTML-selainrajapinnan avulla käyttäjän selain keskustelee TIM-palvelinkontin kanssa. Tämä rajapinta on tarkoitettu vain käyttöliittymälle erilaisiin toiminnallisuuksiin, kuten lohkojen lisäämiseen ja editointiin ja kommenttien lisäämiseen. Melkein jokainen käyttöliittymän vuorovaikuttava toiminnallisuus tekee jossain kohtaa REST-rajapinnan kutsun palvelimeen.

SMTP on TCP-pohjainen protokolla, jota käytetään viestien välittämiseen eri sähköpostipalvelimien kesken ja sen käyttöön on varattu portti numero 25. TIMin käytössä oleva ulkopuolinen SMTP-palvelin on yliopiston oma. SMTP on siis oikeasti protokolla, mutta se voidaan nähdä rajapintana. Rajapinta on siis se, kun SMTP-palvelin mahdollistaa sähköpostin lähetyksen.

Sisun SCIM-rajapintaa (System for Cross-domain Identity Management) käytetään kurssien ryhmätietojen synkronointiin Sisun kanssa. SCIM-rajapinta keskustelee REST-rajapinnan kautta eli se käyttää puhtaita HTTP-kutsuja.

Sisun REST-rajapintaa käytetään mm. arvosanojen kirjaamiseen, johon ei siis käytetä SCIM-rajapintaa.

Hakan SAML-rajapinta (Security Assertion Markup Language) tekee mahdolliseksi käyttäjien kirjaamisen TIMiin yliopistotunnuksella. SAML on tietojärjestelmien käyttäjien valtuuttamiseen ja tunnistamiseen liittyvien tietojen jakamiseen tietoverkossa keskittyvä standardi. Teknisesti katsottuna SAML on XML-standardi ja siihen liittyy tietyt rajapinnat, jotka Haka ja TIM tarjoavat. Nämäkin on toteutettu käytännössä REST-rajapintana.

OAuth2-rajapinta on käytössä käyttäjien tunnistamiseen ulkoisissa järjestelmissä TIMin avulla. OAuth2 on laajassa käytössä oleva protokolla ja rajapinta, jonka avulla käyttäjä voi antaa ulkoisille järjestelmille lupaa vuorovaikuttaa tunnistautumista vaativien resurssien kanssa. TIM tarjoaa seuraavat resurssit ulkopuolisille järjestelmille rajapinnan kautta:

• Käyttäjän käyttäjätunnus
• Käyttäjän sähköpostiosoitteet
• Käyttäjän koko nimi

Tällä hetkellä nämä tiedot voidaan käyttää käyttäjän sisäänkirjaamiseen ulkoisiin järjestelmiin.

JSON/CSV -rajapintaa voidaan käyttää erilaisen määrämuotoisen tiedon hakemiseen tai syöttämiseen TIM:iin. JSON on yksinkertainen avoimen standardin tiedostomuoto, jolla välitetään ja tallennetaan tietoa. Se perustuu JavaScriptiin, mutta on siitä riippumaton. JSON on kieli, muttei ohjelmointikieli. JSON:ia käytetään, kun dataa lähetetään palvelimelta verkkosivulle. CSV taas on yksinkertainen tiedostomuoto, jota käytetään taulukkotietojen, kuten laskentataulukon tai tietokannan, tallentamiseen. CSV-muodossa olevat tiedostot voidaan tuoda ja viedä ohjelmiin, jotka tallentavat tietoja taulukoihin, kuten Microsoft Excel tai OpenOffice Calc. CSV lyhenne tulee siitä, että se tarkoittaa “pilkuilla erotettuja arvoja”.

2. Laitearkkitehtuuri

TIM-järjestelmää voi ajaa monipuolisilla palvelimilla. Yleiset järjestelmävaatimukset tuotantokäytölle ovat:

• Docker 19.03 tai uudempi
  • Kernelin ja tiedostojärjestelmän tuettava Dockerin overlay2-ajuria (xfs:n tapauksessa oltava d_type=true)
• Levy: SSD, min. 16 GB
  • Suositus: min. 0,5 TB
• RAM: min 2 GB + min. 2 GB jokaista 100 aktiivista samanaikaista käyttäjää (esim. koe, liveluento) kohden
  • Jos käyttö ei ole samanaikaista, voi pärjätä pienemmällä
  • Suositus: min. 8 GB + 4 GB jokaista 100 aktiivista samanaikaista käyttäjää kohti
• CPU: min. 8 ydintä
• Internet-linkki: min. 1 Gbps

Jyväskylän yliopistossa käytettävä laitteisto ja arkkitehtuuri on kuvattu erillisessä dokumentissa: Jyväskylän yliopiston TIM-asennuksen arkkitehtuuri.

3. Storage solutions

The database services for the TIM system are provided by a PostgreSQL server running on in its own Docker container. In turn, documents written to the TIM system, their edit history and attachments are stored as normal Linux files.

In addition, the JYU TIM instance leverages a failover and backup services to ensure the system is up and running.

3.1 Storing data

3.1.1 Database

Most of the data in the TIM system is stored in the PostgreSQL relational database. This data includes users, user groups, responses to tasks, document and folder metadata (name, location, permissions) and settings.

The relational tables in the relational database are defined programmatically in the source code of the main container using the SQLAlchemy library. The names of all relations are listed in the tim_app.py file.

3.1.2 Documents and editing history

Documents and editing history are stored as files directly in the file system. By default, these files are stored in the folder timApp/tim_files.

All documents consist of blocks, which are separate files. Block files contain JSON data with at least an identifier (id), raw content (md) and a check value (t). If a block is modified, a completely new file is created.

In turn, documents are files, listing the identifiers and check values of the associated blocks in order. If two blocks in a document are changed, a completely new file is created with its own version number. Document edit transactions are stored in a separate changelog file. The old files are always preserved, so the full history of exists.

The folder and file structures of documents and blocks are described in more detail in ’s own document:

Introduction to TIM development - Documents

3.1.3 Liitetiedostot

TIMissä liitetiedostot tallennetaan levylle normaaleina Linux-tiedostoina. Mikäli ne ovat suurempia tiedostoja, kuten tehtävien palautuksia PDF-muodossa, käytetään GhostScript-ohjelmaa pakkaamaan tiedostot pienemmiksi tilan säästämisen vuoksi.

Liitetiedostoista tallennetaan tietokantaan tieto, mistä tiedostopolusta liitetiedosto löytyy, sekä tiedot kaikista dokumenteista, joihin liitetiedosto on liitetty. Liitetiedostojen käyttöoikeuksia hallitaan tietokannan puolella.

3.2 Varmuuskopiointi

Oletuksena TIM-järjestelmä ei tee varmuuskopioita automaattisesti. Tätä varten kuitenkin on olemassa prosessia helpottavia skriptejä GitHub-projektissa. Alla kuvataan olennaiset varmuuskopioitavat tiedot, suositeltavat ohjelmat ja JYU TIM -instanssin varmuuskopiointikäytänteet esimerkinomaisesti.

Tietokannan varmuuskopiointi onnistuu tekemään PostgreSQL:n pgdump-ohjelmalla. Tätä varten TIM-järjestelmän lähdekoodissa on valmis postgre_backup.sh -skripti. JYU TIM -instanssissa tietokanta varmuuskopioidaan tunnin välein. Lisäksi viikkoa vanhat varmuuskopiot poistetaan JYU TIM -instanssilta postgre_backup_rotate.sh-skriptillä. Tämä tehdään tilan säästämiseksi, ja koska instanssilla ajetaan snapshot-varmuuskopiot.

Itse tiedostojärjestelmän varmuuskopiointi tehdään JYU TIM -instanssilla rsync ja scp -ohjelmilla. Varmuuskopiointi tehdään koko JYU TIM-instanssin pääkansiosta, johon sisältyy timApp/tim_files-kansio, sekä tietokannan varmuuskopiokansiosta. Nämä snapshotit tallennetaan kahteen paikkaan:

• tiedekunnan backup-järjestelmään joka vuorokausi 30 vuorokauden ajaksi sekä kuukausittain 24 kuukauden ajaksi,
• JYU TIM -instanssin varmuuskopiointipalvelimelle joka vuorokausi 730 vuorokauden (n. 2 vuotta) ajaksi.

JYU TIM -instanssin varmuuskopiointipalvelimelle varmuuskopioidaan myös kaikki JYU TIM -instanssin sivupalvelut (sähköpostilistapalvelin, kehityspalvelimet) samalla rotaatiolla (joka vuorokauksi 730 vuorokaudeksi).

3.2.1 Palautustavoitteet JYU TIM -instanssilla

JYU TIM -instanssilla

• RPO (Recovery Point Objective) kuvaa, kuinka pitkältä ajalta tietoa voidaan pahimmillaan menettää häiriön sattuessa. JYU TIMin tilasta tehdään varmuuskopio kerran päivässä. Varmuuskopiosta palautetaan siis enimmillään 24h päästä versio häiriön tapahduttua.

• RTO (Recovery Time Objective) kuvaa, kuinka nopeasti järjestelmä voidaan palauttaa häiriötilanteesta. JYU TIM -instanssilla tämä aika on täysin riippuvainen työvoiman saatavuudesta, varsinkin työajan ulkopuolella. Jos sitä ei pystytä välttämättömien tapauksien (esim. pääsykokeiden) takia tekemään välittömästi, se on noin 15 min. Ajan myötä tavoitteena on laskea tämä aika noin minuuttiin järjestelmän kahdennuksen myötä.

4. Monitorointi ja ylläpito

The monitoring and maintaining of the TIM system is partially automated. There is no single central interface for these activities, which are performed mainly by running commands on the TIM server. The testing of the TIM system is done both by automation testing and by functional testing.

In the JYU TIM instance, the administrators are responsible for monitoring the servers. The load levels on the servers’ processors are monitored through random checks. There are no daily or monthly maintenance procedures defined for the servers to check their condition. Any problems are addressed when they are detected, e.g. in case of system malfunctions.

4.1 Monitorointityökalut

4.1.1 Lokitiedot

TIM-järjestelmän eri Docker-kontit keräävät omia lokeja. Docker-konttien lokit voi lukea komennolla

./dc logs -t -f kontin_nimi

missä kontin_nimi on tarkasteltavan kontin nimi. Nämä lokit voi tarkastella ja analysoida muilla ohjelmilla, esimerkiksi grep-hakuohjelmalla.

TIM-järjestelmän jotkin kontit tallentavat lokinsa suoraan tiedostoihin tarkempaa analysointia varten. Nämä lokit tallennetaan tim_logs-kansioon, jonka sijainti on säädettävissä (esim. JYU TIM -instanssilla se on /extra/tim_logs). Nämä lokit ovat

• pääkontin loki (timLog.log), joka tallentaa pääkontille tulleet HTTP-kutstut, sekä palvelimen erilaiset tapahtumat, varoitukset ja virheet. Loki toimii tapahtumalokina, sillä kutsujen yhteydessä näkee käyttäjätunnukset, IP-osoitteet, sekä kutsun keston. Lokit voi analysoida grep tai glogg-ohjelmilla.
• caddy-kontin lokit (caddy-kansio), joka tallentaa kaikki TIM-instanssin ulkopuolelta tulevaa liikennettä. Lokit voi analysoida goaccess-ohjelmalla.

4.1.2 Uptime-monitorointi

TIM-järjestelmän tilaa seurataan healthcheck.sh-skriptillä. Skripti lähettää minuutin välein HTTPS-pyynnön TIM-palvelimelle tarkistaakseen, onko tämä pystyssä. Jos TIM-palvelin ei vastaa pyyntöön, lähettää skripti automaattisesti sähköpostin TIM-järjestelmän ylläpitäjille.

Pyynnöt tehdään kerran minuutissa, mikäli palvelin vastaa. Joka kerta, kun palvelin ei vastaa pyyntöön, pidennetään aikaväliä minuutilla.

JYU TIM -instanssilla skripti ajetaan toisella yliopiston sisällä olevalla palvelimella.

4.1.3 “wuff”-virheilmoitukset

Mikäli TIM-järjestelmän pääkontin palvelinkoodi tuottaa poikkeuksen (eli TIM-ohjelmisto palauttaa tilan, johon ei olla varauduttu), järjestelmä tuottaa tästä virheen.

Näistä virheistä lähetetään virheilmoitukset (“wuffit”) TIM-järjestelmään konfiguroituun sähköpostiosoitteeseen. Ilmoitukseen sisältyy muun muassa

• käyttäjä ja HTTP-pyyntö, joka aiheutti virheen;
• kooditiedosto, jossa virhe ilmeni;
• virheilmoitus.

4.1.4 Kuormituksen tarkistus

Järjestelmän kuormitusta seurataan tarpeen vaatiessa. Kuormituksesta ei aiheudu automaattisia hälytyksiä palvelun ylläpitäjille. Mikäli käyttäjiltä tulee raporttia tai muista lokeista huomataan poikkeamaa, seurataan järjestelmän kuormitusta.

Kuormituksen visualisoinnissa käytetään top-ohjelmaa, jolla nähdään resurssien käyttöaste ja prosessit, jotka näitä resursseja kuluttavat.

4.2 Päivitykset ja huoltokatkot

Järjestelmän päivityksiä tehdään ketterästi. Päivityksiä julkaistaan niiden valmistuttua, jopa useamman kerran saman vuorokauden aikana parhaimmillaan.

TIM-järjestelmä ei hyödynnä tarkkaa versiointistandardia, kuten Semveriä. Versiointi perustuu pääsääntöisesti TIM-JYU/TIM -projektiin tehtyyn viimeisimmän muutoksen hash-arvoon. Ennen kuin päivitykset viedään tuotantoon, muutoksille ajetaan automaattiset yksikkötestit. Lisäksi suurimmista muutoksista julkaistaan ensin väliaikainen esikatseluversio, jossa palvelua voidaan testata manuaalisesti.

Päivityksiä suorittaessa, täytyy joissain tapauksissa käynnistää järjestelmä tai sen osia uusiksi. Nämä huoltokatkot pyritään ajoittamaan JYU TIM -instanssilla kello 18 jälkeen, jotta käyttäjille koituisi mahdollisimman vähän häiriötä.

Huoltokatkoista tiedotetaan erikseen käyttäjille etukäteen asettamalla palveluun ilmoitus, jossa tiedotetaan tulevan huollon ajankohta ja arvioitu kesto.

Kurssinpitäjät ilmoittavat palvelun ylläpitäjille, mikäli palveluun on tulossa odotettavasti suurta kuormaa esimerkiksi tenttien vuoksi. Katkot ja päivitykset voidaan ajoittaa näiden tilanteiden ulkopuolelle.

4.3 Ylläpitotehtävät

Alla olevassa taulukossa ovat listattu olennaisimmat ylläpitotehtävät:

Muut uudelleenkäynnistystarpeet ja komennot ovat avattu tarkemmin Ylläpitäjien toiminnot -dokumentissa.

5. Palvelupyynnöt

Palvelupyyntökäytänteet koskevat käyttäjien pyyntöihin, kyselyihin, neuvontaan, käyttöoikeuksiin ja opastuksiin liittyvää toimintaa TIM-järjestelmän sisällä. Luvussa käsitellään pääosin JYU TIM -instanssin käytänteitä, mutta osa asioista koskevat yleistä TIM-järjestelmää.

5.1 Roolit ja vastuut

JYU TIM -instanssilla palvelupyyntöroolit jaetaan kahteen ryhmään: TIM-ylläpitäjät ja käyttäjät.

5.1.1 TIM-ylläpitäjät

TIM-ylläpitäjäryhmä koostuu joukosta asiantuntijoita. Palvelupyyntöihin kohdistuvat roolit ja vastuut ovat kaikkien ylläpitotiimin asiantuntijoiden vastuulla.

Tämä käsittää

• palvelupyyntöjen hallinnoinnin
• palvelupyyntöprosessin eri vaiheet
• yksittäisten pyyntöjen käsittelyn tai hylkäämisen
• pyynnön edistymisen ja ratkaisun seurannan
• kommunikoinnin pyynnön lähettäjän kanssa
• tarvittaessa asianomaisten henkilöiden tiedon ajantasaisuuden varmistaminen pyyntöjen edistymisestä

5.1.2 Käyttäjät

Palvelupyynnöt esitetään yksittäisten käyttäjien toimesta suorittamalla palvelupyyntö sille tarkoitetun kanavan välityksellä. Käyttäjä voi halutessaan osallistua keskusteluun, joka yleensä syntyy lähetetyn pyynnön yhteyteen. Käyttäjä voi mahdollisesti joutua tarjoamaan lisätietoja palvelupyynnön yhteydessä, jotta tämän täyttyminen voidaan varmistaa onnistuneesti.

Käyttäjät voidaan jakaa ryhmiin, mikä vaikuttaa oikeuksien hallintaan sekä palvelupyyntöjen luonteeseen. Valmiita ryhmiä TIMissä ovat muun muassa

• Haka users – HAKA-tunnistuksella kirjautuneet käyttäjät,
• Teachers – opettajat,
• Administrators – TIM-ylläpitäjät,
• Group admins – Käyttäjät, jolla on oikeus luoda uusia ryhmiä,
• Logged-in users – sisäänkirjautuneet henkilöt,
• kotiorganisaation käyttäjät – HAKA-tunnistuksella kirjautuneet käyttäjät, jotka kuuluvat konfiguroituun kotiorganisaatioon. JYU TIM -instanssilla tämä on jyu.fi
• Anonymous users – sisäänkirjautumattomat käyttäjät

Jos ongelmatilanteessa tai muuta tehtävää suoritettaessa käyttöoikeudet eivät riitä, on otettava yhteyttä TIM-järjestelmän ylläpitoon. Tällaiset tapaukset ovat esimerkiksi oman ryhmän luominen, jos käyttäjä ei ole Group admins -ryhmässä.

Käyttäjien palvelupyynnöt voivat riippua myös käyttäjän käyttöoikeuksista palvelupyynnön kohteena olevaan dokumenttiin tai kansioon.

Dokumentin tai kansion käyttöoikeudet voi nähdä ja muokata näiden kohteiden Manage-sivuilta. Mahdolliset käyttöoikeudet ovat listattu alla:

• View antaa oikeuden nähdä kohteen sisällön.

• Copy antaa katseluoikeuden lisäksi nähdä dokumenttien lähdetekstin sekä kopioida dokumenttien lohkot.

• Edit antaa kopiointioikeuden lisäksi oikeuden muokata dokumentin sisältöä.

• See answers antaa oikeuden tarkastella muiden vastauksia.

• Teacher käyttöoikeuksien avulla opettajat voivat opetukseensa esim. antaa opiskelijoille palautetta vastauksista.

• Manage antaa oikeuden muokata dokumentin oikeuksia, paitsi korkeimman tason Owner oikeuksia.

5.2 Palvelupyyntöprosessi (JYU TIM)

Prosessin kulkua JYU TIM -instanssilla voi kuvata seuraavalla prosessidiagrammilla:

Palvelupyynnön tarkemmat vaiheet ovat

1. Palvelupyynnön avaus
   Käyttäjä voi tehdä palvelupyynnön kahdella vaihtoehtoisella tavalla:

   1. lähettämällä pyynnön sähköpostilla osoitteeseen tim@jyu.fi TAI
   2. GitHub-kortilla

   Pyynnön käsittelyä helpottaa yksityiskohtainen ongelman kuvaus. GitHub-sivustolta voi tarkastella olemassa olevia, avoimia ja suljettuja tikettejä.

2. Analysointi
   Ylläpito perehtyy palvelupyynnön sisältöön ja ottaa sen hoitaakseen tai ohjaa palvelupyynnön tarvittaessa toiselle asiantuntijalle sen kuuluessa paremmin toisen asiantuntijan osaamis- tai vastuualueelle. Ylläpito voi myös luoda sähköpostilla käyttäjältä tulleen palvelupyynnön johdosta GitHub-tiketin.

3. Vastaaminen
   Asiantuntija vastaa käyttäjän lähettämään palvelupyyntöön. Käyttäjä pidetään ajan tasalla pyynnön etenemisestä ja mahdollisista muista toimenpiteistä. Käyttäjältä saatetaan pyytää lisätietoja, jotka analysoidaan myös. Sähköpostilla avatut viestiketjut siirtyvät usein suoraan ensimmäiseksi vastanneen ylläpitoryhmän jäsenen vastattavaksi.

4. Ohjeistus ja toimenpiteiden määräys
   Palvelupyynnön luonteesta riippuen ylläpito antaa suoraan käyttäjälle tarvittavat ohjeistukset tai toimintaohjeet asian ratkaisemiseksi. Tarvittaessa ylläpito itse toteuttaa tarvittavat toimenpiteet.

5. Toimenpiteiden suoritus
   Ylläpito tai käyttäjä suorittaa tarvittavat toimenpiteet palvelupyynnön toteuttamiseksi.

6. Pyynnön täyttyminen
   Palvelupyyntö on selvitetty ja suljettu. Ensimmäisen tavan mukaan avatut palvelupyynnöt katsotaan sulkeutuneeksi, kun pyyntö on täyttynyt ja sitä koskeva viestiketju pysähtynyt. GitHub-kortilla avatun palvelupyynnön status määritellään suljetuksi, kun pyyntö on katsottu täyttyneeksi.

Käyttäjä voi koska tahansa keskeyttää palvelupyynnön jättämällä pyynnön keskytyksestä syntyneeseen viestiketjuun. Pyynnön voidaan myös nähdä keskeytyneen, mikäli viestiketjun jatkuminen pysähtyy käyttäjän toimesta.

5.3 Yleiset palvelupyynnöt

Palvelupyynnöt voi jakaa JYU TIM -instanssilla kahteen luokkaan: avun- ja opastuspyyntöihin sekä sisällön päivityspyyntöihin.

5.3.1 Avunpyynnöt ja opastuspyynnöt

Palvelupyynnöt voivat olla luonteeltaan avunpyyntöjä tai opastuspyyntöjä, esimerkiksi liittyen TIM-dokumenttien muokkaukseen/luomiseen.

Esimerkkejä pyynnöistä:

• sivujen poistaminen ja palauttaminen
• kuvion luominen
• kurssin videosisältö ei toimi

Avunpyynnöt voivat olla myös kurssien sisältöön liittyviä tai dokumenttien omistajille kuuluvia pyyntöjä. Tällaiset eivät varsinaisesti kuulu TIM-tiimin asiantuntijoille ja ne ohjataan yleensä järjestelmän toimesta suoraan asianomaisille henkilöille, kuten kurssin opettajille.

5.3.2 Päivityspyynnöt ja muutokset

Päivityspyyntöjä ja muutoksia koskevat palvelupyynnöt pitävät sisällään TIM-palvelun sisältöön kohdistuvia toimenpiteitä: päivitys- tai muutostarpeita tai -ehdotuksia. Näitä voivat olla esimerkiksi erilaiset lisäykset, poistot ja muutokset, kuten esimerkiksi Pythonin versiopäivityksen toteuttaminen.

Esimerkkejä pyynnöistä:

• Kuvien ja kaavojen numerointi