Who will initiate the final ToR exchange process?

[wrygiel]

The current version of the document proposed two contradicting flows of data in regard to the final exchange of ToR (after mobility). Both of these flows are described here:

We need to pick - either option 1 or option 2. Or, devise some different option.

My personal estimate is that option 1 is a much safer choice of these two.

[georgschermann]

Among our customers, the first scenario is the most common, but also other scenarios like the 2nd one or initiated by the sending coordinator and the receiving coordinator accessing the sending web app are common practice

[wrygiel]

receiving coordinator accessing the sending web app

What do you mean exactly? If I understood you correctly, this would require the receiving coordinator to have a user account on the Sending Web App?

In general, we could also support both of these options, if need be. We could have two separate flags in the Outgoing Mobility object:

• marked as ready for recognition by the student
• marked as ready for recognition by the receiving coordinator

The Sending Web App could notify the sending coordinator if any of these flags was changed.

[wrygiel]

BTW, initially I wanted this flag to be present in the ToR itself, but now it seems more appropriate to move it to the Outgoing Mobility entity and allow Receiving Web App to modify it via Ougoing Mobility Remote Update API.

[wrygiel]

but now it seems more appropriate to move it to the Outgoing Mobility entity and allow Receiving Web App to modify it via Ougoing Mobility Remote Update API.

So the new version of option 2 would look rather like this:

[georgschermann]

receiving coordinator accessing the sending web app
What do you mean exactly? If I understood you correctly, this would require the receiving coordinator >to have a user account on the Sending Web App?

sometimes they get user based access, most of the time they get an email with a link and are authorized via access tokens

i also don't think that we should restrict this to a single scenario

[vickalaser]

I agree that we should not restrict. We should try to design the systme so that it can pass information between HEIs. The main flow, as we know is the following. Some flows are clear regarding who initiates but some will have variance.

nomination ( variations on who intiiates and who signs)
acceptance/rejection (possible need for clarification before decision)
LA handshake ( this will be back and forth before and during the mobility period)
Host Transcript ( host always sends)
Home Transcript (home always generates after conversion, may flag recognition to Host)

[wrygiel]

To sum up - all three parties should be allowed to initiate this exchange.

1. The student should be allowed to click a button in his Sending Web App labeled "Refresh the Transcript of Records from the receiving institution".
2. The sending coordinator should be able to do the same.
3. Receiving coordinator too!

This last one is trickier. In EWP, we don't encourage solutions involving receiving coordinators accessing Sending Web Apps. But I guess we could allow such requests to be submitted via the Outgoing Mobility Remote Update API.

Solution 1: Add a new "history entry"

This API is still in draft version, but it already allows receiving coordinators to edit various properties of the Outgoing Mobility object by adding new "history entries" to its <timeline>. I believe we could introduce a new type of "timeline entry" for this purpose. The meaning of such entry would be:

"The receiving coordinator has indicated that the Transcript of Records associated with this mobility has been recently modified and the sending institution should refresh it."

Once such entry is added, the Sending Web App can either notify its sending coordinator on the fact, or it can refresh the ToR itself.

Solution 2: Add a new parameter to the Remote Update API

Having a history of such requests seems a good feature for me, but if guys from @erasmus-without-paper/wp3 don't agree, we could also add a separate parameter to the Outgoing Mobility Remote Update API for that.

[wrygiel]

Solution 3: The CNR API solution

It's worth noting that initially I was hoping that we will achieve this functionality by means of a CNR API - the Receiving Web App would notify the Sending Web App about every change in the Transcript of Records, so that the Sending Web App would always be able to have a fresh copy of it (and there will be no reason to manually initiate such exchanges, ever).

However, after some thought I'm afraid that sending such notifications would be quite hard. Transcripts of Records are complex beasts. There is a huge amount of triggers which would need to be watched in order for such notifications to work properly. So we would need a manual way of doing this either way.

[wrygiel]

As I have indicated here (and during the discussions in Warsaw), I currently believe that Solution 1 is the way to go.

[wrygiel]

In the current Outgoing Mobilities API, there is no timeline anymore, so Solution 1 is no longer possible.

Solutions 2 and 3 are still doable.

• In case of Solution 2, we no longer have the "Outgoing Mobilities Remote Update API", currently we have the "update endpoint" of the Outgoing Mobilities API, which serves the same purpose. However, this endpoint updates elements which exist in the get's XSD, and no such element exists there now.

• Solution 3 seems to be the "cleanest" one. It allows the receiving HEI to re-send notifications about changes in the ToR, if such changes happen. Since it is the receiving HEI who is "in charge" of the ToR, so this solution also seems to better fit reality. However, we might also need to add the index endpoint to ToRs API in order for this solution to work the same way as IIAs and Mobilities do.

[wrygiel]

No one commented, but it's time to choose. I will describe solution 3 in the specs.

[wrygiel]

First thing to do here is to move parts of the current README.md documentation into a separate endpoints/get.md file. The location of the XSD and the example XML will also change, along with its namespace (for clarity).

[wrygiel]

Next, we need to add a new index endpoint, and a corresponding CNR API.

[wrygiel]

What request parameters should the index endpoint take?

If we want to make it similar to the index endpoint specified for the Outgoing Mobilities API, then it would take sending_hei_id, receiving_hei_id and modified_since. I'm not sure if there is a need for a planned_arrival_after parameter (especially in context of this thread).

Since this API is being served by the receiving HEI (as opposed to the Outgoing Mobilities API being served by the sending HEI), the roles are interchanged:

• In Outgoing Mobilities API the sending_hei_id is required, and the receiving_hei_id is repeatable and optional.

• In Transcript of Records API it seems that the receiving_hei_id should be required, and the sending_hei_id should be repeatable and optional.

[wrygiel]

These issues still need to be specified clearly:

1. When should the receiving HEI publish its first version of the ToR?
2. Is it forbidden to publish new (initially empty) ToRs automatically, for every new mobility, and then issue corrections to them?
3. When corrections allowed?

Solution 3a

I think that we need an additional "ready for recognition" boolean flag for each ToR. If we add such a flag, then it would be okay to answer the above questions as such:

1. Whenever it wants.
2. No, it's not forbidden. It's okay to publish empty ToRs, but it's probably not okay to mark them as "ready for recognition".
3. Always. Even in the ToRs which were already marked as "ready for recognition".

@erasmus-without-paper/all-members

[wrygiel]

Solution 3b

1. Only after it has been marked as ready for recognition.
2. Yes, it is forbidden to publish ToRs which are not yet ready for recognition.
3. Corrections are still allowed.

[MartaJuzepczuk]

I'm not sure about the planned_arrival_after parameter. In context of this thread and in context of possible use of ToRs without mobility context, it seems to be good idea to skip this parameter. However, wouldn't it be hard for client to get "this year ToRs" without this parameter? Especially if some student will visit the same HEI twice.

The second thing is that in Outgoing Mobilities API, the modified_since parameter can be ignored by the server. Would you like to allow this for ToRs as well? They are much bigger than mobility responses.

[MartaJuzepczuk]

Solution 3b seems easier and is enough for us.
If we choose solution 3a, it would be useful to have "ready for recognition" parameter in index endpoint.

[wrygiel]

In context of planned_arrival_after parameter:

wouldn't it be hard it could be hard for client to get "this year ToRs" without this parameter?

If we want this parameter to stay, then we need to decide if ToRs for which planned_arrival is unknown should be returned when planned_arrival_after is used. What do you think?

As to the modified_since parameter - yes, I think it should look exactly the same as in Outgoing Mobilities API - that is, servers should not be strictly required to implement it (because I suspect it could be very hard to achieve in some architectures).

We could add an extra element in manifest-entry.xsd which server implementers could use to notify the clients if they had implemented modified_since or not. Do you think you would make any use of it?

[MartaJuzepczuk]

If we want this parameter to stay, then we need to decide if ToRs for which planned_arrival is unknown should be returned when planned_arrival_after is used. What do you think?

I don't know. Probably we will ask for ToRs at the end of the arrival, so if only server stores this data, at this time it should be known. Maybe it would be better to choose the same rule as in Outgoing Mobilities.

We could add an extra element in manifest-entry.xsd which server implementers could use to notify the clients if they had implemented modified_since or not. Do you think you would make any use of it?

I don't think so.

As the client side developer I would like to have some filter (date or didactic cycle) that would be known for every ToR and not ignored by the server. This filter should allow me to filter "current" ToRs. We have generation date, but I'm afraid that it's too "technical". Maybe some servers will generate ToRs on demand or regenerate them from some reason.

[wrygiel]

Solution 3b seems easier and is enough for us.

Okay. 3b it is then.

Maybe it would be better to choose the same rule as in Outgoing Mobilities.

We didn't choose any rule in Outgoing Mobilities yet.

We have generation date, but I'm afraid that it's too "technical". Maybe some servers will generate ToRs on demand or regenerate them from some reason.

BTW, the generatedDate is supposed to be automatically generated upon every response. It was introduced to EMREX to avoid replay attacks. You were probably thinking about issueDate, however it also can be generated automatically upon every response. So these two dates won't work for you. planned_arrival_after seems a better choice.

[huntering]

We agree with the 3b solution -> CNR and only publish when ready for recognition.