search

erasmus-without-paper / ewp-specs-api-institutions

Specifications of EWP's Institutions API.
MIT License
0 stars 0 forks source link

How (and if?) do we model relations between contacts/people and their roles? #5

Closed wrygiel closed 7 years ago

wrygiel commented 7 years ago

As @kaiqu explained here, we might need relations between <contact>s and IIAs.

In version 0.1.0 of the Institutions API schema, this is dealt with via the <iia-id> sequence, but - if I understood this correctly - this is not enough. We need to able to assign iia-ids for every role of every contact.

@kaiqu, did I understand this correctly?

kaiqu commented 7 years ago

As @kaiqu explained here, we might need relations between "contact"s and IIAs.

In version 0.1.0 of the Institutions API schema, this is dealt with via the "iia-id" sequence, but - if I understood this correctly - this is not enough. We need to able to assign iia-ids for every role of every contact.

@kaiqu, did I understand this correctly?

First, some data model terminology:

A Coordinator belongs to an Institution/Org Unit, and can (in the next version) be connected to 0..* IIAs. I think the latter connections belong in the IIAs API.

BTW, I suggest we use "quotes" (or something) instead of XML for elements, since the latter convention aren't displayed in quoted text.

wrygiel commented 7 years ago

Contacts are Coordinators for Mobilities

Oops, I have used a different terminology in my XSD. Are these terms defined in WP2's dictionary?

My "contact" element is not necessarily a person. It can be, for example, an office (a phone number, or an email address, shared by a couple of people). Do you think it's a wrong assumption on my part? Do you think that we can require all coordinators to be specific persons?

A Coordinator belongs to an Institution/Org Unit, and can (in the next version) be connected to 0..* IIAs. I think the latter connections belong in the IIAs API.

I would rather assume that coordinators are part of factsheets (and factsheets are served in Institutions API).

In my mind, these two entities are divided quite clearly, according to the following:

wrygiel commented 7 years ago

My "contact" element is not necessarily a person.

For example, see here (source), or here (source).

(more factsheet examples)

kaiqu commented 7 years ago

Contacts are Coordinators for Mobilities

Oops, I have used a different terminology in my XSD. Are these terms defined in WP2's dictionary?

No - the task of aligning the model with the dictionary was assigned a lower priority, to be done after the structure is finalized.

My "contact" element is not necessarily a person. It can be, for example, an office (a phone number, or an email address, shared by a couple of people). Do you think it's a wrong assumption on my part? Do you think that we can require all coordinators to be specific persons?

This is a matter of terminology, rather than structure (it was probably not a good idea to delay the above-mentioned aligning with the dictionary, since it's important to know exactly what we are talking about when designing the structure). In the model, there is a sharp delineation between two types of contact information:

I've never been quite happy with the latter, so now might be the time to change it. In my mind, the term "coordinator" denotes a person, while "contact" is more general. I propose the following:

A Coordinator belongs to an Institution/Org Unit, and can (in the next version) be connected to 0..* IIAs. I think the latter connections belong in the IIAs API.

I would rather assume that coordinators are part of factsheets (and factsheets are served in Institutions API).

The Coordinators themselves, yes. I was referring to their connections to IIAs - i.e. a Coordinator having Role for an IIA (denoted in the coming version by a N:M relationship).

In my mind, these two entities are divided quite clearly, according to the following:

Factsheets contain information which is public, and can change in time without the need of signing the IIA again. IIAs contain information which is not necessarily public, and - if it changes - it requires the agreement to be signed again.

With that distinction, I guess assigning a new Coordinator to an IIA doesn't necessitate re-signing, so then I agree that the assignment of Coordinators to IIAs belong in the Institutions/Departments APIs.

kaiqu commented 7 years ago

My "contact" element is not necessarily a person.

For example, see here (source), or here (source).

The Contact term is discussed in my previous message, but I notice that the above examples seem to indicate more Roles than the ones mentioned so far.

(more factsheet examples)

I looked at some of these in the beginning of the modeling process, but it would probably be a good idea to go through some more fact sheets at this point to 1) check that the model hasn't lost any information and 2) complete code sets such as Role...

wrygiel commented 7 years ago

(...) two types of contact information: For people it's defined in the Coordinator entity

The term "coordinator" seems to fit our current set of roles. But I can imagine that as the list of roles grows, it might become very awkward, at some point. Intuitively, "coordinating something" seems to be a subset of all possible roles (and we can expect for this set to be growing).

BTW - our model image is becoming a bit tangled up. Do we need to model all entities on a single image? Perhaps it would be easier for the readers to split it up, for example, by the API?

Before I tackle your other comments - let's think about minimum requirements again, for a moment. The more I think on this, the more I wonder if we really need to model all these roles. Since EWP allows communication between whole systems, then perhaps it's up to the particular system developer to know who is supposed to do what in which context, and the partner doesn't need to know that. If this is true, then do we need roles in our model at all? Or, perhaps, we need only a small subset?

I would start with the smallest set of features required to meet our use cases. We can always add more features as we go.

wrygiel commented 7 years ago

Since it's somewhat unclear to me at this point, I have moved <role-id> and other related elements to a separate feature branch. (So that the master branch stays "clean".)

janinamincer-daszkiewicz commented 7 years ago

No - the task of aligning the model with the dictionary was assigned a lower priority, to be done after the structure is finalized.

It is a good assumpiton if we talk about technical dictionary prepared by WP3, not terminology prepared by WP2. That should be taken care of in the first place.

janinamincer-daszkiewicz commented 7 years ago

I looked at some of these in the beginning of the modeling process, but it would probably be a good idea to go through some more fact sheets at this point

You will find a substantial set gathered once by the partners in the Mobility project: https://www.usos.edu.pl/Mobility/InfoSheets/

In fact any proposal for the model should first be checked against this set of fact sheets.

janinamincer-daszkiewicz commented 7 years ago

I would start with the smallest set of features required to meet our use cases. We can always add more features as we go.

I agree.

kaiqu commented 7 years ago

The term "coordinator" seems to fit our current set of roles. But I can imagine that as the list of roles grows, it might become very awkward, at some point. Intuitively, "coordinating something" seems to be a subset of all possible roles (and we can expect for this set to be growing).

Yes.

BTW - our model image is becoming a bit tangled up. Do we need to model all entities on a single image? Perhaps it would be easier for the readers to split it up, for example, by the API?

Splitting up by API is not really possible, as many entities are used in more than one API. I guess it could be split up into some kind of "business areas", associating entities with a "primary" API:

Organization

IIA

Mobility

There are basically three ways to do this (ranging from the easiest to the most work):

  1. Assigning three colors to the entities
  2. Blowing the model up to A3 format
  3. Distributing the entities on 2 pages (the last two should fit one the same page)

I would like to try option 1 first, if we can assume everyone to have access to color printers?

Before I tackle your other comments - let's think about minimum requirements again, for a moment. The more I think on this, the more I wonder if we really need to model all these roles. Since EWP allows communication between whole systems, then perhaps it's up to the particular system developer to know who is supposed to do what in which context, and the partner doesn't need to know that. If this is true, then do we need roles in our model at all? Or, perhaps, we need only a small subset?

I assume contact information is only visual (if it was to be used programmatically in a different way for different Roles, the Roles would definitely be necessary). The only reason, then, for having defined Roles would be to be able to programmatically display contact information in a standard way for those Roles (and possibly to determine which Roles are assigned at a HEI).

I would start with the smallest set of features required to meet our use cases. We can always add more features as we go.

I agree. If Roles are deemed to be outside the smallest set, I'll remove them.

kaiqu commented 7 years ago

the task of aligning the model with the dictionary was assigned a lower priority, to be done after the structure is finalized.

It is a good assumpiton if we talk about technical dictionary prepared by WP3, not terminology prepared by WP2. That should be taken care of in the first place.

Aha. Ok, I will do that before releasing the next version of the model.

kaiqu commented 7 years ago

You will find a substantial set gathered once by the partners in the Mobility project: https://www.usos.edu.pl/Mobility/InfoSheets/

In fact any proposal for the model should first be checked against this set of fact sheets.

There are more than 70 documents here (counting the ones in the subdirectories) - is it possible to identify a key subset of them, for me to check?

janinamincer-daszkiewicz commented 7 years ago

I would have to look at them myself ;) I did but it was a couple of years ago. Just pick up 10 randomly.

janinamincer-daszkiewicz commented 7 years ago

It might be of some use to have a look at businessCardT in: https://www.usos.edu.pl/Mobility/Documentation2/default.html

kaiqu commented 7 years ago

It might be of some use to have a look at businessCardT in: https://www.usos.edu.pl/Mobility/Documentation2/default.html

Hm... Leaving out userDefinedBusinessCardSectionT and userDefinedSectionItemT (a generic name/value structure), the remaining components seem to be modeled by the current version:

organizationBCSection is covered by:

iroOfficeBCSection is covered by:

So, unless there is need for such a generic name/value structure, the model seems sufficient in this respect.

kaiqu commented 7 years ago

It is a good assumpiton if we talk about technical dictionary prepared by WP3, not terminology prepared by WP2. That should be taken care of in the first place.

Aha. Ok, I will do that before releasing the next version of the model.

I have produced a version of the WP2 Dictionary (data_dictionary.xslx), where I map from the Field Name to the current model, expressed by two added columns "WP3 - Attribute" and "WP3 - Entity". There are some questions which should be cleared up - should I commit the spreadsheet (possibly to a branch), or would this be considered unnecessary clutter in the repo?

kaiqu commented 7 years ago

I have produced a version of the WP2 Dictionary (data_dictionary.xslx), where I map from the Field Name to the current model, expressed by two added columns "WP3 - Attribute" and "WP3 - Entity". There are some questions which should be cleared up - should I commit the spreadsheet (possibly to a branch), or would this be considered unnecessary clutter in the repo?

I tried pushing the commented file to a new branch, but the server returns "permission denied" / HTTP 403. Should I have write access to this repo, or is it better to send the commented file to the technical mailing list?

@wrygiel @erasmus-without-paper/wp2

janinamincer-daszkiewicz commented 7 years ago

So, unless there is need for such a generic name/value structure, the model seems sufficient in this respect.

In my opinion there is a need for such generic section since it gives the possibility to send any information which might seem relevent by sending HEI. Our old Mobility client and server is in operation, you can see some real examples at: http://mobility.usos.edu.pl/mobility-server-transport/ These are business cards prepared by partner institutions.

kaiqu commented 7 years ago

So, unless there is need for such a generic name/value structure, the model seems sufficient in this respect.

In my opinion there is a need for such generic section since it gives the possibility to send any information which might seem relevent by sending HEI. Our old Mobility client and server is in operation, you can see some real examples at: http://mobility.usos.edu.pl/mobility-server-transport/ These are business cards prepared by partner institutions.

I think this is solved by the Info attribute in Inst/Org Unit in the latest version of the model. It represents 0..* Info elements with Headers for display/grouping (as described in my message to the technical list yesterday). I propose to replace the predefined Role IDs with this.

janinamincer-daszkiewicz commented 7 years ago

Is this already reflected in the XSD or XML example?

janinamincer-daszkiewicz commented 7 years ago

Are you sure that all posted Business Cards (Fact Sheets) from the Mobility server can be easily described by the model? Could we see the XML examples showing this? That would be real proof of concept.

janinamincer-daszkiewicz commented 7 years ago

What you see at http://mobility.usos.edu.pl/mobility-server-transport/ is posted automatically by the server after API invocation of the client. XML contains header (title) section which helps to structure information in a way readable for humans. We might even post such Facts Sheets of EWP partners at the registry web page (if we decide to have one and if there comes an attribute 'public' with the invocation).

kaiqu commented 7 years ago

Are you sure that all posted Business Cards (Fact Sheets) from the Mobility servrr can be easily described by the model? Could we see the XML examples showing this? That would be real proof of concept.

I am working on it.

What you see at http://mobility.usos.edu.pl/mobility-server-transport/ is posted automatically by the server after API invocation of the client. XML contains header (title) section which helps to structure information in a way readable for humans.

This fits the Info structure perfectly (header + content repeated), which was the result of examining quite a few fact sheets (including the one from UW). It also fits pretty well with what @wrygiel created in a branch (except he called the structure "embedded-mobility-factsheet" and made it embeddable/recursive).

Also, since there doesn't seem to be any need for programmatic processing of predefined Role IDs, I propose to replace them with headers. That way, we get the header/content structure for all kinds of repeating information connected to Inst/Org Unit. (Coming in the next model version)

wrygiel commented 7 years ago

I tried pushing the commented file to a new branch, but the server returns "permission denied" / HTTP 403.

In general, only WP2 is allowed to change things in ewp-wp2-* repositories, because they are responsible for their contents. If you would like to suggest changes, the "GitHub way" of doing this is to create a fork (your local copy of the repository), and then make a pull request. Then, you assign people to this pull request to review your comments.

wrygiel commented 7 years ago

BTW, @kaiqu, I see we are working on one API in parallel. I hope it's not too confusing for you :) I also have some local changes for Organizational Units API, but I'm not sure if will be able to push them before I leave for my holidays.

kaiqu commented 7 years ago

In general, only WP2 is allowed to change things in ewp-wp2-* repositories, because they are responsible for their contents. If you would like to suggest changes, the "GitHub way" of doing this is to create a fork (your local copy of the repository), and then make a pull request. Then, you assign people to this pull request to review your comments.

Sorry about the GitHub newbie questions, but I have created the fork and pull request, but I don't see how to assign people to it?

kaiqu commented 7 years ago

BTW, @kaiqu, I see we are working on one API in parallel. I hope it's not too confusing for you :) I also have some local changes for Organizational Units API, but I'm not sure if will be able to push them before I leave for my holidays.

No problem :-) I'm waiting with the Org Units API until the Institutions API is finished, since they will be very similar.

wrygiel commented 7 years ago

I have created the fork and pull request, but I don't see how to assign people to it

It seems that you'd need to have write-permissions to assign people directly. So, lets use @mention tags instead.

wrygiel commented 7 years ago

As @kaiqu explained here, we might need relations between <contact>s and IIAs.

In the latest IIAs API draft (version 0.1.0), we have dealt with this problem by allowing <contact> elements in various places of the IIA element tree. Each such contact can have a <role-description>. Contacts with very specific roles have separate elements to distinguish them. We will see if this proves enough for our purposes (new, more specific issues might arise in the future).

BTW, this also means that some data that we initially planned to put in the Institutions API, will now be placed in the IIAs API (as explained here).