FAQ | This is a LIVE service | Changelog

essm-sync.md 4.82 KB
Newer Older
Robin Goodall's avatar
Robin Goodall committed
1
2
title: ESSM Sync

Robin Goodall's avatar
Robin Goodall committed
3
# Education Space Scheduling and Modelling Sync
Dr Rich Wareham's avatar
Dr Rich Wareham committed
4

5
6
7
This page gives an overview of the Education Space Scheduling and Modelling synchronisation service,
describing its current status, where and how it's developed and deployed, and who is responsible for
maintaining it.
Dr Rich Wareham's avatar
Dr Rich Wareham committed
8

9
## Service Description
Dr Rich Wareham's avatar
Dr Rich Wareham committed
10

11
12
13
14
15
Student Registry procured a room scheduling application called [TermTime from Semestry](https://semestry.com/overview/).
Room Booking is currently handled by [Booker from EventMap](https://www.eventmapsolutions.com/osc-booker/).
A synchronisation process was required where the activities scheduled in TermTime would become
room bookings in Booker. Also, for consistency the room and building definitions in Booker would
need to be synchronised to TermTime.
Mike Bamford's avatar
Mike Bamford committed
16

17
## Service Status
Mike Bamford's avatar
Mike Bamford committed
18

19
The ESSM Sync is currently `alpha`.
Mike Bamford's avatar
Mike Bamford committed
20

21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
Currently, which databases and discrepancies between Booker and TermTime are being ironed out.

Following this, a testing stage using a combination of Booker live and staging and a TermTime
training database, will confirm that the synchronised works as expected.

Finally, this will become live using a production TermTime database and Booker live.

## Contact

Technical queries and support should be directed to devops@uis.cam.ac.uk and will be picked up
by a member of the team working on the service. To ensure that you receive a response, always
direct requests to devops@uis.cam.ac.uk rather than reaching out to team members directly.

Issues discovered in the service or new feature requests should be opened as GitLab issues
in the [administration project](https://gitlab.developers.cam.ac.uk/uis/devops/essm/administration/-/issues)
or [sync-tool repository](https://gitlab.developers.cam.ac.uk/uis/devops/essm/sync-tool/-/issues),
37
if a sync tool specific issue or you lack permission to the administration project.
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61

## Environments

The ESSM Sync is currently deployed as Gitlab CI and Scheduled Pipelines in the Gitlab
[Synchronisation Tasks project](https://gitlab.developers.cam.ac.uk/uis/devops/essm/sync-tasks).

There is no additional infrastructure other than Gitlab itself and the DevOps Gitlab CI runners.

## Source code

The source code for the ESSM Sync is spread over the following repositories:

| Repository  | Description
| ----------- | ------------------ |
| [Sync Tool](https://gitlab.developers.cam.ac.uk/uis/devops/essm/sync-tool) | The source code for the synchronisation processing |
| [Sync Tasks](https://gitlab.developers.cam.ac.uk/uis/devops/essm/sync-tasks) | The Gitlab CI and Terraform infrastructure code for creating the Scheduled Pipelines |
| [Administration](https://gitlab.developers.cam.ac.uk/uis/devops/essm/administration) | General project wide issue tracking and [documentation](https://gitlab.developers.cam.ac.uk/uis/devops/essm/administration/-/wikis/home) |


## Technologies used

The following gives an overview of the ESSM Sync is built on.

| Category | Language | Framework(s) |
Mike Bamford's avatar
Mike Bamford committed
62
| -------- | -------- | --------- |
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
| Sync Tool | python | requests, PyYAML and dpath |
| Sync Tasks - Infrastructure | terraform | [gitlab provider](https://github.com/gitlabhq/terraform-provider-gitlab) |
| Sync Tasks - Gitlab CI | bash | docker |


## Operational documentation

The following gives an overview of how the ESSM Sync is deployed and maintained

### How and where the ESSM Sync is deployed

See [Sync Tasks](https://gitlab.developers.cam.ac.uk/uis/devops/essm/sync-tasks) Gitlab project.

### Deploying a new release

Updates to the [sync-tool](https://gitlab.developers.cam.ac.uk/uis/devops/essm/sync-tool) will be used
automatically by next schedule pipeline.

### Monitoring

Gitlab CI pipeline failures will cause automatic notification to the schedule owner (UIS DevOps Division Robot).

### Debugging

A local setup can be created by:
88

89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
- installing the sync tool
```
pip install https://gitlab.developers.cam.ac.uk/uis/devops/essm/sync-tool
```
- creating configuration files from the templates used in the
[Sync Tasks](https://gitlab.developers.cam.ac.uk/uis/devops/essm/sync-tasks) repository, containing
Booker and TermTime API credentials from ESSM 1password vault
- running `essmsync -c <configuration> <operation>` as described in
[sync tool](https://gitlab.developers.cam.ac.uk/uis/devops/essm/sync-tool) README

*Testing should be initially done against Booker staging instance and TermTime CambTest database.*

### Further Documentation

Detailed investigation of API usage and the synchronised processes may be found in the
[Administration Wiki](https://gitlab.developers.cam.ac.uk/uis/devops/essm/administration/-/wikis/home).


## Service Management and tech lead

109
The **service owner** is [Student Registry](https://www.student-registry.admin.cam.ac.uk/).
110

111
The **service manager** is [Neil King](https://www.lookup.cam.ac.uk/person/crsid/nik22).
112
113

The **tech lead** is [Robin Goodall](https://www.lookup.cam.ac.uk/person/crsid/rjg21).