Integrate OSM Teams within TM4 teams

[LanesGood]

• [X] Discuss integration with TM development team
• [x] Create workflow document for potential integration options

[kamicut]

This has to be discussed with the TM development team to figure out if this is an external plugin or something that has to be added in the TM codebase. We also have to determine whether this is a 2-way sync, a one-way sync, or if OSM Teams within TM are a different entity but behave like TM teams.

[batpad]

We're settling on an approach we're calling "Creating read-only teams within Tasking Manager" - where a user can create teams within Tasking Manager where all the team metadata like name and description can be edited within Tasking Manager, but user membership will be handled in OSM Teams and be read-only in Tasking Manager.

This would allow users to delegate all team management activities to OSM Teams while creating teams in the Tasking Manager. This would leave the current Teams flow in TM unchanged - but allow users to optionally mark a team on TM as “managed on OSM-Teams”. The flow would be roughly:

• When user is creating a team on TM, they have an option to say “I want to sync a team from OSM-Teams”. They are then prompted to login to OSM-Teams, and they can choose the team within OSM Teams that they wish to sync to TM.
• The team is then created on TM by copying over data from OSM Teams to the TM database. If a team is flagged as “managed by OSM Teams” in TM, it is read-only in the Tasking Manager - users will get a link to OSM Teams where they can make any changes.
• Then, a user can at any point press a “Re-sync” button, which will update the team in TM with any changes made on OSM Teams.

Rationale:

• This avoids the complexity of a “two-way sync” where some conflicts may not be easy to resolve - how does one deal with a user removed on one end, etc?
• This leaves the current workflow for Teams on TM unchanged: people can continue using existing teams as is.
• This fits well with the vision of OSM-Teams: external application use its OAuth system to authenticate, get access to teams and use that information, while delegating all aspects of management of those teams to OSM-Teams.
• This approach allows for a gradual migration to using OSM-Teams on TM without forcing an all-or-nothing approach.

Next Steps:

• [x] @LanesGood to understand the authentication flow and caveats, and mock up the buttons / screens to be added to TM4.
• [x] @willemarcel to validate the possibility of implementation in TM4 / suggest changes to make integration easier / better.
• [ ] Once we have a finalized plan with clear mockups, plan implementation and discuss possibilities of merging changes upstream.

cc @vgeorge @willemarcel @LanesGood @kamicut

[willemarcel]

• If a team is flagged as “managed by OSM Teams” in TM, it is read-only in the Tasking Manager

It's good to clarify that only the members will be read only. The other team details as name and description will remain editable in TM.

[batpad]

It's good to clarify that only the members will be read only. The other team details as name and description will remain editable in TM.

Thanks @willemarcel . Have updated the comment above to reflect the same.

[LanesGood]

Is there a possibility to add a "synced with Tasking Manager" label/field to a team in OSM Teams? I imagine this would be a database field. This could be useful for team managers/moderators when making changes on the OSM teams side to consider/be aware of effects on the TM environment.

[LanesGood]

I've mocked up the possible flow for TM4<>OSM Teams integration and am interested in your feedback @kamicut @vgeorge @batpad @willemarcel

View the prototype here. I've documented the current Team creation flow in Tasking Manager, and added the proposed flow.

[batpad]

@LanesGood 😍 this looks fantastic!

Everything looks good to me and this to me is the "ideal workflow". The only problem I can see with this is how do we handle the case where there is a user on OSM Teams who does not yet have an account on Tasking Manager - in this case, Tasking Manager does not have a good way to add this user to a team.

I think there are two options here:

• Make some significant changes to how users and teams are handled in TM to allow for there to be some sort of "orphaned user" as part of a team - i.e. we store that a particular OSM ID is part of a team even if they don't have a TM account. Then, if that user signs up to TM, they are automatically added to the teams that their OSM ID is part of. This seems like it would be the nicest from a UX perspective: then the user doesn't need to worry about this problem really - you can still add OSM IDs to Teams in TM, and if and when the person signs up for an actual account on TM, they are added to the team. I do worry that this introduces too much complexity in TM and would require structural changes. @willemarcel would just be nice to get your thoughts on here and a rough sense of how feasible you think this is.
• A more practical solution might be to just inform the user that is creating / syncing the team from OSM Teams if there are OSM IDs in the team from OSM Teams that do not have a corresponding TM account. In this case, it would be some sort of message to the user like "Adding X, Y and Z users failed because they don't have TM accounts. Please ask them to create TM accounts and sync again.". This is likely the easiest from an implementation perspective, but likely gets a bit tricky to come up with a nice UX for this.
• Similar to the above option, maybe we could let the user know that X, Y, Z users could not be added, but we don't require the user to re-sync after the users create their TM accounts - we do some sort of background re-sync or so to keep the teams in sync without explicit user intervention. Again, this requires some infrastructural complexity and we need to figure out how we do this "background re-sync" exactly, but could be worth doing to avoid the user having to manually re-sync. @kamicut thoughts?

I also feel comfortable with ignoring this particular complexity for now to continue conversations and see if this overall flow seems agreeable, and then tackle these little details, but we likely will need to deal with this problem at some point.

[willemarcel]

@LanesGood the mockups look great!

For the initial implementation, I prefer to just show a message with the users that are not present in TM. I would avoid implementing background re-sync in a first moment too, as it would require more changes in TM.

Is there a possibility to add a "synced with Tasking Manager" label/field to a team in OSM Teams? I imagine this would be a database field.

Yes, it'd be possible.

[willemarcel]

Started the work in this branch: https://github.com/OpenHistoricalMap/tasking-manager/tree/feature/osm-teams-integration

[LanesGood]

Current Tasklist

• [X] Made authentication oAuth connection
• [X] Set up API call from TM to teams
• [ ] Refresh tokens are saved in the TM database
• [x] Pull in user teams
• [x] Select teams
• [x] import members & managers

[LanesGood]

Addressed in https://github.com/hotosm/tasking-manager/pull/5575