Below we use $SofTool to generically refer to GradePRO or MAGIC.
Creating a linked account (Phase1)
Users will log in to $SofTool using their Cochrane Account.
Any Cochrane-review linked projects that were previously created will be shown in their list of projects.
If a user's details have changed on their Cochrane Account, they are also updated in $SofTool upon login.
It is possible that accounts are de-duplicated in Archie, in which case the person ID may change, in which case the account link is lost, and the user would end up in a new empty account. There is a RabbitMQ event stream that would allow $SofTool to handle these events automatically. However this is not a hard requirement, as this is expected to be extremely rare at the stage where someone is a Cochrane author. So handling any cases through support when they arise would be acceptable. Cochrane will be able to confirm if a de-duplication took place for a particular ID.
Create a SoF table from RevMan Web (Phase1)
The user has a Cochrane account that is linked with a GRADEpro account
RevMan Web will have a button to "Create Summary of Findings table in $SofTool". This will link out to $SofTool to a Cochrane namespaced URL, e.g. POST ${createCochraneSofUrl}?reviewId={reviewId}
There are three scenarios to handle when the user clicks create SoF or Edit SoF and is not logged in to GRADEpro:
In phase 1:
Scenario 1: The user has a Cochrane account that is linked with a GRADEpro account
If the user is already logged in with a GRADEpro account, he/she will see the "Choose analysis group screen immediately". After choosing, our API will create a table in GRADEpro and link it to the SoF table created in RevMan.
Then, the user will be redirected to the GRADEpro application. If user is not logged in/logged in to different GRADEpro account, he will be prompted to log in with Cochrane account. Then he/she will see screen for choosing analysis group, as above.
Scenario 2: The user has a Cochrane account and a GRADEpro account but they are not linked
The user will be prompted to log in with Cochrane account, however it will not work until phase 2 is complete.
Scenario 3: The user has a Cochrane account but no GRADEpro account
The user will be prompted to log in with Cochrane account, however it will not work until phase 2 is complete.
In phase 2:
Scenario 1: as above.
Scenario 2: if user has GRADEpro account registered to same email that is used by Cochrane account, he will be prompted to log in with Cochrane account and the type password to GRADEpro account.
This will link accounts. After that, user will continue to choose analysis group screen.
Scenario 3: if there is no GRADEpro account registered to email used by Cochrane account, user will have 2 options: link his Cochrane account to some other GRADEpro account (and he/she will need to provide credentials for this account;
the process will then be as in scenario 2) or to create GRADEpro account based on data from Cochrane account. This will mean that he/she is agreeing to our Terms of Service, Privacy Policy (required) and may also agree to opt in to our
newsletter (not mandatory). After creation, accounts will be linked and user will continue to choosing analysis group screen as above.
If there is already a project in $SofTool for {reviewId}, this will create a new SoF table within the organization Cochrane. If there isn't one, this will create a project linked to the relevant Cochrane review, and create a new SoF table within that review.
If the linked Cochrane Account does not have write permission to the review, permission is denied.
The newly created SoF table will be opened for editing in $SofTool.
$SofTool will query ReviewDB for the relevant information to populate a SoF table, and present a similar user interface as currently for projects based on a RM5 file. Analyses with no totals will be imported as non estimable.
$SofTool will create the SoF table in RevMan Web as soon as it has been set up. It will persist the ID of the SoF table in RevMan Web, so that changes to the SoF table can overwrite the previously inserted SoF table.
$SofTool will update the SoF in RevMan Web whenever it is saved in $SofTool (but throttling to limit rapid-fire updates is acceptable).
$SofTool will have full ownership of the SoF table in RevMan Web. The user will not be able to edit the SoF table directly in RevMan Web, and will instead be directed to $SofTool to do so. $SofTool may overwrite the contents of a SoF table it owns at any time. Deleting the SoF table can only be done in $SofTool.
RevMan Web will have a button to "Edit Summary of Findings table in $SofTool". This will link to $SofTool to a Cochrane namespaced URL, e.g. GET ${editCochraneSofUrl}?reviewId={reviewId}&sofTableId={sofTableId}, where {sofTableId} is the RevMan Web ID of the SoF table.
Updating a SoF table when the underlying data changes in RevMan Web (Phase 1)
$SofTool will allow the user to check for changes to the review. This may happen on login to $SofTool, but the user should also be able to do this by clicking a "Check review for changes" button. $SofTool will check which SoF tables are affected (if any), make the required changes, and alert the user to them if necessary.
Fully automatic updating of SoF tables when the underlying data change in RevMan Web is not in scope for this proposal. Primarily that is due to the expected complexity, but it may also be desirable to require human intervention for the updating of the SoF table (e.g. to check if GRADE decisions need updating). A middle ground could be an "update" button that doesn't pull the user into $SofTool, but any rows with changes should be clearly marked as needing user attention.
Alerting the user when they may need to update a SoF table (Phase2)
To alert the user when a SoF table needs updating, RevMan Web needs to be aware which analyses are used in a SoF table (and ideally when the data were retrieved). $SofTool could include this as meta-data, if an appropriate API is provided by ReviewDB. The validation report could be used for this.
Delete a SoF table
SoF tables manages by SoFTool can only be deleted from the SoFTool. In RevMan Web, the delete button is disabled and the user is encouraged to go to SoFTool to delete it. The user should be warned in SoFTool that deleting the table in GRADEpro, also deletes in RevMan Web.
Creating a SoF table from $SofTool (Phase2)
When a SoF table is created in a project linked to RevMan Web in $SofTool, the table should also be created in RevMan Web.
Synchronising access to reviews (Phase2)
Besides the check for write permission in the authorization flow described above, it is desirable to synchronise access rights between $SofTool and RevMan for a review. This could be done whenever data is pulled on the review, by comparing the author list from RevMan to the list from $SofTool.
It may also be that the user does not have the right to read or write the review, although he/she is a author. This could be when the review is in editorial phase, or when it is checked out from Archie. This would result in errors returned from the ReviewDB API. In those cases changes to be pushed need to be queued up. Messaging to the user is also needed.
A user's token may also become invalid for various reasons that require re-authentication, e.g. after expiry of the refresh token. This needs to be handled, but can be assumed to be a rare occurrence.
Non-Cochrane contributors (not included)
$SofTool may want to allow non-Cochrane users of their tool to contribute to a Cochrane review project. These users then need to be added from within the $SofTool. The main issue is that these users won't have a valid Cochrane token, so synchronisation will have to use the token for another user.
TODO: Cochrane to evaluate if e.g. review-scope tokens can be granted to handle this more smoothly.
Editing of the SoF table in RevMan Web (Phase not determined)
Editing of a SoF table owned by $SofTool will not be allowed at all in RevMan Web. We may consider the following in future:
- RevMan Web may allow the user to copy a SoF table created in $SofTool, and modify the copy. $SofTool will have no ownership over the copy.
- RevMan Web may allow the user to "ignore" a SoF table to exclude it from the published review. This also means that it can't be linked to in the text. $SofTool should not set the "ignored" status of SoF tables.
Widget / iSoF linking (Phase2)
$SofTool may want to include a link to the interactive Summary of Findings widget on it's own platform with the static content of the SoF. Ideally this would allow progressive enhancement on the Cochrane Library - where the iSoF widget would be displayed when possible, or display a standard SoF with a link to the iSoF when not.
Depositing of structured data (not included)
Depositing of structured data by $SofTool can be considered, but we would need to identify a common format between the tools, and the use cases we want to enable. These could be related to publishing/CLib, linked data, or prioritisation. Consultation needed.
Future considerations - changes to data structures (not included)
Should be more easily/reliably able to identify Intervention/Comparator and Outcome for an analysis. Might we also be able to make it easier to identify the Population?