Skip to content

Commit 4796793

Browse files
mkurzydlowskimkurzydlowski
authored
Merge pull request #56 from mkurzydlowski/stable-v3
Stable v3
2 parents 85cbafa + a1d2897 commit 4796793

22 files changed

+652
-499
lines changed

‎CHANGELOG.md‎

Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,54 @@ This document describes all the changes made to the *Outgoing Mobilities API*
55
document, starting from its first beta draft version.
66

77

8+
3.0.0
9+
-----
10+
11+
* Update Scenarios document and examples.
12+
* Renamed verified as approved.
13+
* Added important rules.
14+
* Updated approve and reject examples.
15+
* Renamed comment to reject.
16+
* Added rejected status.
17+
* Reworded cancelled status description.
18+
* Removed recognized status.
19+
* Replaced live status with verified.
20+
* Renamed nomination status as pending.
21+
* Updated scenarios.
22+
* Changed "accept" to "approve".
23+
* Added update endpoint and proposal id.
24+
* Added changelog for version 3.0.0.
25+
* Added global_id and activity_attributes parameters to the index.
26+
* Added "is mutually approved" to the iia-id description.
27+
* Receiving HEI's ID must be provided with sending HEI's ID.
28+
* IIA ID must be provided if it exists.
29+
* Removed notes from iia-id description.
30+
* All Outgoing and Incoming Mobilities APIs are required.
31+
* Removed the student-traineeships activity type.
32+
* Removed additional requirements.
33+
* Updated scenario examples.
34+
* Added an optional comment field.
35+
* Both iia-id fields are mandatory for digitally signed agreements.
36+
* Added agreement-isced-f-code mandatory field.
37+
* Removed eqf-level-studied-at-nomination and made at-departure mandatory.
38+
* Made nominee-isced-f-code mandatory.
39+
* Made email mandatory.
40+
* Made nationality mandatory.
41+
* Renamed citizenship to nationality.
42+
* Made birthdate mandatory.
43+
* Removed nominee-language-skill.
44+
* Removed planned-arrival-date and planned-departure-date.
45+
* Removed phone-number.
46+
* Removed street-address and mailing-address.
47+
* Removed photo-url.
48+
* Made gender mandatory.
49+
* ISCED must be four-digit.
50+
* Added MBR to resources and README.
51+
* Made sending CNRs mandatory.
52+
* Removed receiving and sending HEI parameters.
53+
* Incremented namespace version.
54+
55+
856
2.0.0
957
-----
1058

‎README.md‎

Lines changed: 113 additions & 74 deletions
Original file line numberDiff line numberDiff line change
@@ -15,13 +15,31 @@ and enumerate mobilities stored on the sending HEI's servers.
1515
Currently, this API describes mobilities **of one type only** - *Student
1616
Mobilities for Studies*. More types MAY be added in the future.
1717

18+
If HEI provides any API from the following group:
19+
* Outgoing Mobilities
20+
* Outgoing Mobilities CNR
21+
* Outgoing Mobilities Stats
22+
* Incoming Mobilities
23+
* Incoming Mobilities CNR
24+
25+
it MUST provide all APIs from this group.
26+
27+
28+
### Business requirements and processes
29+
30+
31+
[Business requirements and processes](resources/mandatory_business_requirements_nominations.pdf)
32+
document clarifies the requirements for the technical solutions
33+
developed under EWP and in the local implementation that should adequately support
34+
the business processes related to nominations at Higher Education Institutions.
35+
1836

1937
Reminder on vocabulary
2038
----------------------
2139

2240
Keep in mind that definitions of "sending HEI" and "receiving HEI" come from
23-
the "mobility vocabulary", not the "HTTP vocabulary". In case of this
24-
particular API this means that:
41+
the "mobility vocabulary", not the "HTTP vocabulary". In the case of this
42+
particular API, this means that:
2543

2644
* **sending HEI == responding HEI** (HEI which is sending the student == HEI
2745
which implements the API, *receives* the HTTP request, and responds to it),
@@ -31,6 +49,32 @@ particular API this means that:
3149
As long as we use these terms consistently, there shouldn't be much confusion
3250
though.
3351

52+
For brevity, we will use the following shortcuts:
53+
* `S` - sending HEI
54+
* `R` - receiving HEI
55+
56+
57+
Important rules
58+
---------------
59+
60+
* The nomination is uniquely identified by the `omobility-id`.
61+
* S sends the nomination to R – the nomination is in the `pending` state.
62+
* When S is sure that R has received information about the nomination
63+
(it correctly received the CNR or performed a GET),
64+
S must immediately inform its users about it (an internal `delivered` status may be noted in the local system).
65+
* R can accept the nomination – it changes the state to `approved`.
66+
* R can reject the nomination – it changes the state to `rejected`.
67+
* R cannot reject a nomination in the `approved` state.
68+
* If the nomination is in the `approved` state, S can notify R about the change of the student's personal data
69+
(given names, family name, birthdate, nationality, gender, email).
70+
This notification does not require R to make a new decision (the nomination remains in the `approved` state).
71+
* If the nomination is in the `approved` state, S cannot propose to R changes to this nomination
72+
in the data other than student’s personal data listed in the point above.
73+
* If the nomination has been rejected, S can submit a proposal for changes to this nomination
74+
(this requires changing the `proposal-id`). R can accept or reject this proposal.
75+
* S can cancel the nomination at any time – it changes the status to `cancelled`.
76+
Such a nomination cannot be submitted for reconsideration.
77+
3478

3579
Security
3680
--------
@@ -53,6 +97,7 @@ Server implementers MUST:
5397

5498
* Implement the [`get` endpoint](endpoints/get.md).
5599
* Implement the [`index` endpoint](endpoints/index.md).
100+
* Implement the [`update` endpoint](endpoints/update.md).
56101
* Put the URLs of these endpoints in their [manifest file][discovery-api], as
57102
described in [manifest-entry.xsd](manifest-entry.xsd).
58103

@@ -70,100 +115,94 @@ Data model entities involved in the response
70115
* Academic Term
71116

72117

73-
Workflows of changes in nomination and departure statuses
74-
---------------------------------------------------------
75-
76-
Mobility and its nomination have two different sets of statuses sent via Outgoing/Incoming Mobilities API get response. Example scenarios of status changes are presented below.
77-
78-
* `--MOBILITYSTATUS-->` - Outgoing Mobilities API get response
79-
* `<--NOMINATIONSTATUS--` - Incoming Mobilities API get response
80-
* `S` - sending HEI
81-
* `R` - receiving HEI
118+
Workflows of changes in nomination statuses
119+
-------------------------------------------
82120

121+
Nominations have sets of statuses (pending, approved, rejected, cancelled)
122+
managed by the sending institution and sent via Outgoing Mobilities API get response.
123+
Receiving institution verifies the nomination (approve or reject) via Outgoing Mobilities API update request.
124+
Scenarios of status changes are presented below.
83125

84-
**1.**
126+
The example scenarios will be described using the following symbols:
85127

86-
* S informs R via CNR about new nomination.
87-
* `S --NOMINATION--> R`
88-
* S ask R about nomination, but R has done nothing yet.
89-
* `S <--PENDING-- R`
90-
* R informs S that via CNR that nomination was changed.
91-
* `S <--REJECTED-- R`
92-
* S identifies problem and corrects nomination data
93-
* S informs R via CNR about changed nomination.
94-
* `S --NOMINATION--> R`
95-
* R informs S via CNR that nomination was changed.
96-
* `S <--VERIFIED-- R`
128+
* `--MOBILITY-STATUS-->` - Outgoing Mobilities API get response
129+
* `<--MOBILITY-UPDATE--` - Outgoing Mobilities API update request
97130

98-
**2.**
99131

100-
* Nomination was sent but student or S wants to cancel the mobility.
132+
### Simple nomination approval
101133

102-
Initial state:
103-
104-
`S --NOMINATION--> R`
105-
106-
`S <--ANY-- R`
134+
* S informs R via CNR about the new nomination.
135+
* `S --PENDING--> R`
136+
* S marks the nomination internally as `delivered`.
137+
* R processes the nomination internally.
138+
* `S <--APPROVE--R`
139+
* S informs R via CNR about the approved nomination.
140+
* `S --APPROVED--> R`
107141

108-
* S informs R via CNR about changed nomination.
109-
* `S --CANCELLED--> R`
142+
### Simple nomination rejection
110143

111-
**3.**
144+
* S informs R via CNR about the new nomination.
145+
* `S --PENDING--> R`
146+
* S marks the nomination internally as `delivered`.
147+
* R processes the nomination internally.
148+
* `S <--REJECT--R`
149+
* S informs R via CNR about the rejected nomination.
150+
* `S --REJECTED--> R`
112151

113-
* Nomination status is `VERIFIED` and student is about to leave for R.
152+
### Rejection, correction and approval (part marked with ! may occur multiple times)
114153

115-
Initial state:
154+
* S informs R via CNR about the new nomination.
155+
* `S --PENDING--> R`
156+
* S marks the nomination internally as `delivered`.
157+
* ! R processes the nomination internally.
158+
* ! `S <--REJECT--R`
159+
* ! S informs R via CNR about the rejected nomination.
160+
* ! `S --REJECTED--> R`
161+
* ! S corrects the nomination according to the suggestions sent by R in update,
162+
changes the proposal id and removes internal `delivered` flag.
163+
* ! S informs R via CNR about the modified nomination.
164+
* ! `S --PENDING--> R`
165+
* ! S marks the nomination internally as `delivered`.
166+
* R processes the nomination internally.
167+
* `S <--APPROVE--R`
168+
* S informs R via CNR about the approved nomination.
169+
* `S --APPROVED--> R`
116170

117-
`S --NOMINATION--> R`
118-
119-
`S <--VERIFIED-- R`
171+
### Change of student’s personal data (initial status: `pending`)
120172

121-
* S informs R via CNR about changed nomination/mobility.
122-
* `S --LIVE--> R`
123-
* From this moment we don't care about nomination status.
124-
* Time passes.
125-
* Student passes all the exams and returns to S.
126-
* S informs R via CNR about changed mobility.
127-
* `S --RECOGNIZED--> R` (OR, sometimes, `S --LIVE--> R` - some HEIs don't store explicit information about mobility recognition)
173+
* S changes student’s personal data.
174+
* S does not change the proposal id.
175+
* S informs R via CNR about the nomination with modified student’s personal data.
176+
* `S --PENDING--> R`
128177

129-
**4.**
178+
### Change of student’s personal data (initial status: `approved`)
130179

131-
* Nomination has been accepted by the receiving HEI, and all initial formalities have been settled. Student is about to leave for R. Suddenly, student or S wants to cancel the mobility.
180+
* S changes student’s personal data.
181+
* S does not change the proposal id.
182+
* S informs R via CNR about the nomination with modified student’s personal data.
183+
* `S --APPROVED--> R`
132184

133-
Initial state:
134-
135-
`S --LIVE--> R`
136-
137-
`S <--VERIFIED-- R`
185+
### Cancellation of a nomination (initial status: any)
138186

139-
* S informs R via CNR about changed mobility.
187+
* S cancels the nomination internally.
188+
* S informs R via CNR about the cancelled nomination.
140189
* `S --CANCELLED--> R`
141190

142-
**5.**
191+
### Change of non-personal data (initial status: `pending`)
143192

144-
* Student returns prematurely from R. Student can't justify it and has to return money from grant.
193+
* S changes non-personal data.
194+
* S changes the proposal id and removes internal `delivered` flag.
195+
* S informs R via CNR about the modified nomination.
196+
* `S --PENDING--> R`
145197

146-
Initial state:
147-
148-
`S --LIVE--> R`
149-
150-
`S <--VERIFIED-- R`
198+
### Change of non-personal data (initial status: `approved`)
151199

152-
* S informs R via CNR about changed mobility.
200+
* S cancels the nomination internally.
201+
* S informs R via CNR about the cancelled nomination.
153202
* `S --CANCELLED--> R`
154-
155-
**6.**
156-
157-
* Student returns prematurely from R. Student can justify it (force majeure) and doesn't have to return money from grant.
158-
159-
Initial state:
160-
161-
`S --LIVE--> R`
162-
163-
`S <--VERIFIED-- R`
164-
165-
* S informs R via CNR about changed mobility.
166-
* `S --RECOGNIZED--> R` (OR, sometimes, `S --LIVE--> R` - some HEIs don't store explicit information about mobility recognition)
203+
* S creates a new nomination for the same student with new mobility id and new proposal id.
204+
* S informs R via CNR about the new nomination.
205+
* `S --PENDING--> R`
167206

168207

169208
[develhub]: http://developers.erasmuswithoutpaper.eu/

‎endpoints/approve-proposal-v1.xml‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
<req:omobility-update-request
2+
xmlns:req="https://github.com/erasmus-without-paper/ewp-specs-api-omobility/blob/stable-v3/endpoints/update-request.xsd"
3+
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
4+
xsi:schemaLocation="
5+
https://github.com/erasmus-without-paper/ewp-specs-api-omobility/blob/stable-v3/endpoints/update-request.xsd
6+
https://raw.githubusercontent.com/erasmus-without-paper/ewp-specs-api-omobility/stable-v3/endpoints/update-request.xsd
7+
"
8+
>
9+
<req:approve-proposal-v1>
10+
<req:omobility-id>c442c289-5541-4cae-9edb-8ad83e133613</req:omobility-id>
11+
<req:proposal-id>AE61266750D019063512516C7EE01968012C81F25A89</req:proposal-id>
12+
</req:approve-proposal-v1>
13+
</req:omobility-update-request>

0 commit comments

Comments
 (0)