Skip to content

Commit

Permalink
Add optional ewp-reason-code to component changes
Browse files Browse the repository at this point in the history 
Fix #15
  • Loading branch information
@wrygiel
wrygiel committed Mar 3, 2017
1 parent b11779c commit 38a9fb3
Showing 1 changed file with 111 additions and 7 deletions.
118 changes: 111 additions & 7 deletions endpoints/get-response.xsd
View file
Original file line number Diff line number Diff line change
Expand Up @@ -896,13 +896,8 @@
An optional reason for the change.

UI designers are advised to supply a number of suggested reasons for their
users (so that they can pick one when making the change). You can start with
those listed in the EUC LA PDF template. Users SHOULD be allowed to specify
their own custom reason for the change too.

Note, that we do not make use of the "reason numbers" suggested by the EUC LA
PDF template. We also do not attempt to introduce any other identifiable IDs or
codes at this time (but we may try to do so in future versions of this schema).
users (so that they can pick one when making the change). Users SHOULD be
allowed to specify their own custom reason for the change too.
</xs:documentation>
</xs:annotation>
<xs:complexType>
Expand All @@ -913,9 +908,118 @@
A human-readable description of the reason - preferrably in English. It will
often be printed in PDF LA document (e.g. in the "Reason for change" column of
A2 or B2 table - see attached EUC LA template).

The value of this element can sometimes be inferred from `ewp-reason-code`, but
for forward-compatibility reasons, this element is required regardless of this
fact.

If the reason cannot be provided, server implementers MAY provide an empty
string here. This is NOT RECOMMENDED though. Users SHOULD give some reason for
each of their changes, and the server SHOULD store these reasons.
</xs:documentation>
</xs:annotation>
</xs:element>
<xs:element name="ewp-reason-code" minOccurs="0" maxOccurs="1">
<xs:annotation>
<xs:documentation>
An optional reason code. It is RECOMMENDED to provide it, if the reason for
change matches one of the reasons provided in the enumeration below. If no
match can be found, then this element MUST NOT be provided.

Currently, the enumeration supports viable reasons for changing
`components-studied` list only. This element MUST NOT be provided for
changes in `components-recognized`.

Attached EUC LA template defines seven "Reasons for exceptional changes to
study programme abroad", and assigns them numbers from 1 to 7. EUC does say
whether this assignment is backward-compatible or not, so we must assume it
isn't. Therefore, we introduce an enumeration of our own, which is intended to
stay backward-compatible.

IMPORTANT: New values MAY be added to this enumeration in future releases of
this API, and such expansion is considered backward-compatible. Clients MUST be
aware of this fact - if you find an unknown value here, you MUST treat it the
same way as if no `ewp-reason-code` was given at all. Server MUST NOT expand
their set of used reason codes without consulting EWP Partners - new reason
codes MUST be added to the enumeration before they can be used.
</xs:documentation>
</xs:annotation>
<xs:simpleType>
<xs:restriction base="xs:string">
<xs:enumeration value="not-available">
<xs:annotation>
<xs:documentation>
Defined by EUC with the following description: Previously selected educational
component is not available at the Receiving Institution.

This reason MUST be used ONLY for "delete" changes.
</xs:documentation>
</xs:annotation>
</xs:enumeration>
<xs:enumeration value="language-mismatch">
<xs:annotation>
<xs:documentation>
Defined by EUC with the following description: Component is in a different
language than previously specified in the course catalogue.

This reason MUST be used ONLY for "delete" changes.
</xs:documentation>
</xs:annotation>
</xs:enumeration>
<xs:enumeration value="timetable-conflict">
<xs:annotation>
<xs:documentation>
Defined by EUC with the following description: Timetable conflict.

This reason MUST be used ONLY for "delete" changes.
</xs:documentation>
</xs:annotation>
</xs:enumeration>
<xs:enumeration value="substituting-deleted">
<xs:annotation>
<xs:documentation>
Defined by EUC with the following description: Substituting a deleted component.

This reason MUST be used ONLY for "insert" changes.
</xs:documentation>
</xs:annotation>
</xs:enumeration>
<xs:enumeration value="extending-mobility">
<xs:annotation>
<xs:documentation>
Defined by EUC with the following description: Extending the mobility period.

This reason MUST be used ONLY for "insert" changes.
</xs:documentation>
</xs:annotation>
</xs:enumeration>
<xs:enumeration value="properties-update">
<xs:annotation>
<xs:documentation>
This one is NOT defined by EUC, but it seemed reasonable to add it here. It can
be used with both "delete" and "insert" changes, and it indicates an update in
the component properties - like a change in the component's name (e.g. a
spelling error), or the number of awarded ECTS points. The exact reason for the
change SHOULD be specified in the `display-text` element.

This reason MUST NOT be provided if the component is *actually* being removed
or added. It is used *only* when an *existing* component is *updated* (which is
represented as two changes - a "delete" and an "insert" - preferably in this
order, next to each other).

It's worth noting that some servers MAY also choose to "rewrite history"
in case of unimportant mistakes, like obvious spelling errors in component name.
Such "rewrite" will cause a component to instantly change its name in all
snapshots (even those snapshots which have been approved a long time ago).

You can discuss this code here:
https://github.com/erasmus-without-paper/ewp-specs-api-mobilities/issues/15#issuecomment-283988998
</xs:documentation>
</xs:annotation>
</xs:enumeration>
</xs:restriction>
</xs:simpleType>
</xs:element>
</xs:sequence>
</xs:complexType>
</xs:element>
Expand Down

0 comments on commit 38a9fb3

Please sign in to comment.