Setting an Ocean eForm to Update an EMR Demographic Field

Questions on Ocean eForms have the ability to automatically populate certain fields in the patient's chart in the EMR. To set an item in an eForm to update the corresponding field in the patient's chart, follow the steps below.

PS Suite or Accuro Other EMR
  • Open your form in the eForm Editor.
  • Navigate to the "Note Formatting" tab.
  • Set the appropriate value for "Populate answer for EMR Field:".

Note for PS Suite Users:

For a comprehensive list of the various fields that the "Populate answer for EMR Field" options map to, please refer to "Populate answer for EMR Field Options & Corresponding Fields in PS Suite".


Using Keywords to Automatically Insert Content

Keywords allow you to insert a piece of data from the patient object (usually from the EMR) into a caption, to prepopulate a field, or as part of a note. To see a list of available keywords, simply type @ and the menu will appear in the editor. A full list of options is also included in the chart below.

To indicate a keyword, just add "@" to the beginning. For example, "Dear @ptPreferredOrFirstName" will appear as "Dear Jacob".

You can also access keyword values in a script with the ScriptUtil.getKeyword() function, like "ScriptUtil.getKeyword('@ptName')". This is particularly useful for tablet rules, since a rule can access most of the patients information via this function. For example, you can show a COPD assessment questionnaire if the patient has COPD in their problem list or past medical history like this:

ScriptUtil.getKeyword('@ptHas.copd') == 'Y'
Copy Rule

Keywords can be very useful in conjunction with EMRFields to allow patient to update their profile automatically. For example, by setting the default text of a text field to "@ptPreferredName" and setting the EMRField mapping on the same item to "preferredName", the initial value will be the patient's preferred name in the EMR and any changes will be applied to the preferred name field in the EMR.

Note that not all keywords work for all EMRs.

Some keywords accept suffixes, which should be added after a trailing period. For example, "@ptHnExpiryDate.yyyysmmsdd" will show the date as "2015/06/21".

Keyword(preface with '@') Description and Known EMR Limitations (if any) Available on Tablet Available on Ocean Online Available on Ocean Reminders
date The current date. Y Y Y
time The current time. Y Y Y
site The name of the site. N Y Y
ptTitle

The patient's title.

e.g. "Dr."
Y Y Y
ptSuffix

The patient's suffix, if any.

e.g. "Jr."

Y Y Y
ptName The patient's full name. Y Y Y
ptSurname The patient's surname/last name. Y Y Y
ptFirstName The patient's first name. Y Y Y
ptPreferredName The preferred name of the patient, if set. For simple display purposes, consider using ptPreferredOrFirstName. Y Y Y
ptPreferredOrFirstName The patient's preferred name, if set, or the first name if no preferred name is available. Useful for salutations. Y Y Y
ptSecondName The patient's middle/second name. Y Y Y
ptSecondNameInitials The patient's 'middle initial' (the first letter of the second/middle name). Y Y Y
ptAddress1 The first line of the patient's main (mailing) address. Y Y Y
ptAddress2 The second line of the patient's main (mailing) address. Y Y Y
ptCity The city of the patient's main (mailing) address. Y Y Y
ptProvince The province of the patient's main (mailing) address. Y Y Y
ptCountry The country of the patient's main (mailing) address. Y Y Y
ptPostal The postal code of the patient's main (mailing) address. Y Y Y
ptAddr2Line1 The first line of the patient's second (e.g. residence) address. Y Y Y
ptAddr2Line2 The second line of the patient's second (e.g. residence) address. Y Y Y
ptAddr2City The city of the patient's second (e.g. residence) address. Y Y Y
ptAddr2Province The province of the patient's second (e.g. residence) address. Y Y Y
ptAddr2Country The country of the patient's second (e.g. residence) address. Y Y Y
ptAddr2Postal The postal code of the patient's second (e.g. residence) address. Y Y Y
ptBirthDate The patient's birth date. Y Y Y
ptApproxAgeInDays The patient's approximate age, measured as the number of days as an integer. Y Y Y
ptHomePhone The patient's home phone number. Y Y Y
ptBusinessPhone The patient's business phone number. Y Y Y
ptBusinessExt The extension of the patient's business phone number (if it is optionally specified separately from the business phone). Y Y Y
ptMobilePhone The patient's mobile/cell phone number. Y Y Y
ptEmail The patient's main email address. Y Y Y
ptSex Either "M" or "F". Y Y Y
ptIsMale True if the patient is male. Y Y Y
ptIsFemale True if the patient is female. Y Y Y
ptHnVC The health number verification code (for ON health numbers). Y Y Y
ptHnProv The HN province. Y Y Y
ptHnExpiryDate The HN expiry date. Y Y Y
ptHn The patient's health number (HN). Y Y Y
ptAge The patient's age in years. Y Y Y
ptHisHer Either "his" or "her" depending on ptSex. Y Y Y
ptHisHer.cap Either "His" or "Her" (capitalized) depending on ptSex. Y Y Y
ptHeShe Either "he" or "she" depending on ptSex. Y Y Y
ptHeShe.cap Either "He" or "She" (capitalized) depending on ptSex. Y Y Y
ptHimHer Either "him" or "her" depending on ptSex. Y Y Y
ptMaleFemale Either "male" or "female" depending on ptSex. Y Y Y
ptManWoman Either "man" or "woman" depending on ptSex. Y Y Y
ptFamilyDoc The patient's family doc, as per patient record. Y Y Y
ptClinicDoc

The patient's clinic doc.

e.g. could be specialist

Y Y Y
ptComments

Any comments that have been typed into the demographics section of the patient chart.

EMR: PS Suite only

Y Y Y
ptCppOneLine

A section of the patient profile ("CPP") flatted to a single line, delimited by semi-colon.

e.g. ptCppOneLine.prob might yield:

"dm2; chf"

EMR: PS Suite only
Y Y Y
ptCpp

A section of the patient profile ("CPP") with one line per item.

e.g. @ptCpp.prob might yield:

"dm2

chf"

Some other common CPP fields include: ptCpp.pmhx (past medical history), ptCpp.fhx (family history), ptCpp.rx (medications).

EMR: PS Suite only
Y Y Y
ptFullCpp The entire patient profile, with each section heading in uppercase. Y Y Y
ptCheckIfHas

Either "Y" or "" depending on whether the patient has the condition.

e.g. @ptCheckIfHas('dm2')

Y Y Y
ptRxFriendly

A patient-friendly version of one of the patient's medications. Use a suffix to indicate which med.

e.g. @ptRxFriendly.0 would be the first med on file

Y Y Y
ptHas

Either "Y" or "N" depending on whether the patient has the condition. Also checks past medical history if available.

e.g. @ptHas('dm2')

Y Y Y
ptLatestVal

Provides the latest lab result/vital for a particular measurement. Supported vitals include ht, wt, bp, cr, egfr, a1c, oceanvital.

e.g. @ptLatestVal.a1c

Y Y Y
ptEmergencyContactPhone The phone number of the emergency contact/next of kin (requires special "@" delimiter in PSS Next of kin field). Y Y Y
ptEmergencyContactRelationship

The patient's relationship to the emergency contact/next of kin (requires special '@' delimiter in PSS Next of kin field).

EMR: PS Suite only

Y Y Y
ptEmergencyContactIsPoA Y/N whether the emergency contact/next of kin has POA (requires special '@' delimiter in PSS Next of kin field). Y Y Y
ptEmergencyContact The patient's emergency contact/next of kin. Y Y Y
ptCustom

An EMR's custom demographic field, as specified by the keyword's suffix. Note that the field is stripped of non-alphanumeric characters; spaces and dashes are converted to underscores.

e.g. "ptCustom.my_field" for a custom demographic field named "My Field"

e.g. "ptCustom.phq_9" for a custom demographic field named "PHQ-9"

EMR: Accuro only

N Y N
ptExternalRef

The patient's reference in the EMR.

e.g. the patient ID

Y Y Y
ptNextApptDate

This field is deprecated, use "apptDate" instead

A textual description of the patient's next upcoming appointment date and time, or "(not available)".

* Most EMR interfaces (other than PS Suite), as well as the tablet, do not populate this field.

EMR: PS Suite only

N Y* N
apptDate

A textual description of the patient's next upcoming appointment date.

EMR: Not supported in OSCAR

N Y Y
apptTime

A textual description of the patient's next upcoming appointment time.

EMR: Not supported in OSCAR

N Y Y
ptPreferredPharmacy

The preferred pharmacy for the patient.

EMR: PS Suite only

Y Y Y
user.properName

The proper name of the current user.

* This is limited to secure message and web questionnaire invitations and cannot be used in eForms or rules.

e.g. "A message from Dr. John Smith"

N Y* N
providerName The name of the patient's provider for their scheduled appointment. Y Y Y

PS Suite: "Populate answer for EMR Field" Options & Corresponding Fields in PS Suite

  • The "Populate answer for EMR Field" field in the eForm Editor will allow you to set answers to certain questions to autopopulate certain fields in your patient's chart in your EMR.
  • The dropdown options for this field correspond to either demographics or CPP fields in the patient's chart in PS Suite.

The table below describes which dropdown option in this eForm Editor's "Populate answer for EMR Field" field correspond to which demographics fields in PS Suite.

Populate answer for EMR Field PS Suite Demographics Field
firstName First name
surname Surname
preferredName Preferred name
secondName Middle name
maidenName Maiden name
title Title
suffix Suffix
streetNumber Street #
address Mailing Address: Address line 1 or Street Name
addressLine2Label Mailing Address: Extra Type
addressLine2 Mailing Address: Address Line 2 or Extra #
city Mailing Address: City
province Mailing Address: Province
postalCode Mailing Address: Postal code
addr2Line1 Second Address: Address line 1 or Street Name
addr2Line2Label Second Address: Extra Type
addr2Line2 Second Address: Address Line 2 or Extra #
addr2City Second Address: City
addr2Province Second Address: Province
addr2Postal Second Address: Postal code
birthDate Birthdate
email Email
homePhone Home phone
businessPhone Business phone
businessPhoneExt Business phone Ext
mobilePhone Mobile
pmoc Preferred method of contact
insuranceNumber Insurance number
chartNumber Patient #
emergencyContact Next of kin
emergencyContactPhone Next of kin (optional 2nd field, separated by '@')
emergencyContactRelationship Next of kin (optional 3rd field, separated by '@')
emergencyContactIsPoA Next of kin (optional 4th field, separated by '@')
sex Sex
hn HC HN
hnProv HC Prov
hnVC HC Vers
hnExpiryDate HC Expiry date
language Language (EN or FR)
referralClinician N/A
noteFlag N/A
smoker CPP: Risks - Tobacco: Smoking status (Y/N)
everSmoked CPP: Risks - Tobacco: Differentiates 'never smoked' from 'ex-smoker'
cigsPerDay CPP: Risks - Tobacco: cigarettes per day (either a number or a low-high range)
packYears CPP: Risks - Tobacco: smoking 'pack-years'
drinksPerWeek CPP: Risks - Alcohol - drinks per week (either a number or a low-high range)

PS Suite: Populating PS Suite Custom Form Values with Ocean Answers

Ocean allows PS Suite users to customize their eForms to pre-populate custom forms with answers completed using Ocean. This powerful functionality allows you to use your existing custom forms to record the patient's answers, in addition to the usual progress note added to the chart.

  • One great example involves the standard CDM Diabetes custom form. Ocean has a CDM Diabetes History eForm designed for patients to complete. When the patient completes this eForm, either on the Ocean tablet or via an Ocean online questionnaire, Ocean will automatically add the custom form to the chart. The patient's answers, such as the patient's review of symptoms (e.g. hypoglycemia, pain etc.), automatically populate the corresponding checkboxes on the custom form.
  • Note how the checkboxes in the screenshot have already been prepopulated, since the patient has completed the corresponding Ocean eForm.

Configuring the eForm for Custom Form Prepopulation

  • To configure an Ocean eForm to load any PS Suite custom form, open your Ocean eForm in the eForm Editor.
  • Add an invisible eForm formula item to the end of the eForm.
  • Navigate to the "Scripting and More" tab and change the item reference to: 'pssCF'.
  • Specify the exact, character-for-character name of the custom form in the item's "Formula", surrounded by single quotes (' ').
  • Set "Show this field if" to "false" to make this item invisible (so that this field does not show up on the questionnaire when patients view it).

Configuring the Custom Form Field Mapping

  • To map eForm items to PS Suite custom form items, simply ensure that they are named the same. Any eForm item with an item reference matching an item name on the corresponding PS Suite custom form will be automatically pre-populate the custom form's value.
  • For example, an eForm item text field with reference "BP" will populate the custom form item with name "BP" with the text field value.
  • Custom form checkboxes and radio buttons can be populated with Ocean eForm values as well. An Ocean value of "true" will mark the checkbox (or radio button) as checked.
 

Support Disclaimer

  • Please note that the support and troubleshooting for PS Suite custom form and encounter assistant automation is provided "as is". Beyond clarifying the points in this article, CognisantMD is unable to provide direct support for issues related to this functionality. If you need assistance, CognisantMD might be able to connect you with a third-party developer on an hourly basis (depending on availability).

PS Suite: Advanced Field Mapping

In some cases, you may not have an ideal one-to-one mapping between an eForm question item and a custom form value. In these cases, eForm formula items may provide the flexibility you need. For any custom form item that you'd like to populate, you can create corresponding invisible formula item. The formula can make use of any other eForm value, or even calculate new values.

To map a formula item to a custom form item:

  • Add a new "Formula" type item to the eForm.
  • In the "Note Formatting" tab, set the "Make a note for this item" to "never".
  • Make the formula item's reference the same as the custom form item's name.
  • Set the item's formula to return the value that you'd like to see on the custom form.
  • You likely want the formula item to be invisible, so go to the "Scripting and More" tab and set the formula's "Show this field if" value to "false".
  • You also probably do not want the formula to contribute to the generated note, so go to the "Note Formatting" tab and change the "Create a note for this item" to "never".
  • For example:

    • Suppose you have a question on your eForm, "Are you having any pain?", with the item reference: 'pain'. You also have two checkboxes on a PS Suite custom form to record the answer to this question, one called 'PainYes' for a 'Yes' answer and one called 'PainNo' for a 'No' answer.
    • Since the 'pain' question in your Ocean eForm can only have one item reference, you cannot have it directly populate both of the checkbox values on the PS Suite custom form.
    • However, you can create two new formula items on the eForm to map these values:

      Item Reference Formula
      PainYes
      pain.r == 'Y'
      Copy Formula
      PainNo
      pain.r == 'N'
      Copy Formula
    • Now, if the patient answers 'Yes' to the question on your Ocean eForm, the 'PainYes' formula will evaluate to 'true' and the 'PainNo' formula will evaluate to 'false'.
    • Then, when Ocean populates the PS Suite custom form field, the 'PainYes' checkbox will be set to the value of 'true', which will mark the checkbox checked. The 'PainNo' checkbox will be set to the value of 'false', which will leave it unchecked.

Reminder To Use Single Quotes Around Values

These formula items must use valid JavaScript expressions, so in the event that you would like to set a custom form value to a particular string, you will need to wrap that string in single quotes.

For example, a formula can be set to: 'a value I would like to prepopulate', but NOT simply: a value I would like to prepopulate.

To map a formula item to an encounter assistant item:

Using a similar technique, you can also map eForm answers to Encounter Assistant (EA) fields. Encounter Assistant's are actually just a special type of custom form, so you can use the same "pssCF" formula as above to point to the Encounter Assistant.

Mapping the answers to Encounter Assistant items is slightly more difficult. First, you need to find out the ID of the Encounter Assistant item of interest by opening the Encounter Assistant in the custom form editor (as opposed to the usual custom form editor).

  • Find the ID of the Encounter Assistant item

    • To open the Encounter Assistant in the custom form editor, press and hold Alt (Option) when you click to open the Encounter Assistant in the Edit Custom Forms dialog. You can then see the Encounter Assistant items as they are rendered within the Custom Form.
    • Warning: Do not make any changes in the custom form editor. Any changes you make to the Encounter Assistant in the custom form editor may be overwritten when you make subsequent changes in the Encounter Assistant editor.
    • Click on the box for the Encounter Assistant item to view its ID. It should start with a "#". Your corresponding eForm item ref should be the same, except with "NUM_" replacing the "#".
    • For Example: In an Encounter Assistant with ID "#item1614254" maps to "NUM_item1614254" in the eForm XML.
    • Warning: Make sure you click on the actual checkbox or the cycle box to see the ID, not the label of the Encounter Assistant item. The label ID is different.

PS Suite: Setting Ocean to Automatically Trigger PSS Messages Based on a Patient Responses

A special custom form has been built to trigger a PS Suite message (i.e. yellow sticky note) based on a patient's response in an Ocean eForm (or based on completion of a form). This custom form is called "Ocean - Send Message" and is available in the CognisantMD Resource Library. Follow the steps below to trigger a message, based on an Ocean eForm.

Note: To set this up, you will need to be familiar with a few of the more advanced aspects of the Ocean-PS Suite integration.

  1. Download the "Ocean - Send Message" custom form and open up your Ocean eForm.

    • Download the "Ocean - Send Message" custom form from the Ocean Library and install it in PS Suite, like you would with any other PSS custom form
    • Back in the Ocean Portal, select the form that you would like to use to trigger the PSS message and open it in the eForm editor. You will be adding several formula items to the bottom of this form.
  2. Create a new formula item in your Ocean eForm.

    • To add the first item, select "Add Item" and change the item type to Formula.
    • In the Note Formatting tab, set "Create a Note for this Item" to "never".
  3. Link your Ocean eForm to the "Ocean - Send Message" custom form.

    • Under the Scripting and More tab, add the item reference "pssCF", set "Show this field if" to "false" and enter 'Ocean - Send Message' in the formula field.
    • Note: The text in the formula field MUST be surrounded by single quotes (' ').
  4. Define the target user for your PS Suite message.

    • Repeat step 2 to add a second formula item to set the user that will receive the message.
    • Instead of using the item reference "pssCF", this time use "msgTarget" and enter the PSS user initials into the "Formula" box. In the example to the right, the PSS user initials are CMD (remember to use the single quotes in the "Formula" box).
  5. Define the message body for your PS Suite message.

    • Again, repeat step 2 to add a third formula item to configure the body of the message.
    • This time use the item reference "msgBody" and type your message into the "Formula" box. In the example below, the message shown to the user will be 'Pt. completed the test form'.
  6. Define when the PS Suite message shows up.

    • Repeat step 2 to create a fourth formula item to set the message timing.
    • This time, use the item reference "dueAfterXDays" and type a number in the "Formula" box. In the example to the right, 0 days have been entered, which means that the message will display as soon as the chart is opened.
  7. Define the title for your PS Suite message (optional).

    • You can also repeat step 2 to add an optional 5th formula item in order to give your message a title.
    • This time, use the item reference of "msgTitle". In the example below, the message title is 'Test form alert'.
    • Once you have completed these steps, you should see the PSS message whenever a patient completes the associated Ocean eForm.

Note: The "send message" action is triggered when the patient chart is opened. If a patient is sent a form to complete at home using Ocean Online, there may be a significant delay between the completion of the form and the patient chart being opened (and thus, the PS Suite message being triggered). Clinics may consider implementing a message management workflow that ensures that Ocean alerts are enabled and patient charts are always opened as soon as an alert is received.



PS Suite: Checking for Smoking Status Using an eForm or Tablet Rule

The smoking status is drawn from the "RISKS" field in PS Suite, as text. The content of "RISKS" is available in the keyword "@ptCpp.soc" (if you are curious: "soc" stands for social history).

If you would like to display the smoking status, you can use the "@ptCpp.soc"" keyword in one of the following formulas:

To check if someone is a current smoker:
ScriptUtil.getKeyword("@ptCpp.soc").indexOf("current smoker") >= 0
Copy Formula
To check if someone is an ex-smoker:
ScriptUtil.getKeyword("@ptCpp.soc").indexOf("ex-smoker") >= 0
Copy Formula
To check if someone has never smoked:
ScriptUtil.getKeyword("@ptCpp.soc").indexOf("never smoked") >= 0
Copy Formula

 


PS Suite: Updating the Cumulative Patient Profile (CPP) with Patient Survey Responses

Updating the cumulative patient profile (CPP) is problematic for three reasons:

  1. Patients often provide incorrect information (e.g. spell a drug name wrong, wrong dosage, inaccurate condition diagnosis, etc.).
  2. CPP fields often contain information already, meaning that decisions need to be made about merging updates (e.g. how does a system automatically merge "chf:father" and "F:chf age dx80").
  3. The CPP fields are often treated somewhat canonically by staff, so updates must be reviewed carefully.

As a result, we mostly protect the CPP from patient updates. We recommend colour formatting of answers that indicate a CPP update should be considered (e.g. highlight if a patient's mother had breast cancer, so that a clinician can easily spot necessary CPP updates and apply them if appropriate).

 

That being said, there are some things that you can do in Ocean using the PS Suite CPP:

  • All demographic fields update automatically (e.g. address, phone, email, etc.). You can do this either with the standard demographic review screen or with special "EMRFields" that indicate a custom field should update a demographic field.
  • You can display CPP fields in forms. As an example, try the Medication Reconciliation eForm.
  • You can drive tablet rules off of problem lists.

    For example, here's one to drive the Canadian Lung Health Test for non-diagnosed 40+ year olds COPD once a year:

    !ScriptUtil.getKeyword('@ptHas.copd').equals('Y') && pt.getAge() > 40 && daysSinceLastCompleted >= 365
    Copy Rule
  • You can also automatically update smoking status and drinks per week by tagging eForm items with the corresponding new EMRFields in the eForm editor, For example, if you have a question like "Do you smoke currently?", set the EMRField to "smoker" and it will update the risk factor automatically.
  • You can have the Ocean eForm trigger the automatic insertion of a PS Suite custom form or an EA. The PS Suite custom form can then update the CPP and even send messages. See this article for more information.