[FEATURE] Link to RapidPro Parent Text

[ChrisMarsh82]

What?
We will need to bring parent data down from rapidPro (Malaysia deployment - could expand to more)

Why?
We are having validation issues with ParentText ids being entered incorrectly.
New flow to be.
Facilitator creates a parent group within the App
Facilitator sends the unique id for the parent group to parents during the onboarding session.
Parent sends the parent group id to ParentText when prompted.
Parent name and ID gets pulled into the App under the parent group (this data might need to be expanded later)

• From the App will need a way of ensuring Parent Group ID is unique in the app - users may not be logged in

• Password protected end point within the app server to receive parent information from ParentText (Parent Group ID + Parent Name + Parent Text ID) Must provide a success message to validate parent Group ID

• Set up flow in parent Text to allow users to enter a Parent Group ID

• Create webhook on ParentText to push to the app server endpoint

[ChrisMarsh82]

@istride @chrismclarke This is the initial issue we discussed on Thursday. Please feel free to comment and create break out issues.

[istride]

It's important to emphasise that ParentText will push the data back to the app, after a parent initiates a message flow using the group id. This implies that an API endpoint will need to be implemented, on the app side, to receive the data.

[chrismclarke]

Following a quick call today, this is the general data flow landed on for the initial phase:

This should hopefully complete a simple workflow where users can request access to a group from rapidpro flow via 4-digit access code, and be notified of response

Initial sync will include user rapidpro id, and whatever contact fields desirable to share with app. Data shared with firestore is automatically synced to the app

Future follow-up could include another function that fetches updates to users via the rapidpro contacts API (using uuid stored from groupJoin)

[istride]

For error responses that might use HTTP status code 400, it is worth considering whether 422 would be more appropriate. For example, "bad payload" may well be a 400 if, say, the JSON payload is syntactically invalid. An error such as "invalid access code" is more likely to come from a well-formed request with incorrect information in it that can't be processed - a 422.

[chrismclarke]

For error responses that might use HTTP status code 400, it is worth considering whether 422 would be more appropriate. For example, "bad payload" may well be a 400 if, say, the JSON payload is syntactically invalid. An error such as "invalid access code" is more likely to come from a well-formed request with incorrect information in it that can't be processed - a 422.

Apologies, that list isn't very comprehensive (more of a rough draft).
As of now, there's actually 4 separate 400 messages currently sent for

"Param validation error"
"User group not found"
"Multiple groups with same access code, cannot proceed"
"Group is not setup correctly, cannot proceed"

I think what might be a good way forward is to separate out errors that users can act on themselves, vs ones that they can't (to make it easier to display sensible messages in rapidpro as a result)

Of the 4 listed above, I think the last 3 would all be good candidates for 422 as all can (hopefully) be resolved by the user who may have used the wrong access code, or working with a facilitator who can fix things on their end.

The param validation is run against the POST body and would more likely indicate the rapidpro flow not quite setup correctly. It also returns a json response where the others are text response. So maybe we keep that one as 400?

The function code is here if useful:
https://github.com/IDEMSInternational/open-app-builder-functions/blob/main/src/rapidpro-shared-data/group-join.ts

[istride]

In general, we should think to use 422 for application-level errors, unless there is a good reason to use 400 - which may be automatic because, presumably, if there is a structural problem with the request itself, the cloud function would not be called. With param validation, I imagine there is a scenario where the JSON is valid, but does not fit the schema, which would be an application-level error.

I strongly recommend always returning a JSON response in a consistent format, or otherwise just returning a consistent response i.e., if not JSON then always text. When it comes to error messaging, I think @fagiothree may want the option to interpret those to the end user, rather than relay them verbatim. I think it's very likely those messages will need to be translated too, so it's probably best to leave the exact wording to the flow author.

From RapidPro's perspective, the call_webhook action will be used to make requests.

[ChrisMarsh82]

@chrismclarke data to bring over from RapidPro
UUID
ParentTextID
Name (what the parent wants to be called)
Gender

[chrismclarke]

In general, we should think to use 422 for application-level errors, unless there is a good reason to use 400 - which may be automatic because, presumably, if there is a structural problem with the request itself, the cloud function would not be called. With param validation, I imagine there is a scenario where the JSON is valid, but does not fit the schema, which would be an application-level error.

I strongly recommend always returning a JSON response in a consistent format, or otherwise just returning a consistent response i.e., if not JSON then always text. When it comes to error messaging, I think @fagiothree may want the option to interpret those to the end user, rather than relay them verbatim. I think it's very likely those messages will need to be translated too, so it's probably best to leave the exact wording to the flow author.

From RapidPro's perspective, the call_webhook action will be used to make requests.

Sounds good, I've standardised the response codes and formatting. Examples of response codes can be found at
https://github.com/IDEMSInternational/open-app-builder-functions/blob/main/src/rapidpro-shared-data/responses.ts

More detailed examples of test case request/responses can also be found in the test suite
https://github.com/IDEMSInternational/open-app-builder-functions/blob/main/src/rapidpro-shared-data/group-join.test.ts

Next step for this issue is to add support in the app to generate access codes, and then the frontend UI to display parent group data. I'll try and get them done in the next couple days