SEMDA API and integration

1.1. Search for clubs

The control over the clubs is at Rotary International. The Local CMS can retrieve list of clubs and some limited information about them. However in order to get all details from RI about the club, it is necessary to set the “vendor = SEMDA-3” for that club in RI. The vendor can only be set by the club itself. Here is a guide (in German) how to do it. Without setting the vendor to SEMDA-3 for the cub, only a very limited amount of information will be returned by RI .

The related API endpoints are:

• POST /3.0/search/clubs
• GET /3.0/club/{ClubID}

1.2. Create club

Club must be created in RI first. After that, the “vendor = SEMDA xxx” must be set for this club in RI.  This can be done only by the club itself.  Here is the list of SEMDA vendors and here the guide (in German) how to do it.

Important note: remember that RI rules require some minimal number of club members to be entered when a new club is created.

The creation of the club in the Local CMS is also a manual step, because the Local CMS maintains far more data about the club then RI. Creating clubs in Local CMS before RI may lead to different club data in Local CMS. To avoid this, the Local CMS can check data existing in RI. Assuming the vendor for the new club was properly set in RI, the club details can be obtained and used during the creation of the new club in Local CMS.

The related API endpoints are:

• POST /3.0/search/clubs
• GET /3.0/club/{ClubID}
• GET /3.0/club/{ClubID}/addresses
• GET /3.0/club/{ClubID}/emails
• GET /3.0/club/{ClubID}/phonenumbers
• GET /3.0/club/{ClubID}/weblinks

1.3. Modify club

Usually the Local CMS maintains more data about the club than RI. This is given by different requirements for the systems. Therefore clubs should be modified only in Local CMS. Data modifications in RI may lead to data inconsistency in Local CMS.

Some data cannot be modified in RI. It must be set or changed manually within MyRotary or cannot be changed at all. These are for example:

• RI-ID of the organization
• Name of the club 

The related API endpoints are:

• PUT /3.0/club/{ClubID}/addresses
• PUT /3.0/club/{ClubID}/emails
• PUT /3.0/club/{ClubID}/phonenumbers
• PUT /3.0/club/{ClubID}/weblinks

1.4. Terminate club

Termination of clubs requires many pre-conditions like no members, paid invoices, etc. to be met. Therefore, it is not possible to terminate clubs in RI via the RI-Interface. Termination must be done in both RI and Local CMS. 

Manual process spanning multiple actors is difficult to synchronize and introduces dependency of the actors. For reasons of correct accounting and membership management, the club should be terminated fist in RI, then in the Local CMS. Delaying the termination in one of the systems will lead to data inconsistencies in both Local CMS and in RI.

The search for clubs can be used in Local CMS to detect terminated organizations in RI. They are not in the query result. The current RI-API does not provide information about the club status. The only way to clarify it is to engage the district governor.

The related API endpoints are:

• POST /3.0/search/clubs
• GET /3.0/club/{ClubID}

2.1. Import members

When new club is created in RI, it must have a minimal initial number of members. These founding members are always created in RI. In order to create them also in the Local CMS, their data can be imported from RI.

The related API endpoints are:

• GET /3.0/club/{ClubID}/members
• GET /3.0/individual/{IndividualID}
• GET /3.0/individual/{IndividualID}/addresses
• GET /3.0/individual/{IndividualID}/emails
• GET /3.0/individual/{IndividualID}/phonenumbers
• GET /3.0/individual/{IndividualID}/sponsors
• GET /3.0/individual/{IndividualID}/weblinks

The current SEMDA API covers individuals of the type member and honorary member. The individual must belong to one of the three communities: Rotary,Rotaract or Interact (not yet supported). The membership in these communities has specific differences.

2.2. Create member

In RI an individual always belongs to at least one organization. This means. that it is not possible to create an individual without an affiliation to a club. The  endpoint POST /3.0/affiliation/{ClubID}/new-individual must be used for creation of new members.

Handling of duplicates is cumbersome in RI and in Local CMS and creates high manual effort for the support and troubleshooting. Duplicates should be avoided. A good way to avoid duplicates is to search for existing members which similar data before the member is created.

This is what the endpoint POST /3.0/search/individuals is used for. One can search only on e-mail, first name, last name, Club-ID, club type, club name, district-Id or country, and get back only first name, middle name, last name, country and the existing affiliation to the clubs. Unfortunately e-mail is not returned, but it is possible to search on it. In this way a potential duplicate can be detected.

The related API endpoints are:

• POST /3.0/search/individuals
• POST /3.0/affiliation/{ClubID}/new-individual
• PUT /3.0/affiliation/{ClubID}/member/{IndividualID}
• POST /3.0/affiliation/{ClubID}/member/{IndividualID}

2.3. Modify member

Members should be modified only in Local CMS (MASTER), then the modification is propagated to RI. Some member data cannot be modified in Local CMS. It must be set or changed manually in MyRotary, by contacting Rotary International or cannot be changed at all. These cases are:

• Login e-mail address used to login into MyRotary
• Club entry date
• RI-ID of the individual

The related API endpoints are:

• PUT /3.0/individual/{IndividualID}
• PUT /3.0/individual/{IndividualID}/addresses
• PUT /3.0/individual/{IndividualID}/emails
• PUT /3.0/individual/{IndividualID}/phonenumbers
• PUT /3.0/individual/{IndividualID}/sponsors
• PUT /3.0/individual/{IndividualID}/weblinks

RI allows modification of individuals in parallel to Local CMS. It is unavoidable, that members will change their data in one or other system without knowing the consequences. In order to support bidirectional data synchronization, SEMDA provides service to retrieve updates of all members since a specific date. The Local CMS is responsible for requesting the updates in periodic intervals and processing them correctly. It must avoid endless loops resulting from changes initiated in Local CMS. They will of course appear in the next update request.

The related API endpoints are:

• GET /3.0/club/{ClubID}/members
• GET /3.0/synchronisation/individuals/{start-date}/{end-date}

2.4. Change member affiliation to a club

A member may have affiliation with multiple clubs. He/she can be member of one Rotary club and/or of one Rotaract club. He/she can be also honorary member of any number of other clubs. The first affiliation of the member is created when he joins the Rotary or Rotaract community. From then on he/she is forever part of the community.

With the exception of the founding members of a new club, the Local CMS is assumed to be the MASTER for maintenance of the affiliation. The new affiliation is then propagated to RI.

The related API endpoints are:

• GET /3.0/individual/{IndividualID}/affiliations
• POST /3.0/affiliation/{ClubID}/member/{IndividualID}
• PUT /3.0/affiliation/{ClubID}/member/{IndividualID}
• DELETE /3.0/affiliation/{ClubID}/member/{IndividualID}

For honorary members the Local CMS must solve the problem how to obtain their data if they are not known in the Local CMS. The endpoint POST /3.0/search/individuals can be used for that, even it returns only limited amount of data. 

2.5. Terminate member

Termination means ending membership in an club. The individual may still have membership(s) in another clubs. Termination is always done by the respective club. The risk of inconsistency with RI due to incompatible change in RI is low. Local CMS is assumed to be the MASTER and the change is propagated to RI. It is possible to retrieve the terminated individuals of the clubs from RI first and decide if manual actions are necessary.

The related API endpoints are:

• GET /3.0/club/{ClubID}/former-members
• GET /3.0/individual/{IndividualID}/affiliations
• DELETE /3.0/affiliation/{ClubID}/member/{IndividualID}

The terminated member will remain in the RI system. It is not possible to delete this personal data completely today.

2.6. Transfer member

An Individual cannot be member in two clubs of the same community type on any given date. Thus the transfer must be implemented with two separate requests, and the dates must be apart.

1. The Individual is terminated in the existing Club.
2. The Individuals to the new club is created.

The term “officer” represents an individual having a function within an organization. Example is a president or secretary of the club. Management of officers is always done by the respective club.

Modification of officers is not possible. Remove and add is used instead

3.1. Add officer

Officers should be added in Local CMS (MASTER) then the change is propagated to RI. Before an officer is added, Local CMS should verify that it doesn't exist at RI or in Local CMS already.

The related API endpoints are:

• GET /3.0/club/{ClubID}/officers/{CommunityYear}
• PUT /3.0/club/{ClubID}/officers/{CommunityYear}

3.2. Remove officer

Officers should be removed in Local CMS (MASTER) then the change is propagated to RI. Before an officer is added, Local CMS should verify if the officer still exist in RI.

The related API endpoints are:

• GET /3.0/club/{ClubID}/officers/{CommunityYear}
• PUT /3.0/club/{ClubID}/officers/{CommunityYear}