= CiviCRM LCBRU Use Case

Tags: [[CiviCRM Legacy]] [[GENVASC Study]]

[[CiviCRM HowTo Install]]

[[CiviCRM GENVASC Use case description]]

[[CiviCRM GENVASC Report customisation]]

[[redcap_multiserver|REDCap Multi-server set up]] for [[GRAPHIC Study]] laptops

Currently this page is a record of our deployment of CiviCRM - initially as a recruitment process manager for the GENVASC project.

The intention is to use drupal modules to deliver the 'LCBRU' version of civicrm. First, install civicrm. Then install the 'lcbru' module, which will create option group entries, custom fields, contact sub-types, potentially even contacts for GP surgeries, etc., in a consistent way. Then install the ice_messaging module.

briccsapp04.xuhl-tr.nhs.uk - test system[[BR]]
briccsapp05.xuhl-tr.nhs.uk - live system[[BR]]

== CiviCRM Object Model ==


=== Contact Types ===

We can create sub-types which allow for specific custom fields and relationships to be built. This is most important to differentiate between staff (either LCBRU staff or external staff) and those who might be study subjects, who we will call 'contacts'.

Records can belong to more than one sub-type, but sub-types cannot be nested.

* Individual - Contact
* Individual - LCBRU staff
* Individual - Health worker (includes GPs, practice nurses, and LCBRU staff)

* Organisation - GP Surgery - each surgery can have multiple addresses for branch surgeries. Set branch surgery entries to 'other' location type, and the primary surgery as 'main'.

Custom fields for addresses
* ICE code - one per address of the surgery (branch surgeries have separate ICE codes)

=== Contacts ===
Contact entries for LCBRU staff are created automatically from the relevant drupal account. And the drupal account is created automatically at first log-in using LDAP. Smooth.

* Address - address doesn't automatically create via API when a contact is created.
  * State / Province - is replaced by 'county' during localization to UK
  * County - do not use (this is a different division than UK County

Custom fields for Contacts of sub-type 'contact'
* NHS number
* UHL S number

Custom fields for Contacts of sub-type 'health worker'
* GMC number (optional, only applies to GP)
* Practitioner code (optional, only applies to GP)
* ICE code (optional, only applies to GP or practice nurse)
* GCP training date - to help track renewals, this might be better being an activity

Custom fields for Contacts of sub-type 'GP Surgery'
* Practice code

=== Groups ===

* LCBRU staff (ACL group, to allow for ACL role of 'LCBRU staff' to have edit permissions on contacts etc) - could this be a 'SMART GROUP' based on the drupal account being in the associated drupal role 'LCBRU staff'? Needs to interact with the designated contact type.


=== Relationships ===

Contact A     -> "GP is"         -> GP B
GP B          -> "GP of"         -> Contact A

Contact A     -> "GP Surgery is" -> GP Surgery B
GP Surgery B  -> "GP Surgery of" -> Contact A

Use 'employer/employee' relationships to model GPs and practice staff to their respective GP Practices


=== Tags ===

How are we going to use 'tags'? For the time being delete all tags.


=== Option Groups ===

Option Groups provide extensible lists of available options for particular fields.

Gender is pre-set with 'Female', 'Male' and 'Transgender'. Added 'Not Specified' and 'Not Known' to match the NHS national codes.

Individual contact prefixes is pre-set with 'Dr', 'Mr', 'Mrs', 'Ms'. Added 'Professor'


=== Case type ===

Represents the study.

Needs custom fields to represent the study ID number? Since 4.2.0 custom fields can be attached to a specific case type. This works quite nicely but will need validating that it is unique before entry into the database.

Disable the sample case types. Create a new case type for 'GENVASC'.

Each case type requires an xml configuration file in /sites/all/civicrm_templates/CRM/Case/xml/configuration/[[BR]]
That directory needs creating, and then /sites/all/civicrm_templates directory needs to be specified in admin->system settings->directories


=== Cases ===
Represents the recruitment of a participant against a specific study.[[BR]]
Might need a revised webform template (profile) as some fields are not really relevant.[[BR]]

* Encounter Medium (represents the recruitment method) - needs an additional option for GP surgery, and a further option for when activities take place with no direct contact with the participant.
* Location - not relevant, can be dropped.
* Details - not relevant, can be dropped.
* Subject - not relevant, can be dropped.
* Case type - drop down selection of study names (currently only GENVASC)
* Case status - defined seven so far: pending(opened), recruited (opened), available (opened), declined (closed), withdrawn (closed), excluded (closed), completed (closed).
* Duration - not relevant, can be dropped.


=== Case roles ===
Currently the following defined for GENVASC: recruiter, venepuncturist, study administrator, study manager, lab processor, principal investigator.

* Case roles are a sub-set of available relationships, as follows:
  * Recruiter - B is 'Study Recruiter' of A. A is 'Recruited By' B.
  * Venepuncturist - B is 'Venepuncturist' of A. A is 'Blood Samples Taken By' B.
  * Study administrator - B is 'Study Administrator' of A. A is 'Study Subject' B.
  * Study manager - B is 'Study Manager' of A. A is 'In study managed by' B.
  * Lab processor - B is 'Laboratory Processor' of A. A is 'samples processed by' B.
  * Principal Investigator - B is 'Principal Investigator' of A. A is 'In study for P.I.' B.
    
Note: When the case is displayed, each role which is vacant is labelled with the 'B' relationship label, e.g. "Study Manager". This label stays in place even if the role is filled. However when the case is reloaded later, the label is changed to be the 'A' label, e.g. "In study managed by". This is OK but very confusing.

=== Activities ===

The standard GENVASC timeline consists of:

1. Recruit (in practice, recorded on civicrm retrospectively
2. Draw bloods (in practice, recorded on civicrm retrospectively
3. Register on civiCRM (from ICE messaging system) - record activities 1,2,3 at this point.
4. Fetch samples from pathology department
5. Check consent form details
6. Process bloods in LCB
7. 30 day status change to 'available'

=== Withdrawal from study ===

Initially we thought that 'withdraw' needed to be an activity. But in fact the enrolment status captures it better, and records an activity of type 'change enrolment status'. So we should use the 'Change Enrolment Status' function (by editing the status) rather than using a withdrawal activity. But we might well need additional custom data to reflect the various possible 'levels' of withdrawal in a study.

Following a meeting with Chris and Emma, we are implementing the following: a custom group ('GENVASC withdrawal status') with one field ('GENVASC withdrawal status', alphanumeric, radio button options), with three options: not withdrawn ('0'), withdrawal but keep data and samples ('A') or withdrawal, destroy samples and data ('B'). There is an SOP for processing withdrawal requests.

=== Completion of study ===

As with 'withdraw' the best way to capture the fact that a participant has reached the end of a study protocol is to change their status, and this records an activity of type 'change enrolment status'. So we should use the 'Change Enrolment Status' function (by editing the status) rather than using a 'completed' activity. A new status therefore needs to be added of 'completed'.

== Mailings, templates and tokens ==
CiviCRM uses tokens as placeholders for mailings. Additional tokens can be defined in the drupal module LCBRU, in the civicrm_hooks.php file - this will be the general repository for 'clever' civicrm work.

== Note regarding GP practice data ==
As more studies come on board and use Civi as their contact management tool, it is important to apply some consistency to the way records are created. 

In particular, GP surgery contacts which apply to all studies should be created in the following style and contain the national GP C Code in Brackets as part of the GP surgery title.

e.g. Dr ZS Osama and Partners (C82643)

This means that when searching for a practice to see if it has already been registered you can enter the C code in the search box and it will identify the practice quickly if it already exists in Civi.

As there are still some GP Surgeries that need amending to the correct format, it currently makes sense to also check for the GP name or GP address before creating a new GP contact in the style above.

If you are unsure of the GP Practice code, I have saved a copy of the current national list on the UHL BRICCS drive in the ‘Civi’ folder. Performing a search of the GP practice name or address using the find function will provide the C code in column ‘A’.

== CiviCRM and Drupal Cron to automate tasks ==

We use Drupal's cron to trigger automated jobs in CiviCRM for various tasks. Full details are on the [[Drupal HowTo Write Cron Tasks for CiviCRM]] page. 

== CiviCRM for Study Management ==

At the BRISSkit hack on 23/24 February 2015 we explored the use of CiviCRM for study management and monitoring, with the notes being kept at [[civicrm_study_management|CiviCRM for Study Management]].

[[BackLinks]]