This is not a high priority item, but it needs to be documented.

The Pull OnCore Subjects features does not support DAGs. In a multi-site trial, the Pull OnCore Subjects feature will likely expose PII from OnCore to every site defined in the project. A better design would allow the OnCore Study Site to be associated with each DAG in a project. The OnCore Enrollment data includes Study Site in a StudyData object. The OnCore enrollment data should be subsetted by the current user's DAG's Study Site to display only enrollees for their site. Data read from REDCap should be similarly subsetted. Any record's added from OnCore must set the DAG for the new record.

Upgrading to REDCap 9.0.1 causes a never-ending wait after selecting records and attempting to Pull OnCore Subjects, user can only cancel or leave page and no records are added. However, all redcap_entity databases fill as expected.

Also makes the computer running the VM's fan turn on, even after cancelling.

The REDCap OnCore Client needs to verify that users attempting to access the enrollment data for a study are listed as study staff on that study. Study staff data can be provided by the OnCore API via the GetProtocolStaff method. Staff needs to be looked up via UFID. Study staff data should be cached like any other data fetched form OnCore. Managing queries of a user's UFID requires that we store that attribute as an extension of the REDCap user information.

To achieve these goals, I recommend these functions be implemented:

1. Add a new entity named user_attributes with redcap_entity. This entity needs 2 attributes: username, staff_id
2. For each user that opens the Pull OnCore Subjects page, test for a server environment variable named HTTP_GLID. If it exists, store/update it in the staff_id attribute with a username equal to the $REDCAP_USER.
3. Add a new entity named protocol_staff. The entity should have 3 attributes: protocol_id (or whatever we called this attribute in the protocols table), staff_id, and stop_date
4. Add an action to the existing actions that execute when the Refresh OnCore data button is pressed. The new action should use the getProtocolStaff OnCore API method to fetch the protocolStaff for this one protocol, store that data in the protocol_staff entity.
5. Modify the actions that present data on the Pull OnCore Subjects plugin page to check the authorization of the currently logged in user before presenting enrollment data. Only users whose staff_id is listed in the current protocol's protocol_staff table with a stop date in the future are authorized to see enrollment data.
6. Make sure the Refresh OnCore data button is visible and works at all times. This will allow people to refresh cached protocol staff data that might be blocking their access to the enrollment data.

Here's the workflow of a normal interaction with the new features that verify the logged in user is on staff:

Add a feature to save a server variable's value as the Institutional ID.

Apache sets a number of variables and hands them to the called application via the server environment. In a shibboleth environment, one of these could be the institutional ID that we would like to see in the staff_id field of the oncore_staff_identifier entity. We need to read that environment variable and write its value and the current username into a record of the oncore_staff_identifier entity. That should allow us to lookup the staff_id when checking if the currently logged in user is in the protocol_staff entity for the current protocol. To make this feature work at different sites, sites without shibboileth, and development environments, the environment variables read should be configurable.

To that end, do these things:

1. Add a configuration field to the system-level configuration of the redcap_oncore_client. Name that field something like "staff_id_variable_name". It should be a text field.
2. Modify the subjectsPull plugin page or its included classes to read the name of the environment variable in the above config entry, read the value of that environment variable and write/update a record in the oncore_staff_identifier with that value as the staff_id attribute and the currently logged in REDCap user's username as the user_id attribute.

A good place to do this step might be just before

Make sure you test that the var exists. Also, test that the value stored in the var has non-zero length. Also, verify that this feature does not insert an additional record on each page load lest oncore_staff_identifier grow unchecked.

Note: To test this feature any server environment variable that is constant across page reloads will provide suitable input. One can see all the vars using the phpInfo() command. These variables would be suitable: HTTP_HOST, SERVER_ADDR, SERVER_NAME

The Sync OnCore Subjects section of README.md needs content and a retitling to Pull OnCore Subjects

See this REDCap Entity issue for more information.

Pseudocode solution:

if REDCAP_VERSION < 9.8.0
     include_once APP_PATH_DOCROOT . 'ProjectGeneral/form_renderer_functions.php'; 
else
    use NewFormRendererFunctionsClass;

The PHPMD static analyzer pointed out the following minor issues that you might want to address:

classes/entity/list/SubjectsDiffList.php
Line 179: $inline set but never used

classes/entity/SubjectDiff.php
Line 125: $new_record used but never set.

ExternalModule.php
Line 376: $client set but never used
Line 379: $no set but never used
Line 398: $mappings set but never used
Line 472: $key set but never used
Line 528: $id set but never used

Steps to recreate:

1. Login as admin
2. Create a new project, enable and configure the OnCore Client module
3. Go to the Pull Oncore Subjects page
4. Click the Refresh OnCore data button
5. Create another new project, enable and configure its OnCore Client module (Protocol does not matter, it can be the same or different as the first project)
6. Navigate to the newest projects Pull OnCore Subjects page
7. Click the Refresh OnCore data button and observe a PHP error

To solve, navigate to Control Center, External Modules > EntityDB Manager. Drop the table redcap_entity_oncore_subject_diff and create it again. Module will work as long as another project is not created using the OnCore Client module.

Steps to recreate:

1. Create a new project, configure OnCore Client, under Subject Field Mappings, use at least one OnCore variable to populate a REDCap variable
2. Navigate to Pull OnCore Subjects, select any number of subjects and click the Pull OnCore Subjects button
3. Navigate back to the configuration page, select at least one more OnCore variable to populate another REDCap variable and save changes
4. Navigate back to Pull OnCore Subjects, select any number of OnCore subjects which show they need an update, click the Pull OnCore Subjects button again
5. Observe table is now populated with "Not linked" records whose REDCap Record IDs correspond to those of the updated subjects
6. Navigate to Add/Edit Records, observe that "Not linked" records contain all data except that which was just brought in; updated records have been appended to existing records

The SOAP client does not automatically install with the module.

Pull OnCore Subjects exposes project id as a search filterable parameter. This makes no sense as that page is inherently project-specific. While the Project ID menu is populated, changing the value produces meaningless and blank results. The Project ID search term should be hidden.

The OnCore client only sees open protocols. In using the SIP URL, the OnCore client is only seeing protocols that are open to accrual. REDCap project builders using this module would be unable to configure their project before accrual starts. We need an alternative way to enumerate the protocols.

As the protocol numbers are sequential, we could allow the specification of some combination of naming pattern, base name, and starting number that would allow the ONCore client to guess protocol numbers. E.g., it could start at number 00042, using a prefix of "OCR-", to query for OCR-00042, OCR-00043, etc. until it could not locate OCR-NNNNN at which point it would stop assuming it had reached the highest allocated protocol ID.

With these guessed protocol IDs, the OnCore client can query the WSDL interface to get full details about the protocol and its enrollment. It can use a limited set of this data to populate the "select protocol" drop down.

The documentation in the README has fallen behind the current feature set and redcap entity version. I have a branch where I am addressing this. The work is mostly done. See https://github.com/pbchase/redcap_oncore_client/tree/update_readme_for_redcap_entity_v2

I'll make a pull request as soon as I can address the missing imagery for the Sync OnCore subjects section. I have contacted Harshita for access to a project with guaranteed public-safe names.

OnCore provides two fields that might be of interest to study teams: "Subject ID" and SequenceNumber. These should be added to the interface. SequenceNumber is especially important. See Harshita's Research for detail.

Remove developers who have left CTS-IT from config.json. Add them to AUTHORS.md, if needed. See https://github.com/ctsit/auto_populate_fields/blob/master/AUTHORS.md for a template for the authors file if needed. Adjust the content to reflect the contributors.

please move example file of code and project xml into examples folder.

This was likely meant to have been taken out at some point.

The Pull OnCore Subjects and Link to subject buttons are not working reliably. These features need some review. They worked on Tiago's dev instance, but they did not work on my dev instance. Everything surrounding them did, but the actually link and import operations failed.

Cannot create a second record if OnCore's PrimaryIdentifier is not mapped to REDCap's record_id

@ChemiKyle, I got a weird synch problem in my Oncore client testing today. Testing with Protocol OCR20388 in the https://oncore-test.ahc.ufl.edu host, one record would not synchronize right.

mysql> select * from redcap_entity_oncore_subject_diff;
+----+------------+------------+------------+-----------+------------+--------------+-------------+-----------+----------+---------------------------------+
| id | created    | updated    | subject_id | record_id | project_id | subject_name | subject_dob | type      | status   | diff                            |
+----+------------+------------+------------+-----------+------------+--------------+-------------+-----------+----------+---------------------------------+
| 75 | 1565000765 | 1565000765 |        200 | 989       |         14 | Pup Pluto    | -1406577600 | data_diff | on_study | {"LastName":["Pluto","Pluto "]} |
+----+------------+------------+------------+-----------+------------+--------------+-------------+-----------+----------+---------------------------------+

The problem is a trailing space on the LastName field. We must be trimming the data before we write it. We need to not trim it. We need to honor whatever garbage they offer us. :-)

License file name doesn't match spec. The file should be named LICENSE

If the OnCore API delivers any of its values in a nested array or object, they will not be inserted into the REDCap entity db. In SubjectDiff.php, converting the data to json, and converting it back casts all nested objects as arrays which can then be iterated over using array_walk_recursive, allowing them to be brought into REDCap via Pull OnCore Subjects, but it is not recognized by oncore_subjects_diff, resulting in users seeing that a record needs update.

The redcap_oncore_client can consume enrollment details from OnCore, but it does not know how to send summary accrual data to OnCore. CTS-IT is working on a spec to do that at Adding study enrollment summary accrual to the REDCap OnCore Client

Pull OnCore Subjects does not support classic projects. It works only with longitudinal projects.

It would be helpful to other sites--and perhaps even UF-- if they/we could choose whether they want to use the REDCap "Institution ID" field in place of the side table managed by REDCap Entity. I see three use cases:

1. You are using REDCap's "Institution ID" field and it has the right info to align with OnCore.
2. You are using REDCap's "Institution ID" field and it has the wrong info for aligning with OnCore.
3. You are not using REDCap's "Institution ID" field.

For option 1, you'd probably use the REDCap "Institution ID" field so you can keep your existing business process.

For option 2, you'd probably want to use the side table. Again, this would let you keep your existing business process.

For option 3, you could go either way.

This could be implemented with a checkbox in the system configuration the redcap_oncore_client. The code that writes the Institutional ID would need to check this value. The code that reads it would also need to check this value. Alternatively, abstract those set and get operations into a small class.

classes/entity/list/SubjectsDiffList.php

method getRowAttributes

$data is unused

The User Attributes entity is alternately broad and specific. The entity goes by these monikers in the ExternalModules.php

        $types['user_attributes'] = [
            'label' => 'Local User Information',
            'label_plural' => 'Local Users Information',

Yet for the plugin page (in config.json) we refer to it with Enter Study Staff. i.e.

                "name": "Enter Study Staff",
                "icon": "group_gear",
                "url": "plugins/user_attributes.php"

Are these "study staff" details or are we defining a large list of user attributes? I am conflicted here. At UF, the study staff ID is the local UFID. It could be useful in other modules. Yet we are collecting it only within the context of the OnCore Client. 'user_attributes' feels more like system-wide service.

My inclination is to rename this entity study_staff_attributes or oncore_study_staff_attributes. I welcome input on this matter.

Oncore client 2.2.0 with RCE 2.3.0 often fails to pull subjects into redcap when autonumbering is off. fails have been seen with 20-ish records pulled at a time.

When record auto-numbering is on, the client seems 100% reliable.