Contact Title and Encounter Note Function in Forms

Background
ENC_NOTE_ADD Code Logic
How to implement

Background

It's common for complex forms to have a requirement to add a Contact Title and/or write to the Encounter Notes. These instructions leverage the macro ENC_NOTE_ADD which can be called by forms. There is reference text on within the macro's header comment but this Zendesk will provide more detailed instructions.

Note: this strategy does not work well with parkable forms. This will instead write the note in the encounter that the form was originally created in. Instead, see forms like 4. Clinical Documents\Intake Form for example of code that can write to the active encounter.

ENC_NOTE_ADD Code Logic

The ENC_NOTE_ADD macro provides a standard method to handle encounter notes/contact titles for forms. If a complex form needs to deviate from this, copy the code from the macro and use it as a base in an embedded macro function within the form. Do not update ENC_CODE_ADD macro unless the purpose is to change the behaviour in ALL complex forms using the macro. Below is the high-level logic of the ENC_CODE_ADD macro

1. Confirm that the form is associated to an encounter
2. If detects the form should have an associated Contact Title:
   1. Confirm that the contact title does not already exist in the encounter
   2. If a contact title matches one already present, no further action needed
   3. If a contact title does not match do the following:
      1. If an undefined contact is available, update this contact to have the desired title (diagnosis code or free-text code)
      2. If no undefined contacts are found, add a new contact first, then update this one's title
3. If detects if the form should write to the Encounter Note:
   1. If there is an associated contact for this form by title, save the text to this contact
   2. If there is none, check the action links to see if the form is saved to a different contact. If found, save the text to this contact
   3. If neither above is found, add the text to the current contact
      Note: in all cases above, it will append to the existing encounter note. It will NOT overwrite previously written text.
4. Save the Encounter 

How to implement

1. Open the Form Editor for the desired form.
    
2. In the Object Inspector, click on the very topmost node and then navigate to the Events tab. There should be a macro associated to the event OnMValidateSave
   
    
3. Double-click on the macro name to open it up in the Macro Form Editor
    
4. If there is a macro call to "FillEncounterNote", remove this line. Also, delete the embedded macro "FillEncounterNote". This is a relic of the old way to add Encounter Notes/Contact Title.
   

5. At the top of the macro if it does not currently exist, add the following:

   Form.Vars("ENC_TITLE_TYPE") = ""
   Form.Vars("ENC_TITLE_TEXT") = ""
   Form.Vars("ENC_NOTE_CONTENT") = ""
   Profile.CallMacro "ENC_NOTE_ADD"

6. For each form variable, update the following based on the needs of the form:
   • To add/update Contact Title:
     • Set ENC_TITLE_TYPE to "CODE" if the form should use a diagnosis code for its Contact Title, or "DESC" if free-text should be used for the Contact Title.
     • Set ENC_TITLE_TEXT to the value needed for the code or the ad hoc text
   • To add/update the Encounter Notes, assign ENC_NOTE_CONTENT the final value it should display, including any formatting. 
     
     Below are two examples where one's goals are to ensure there is a Contact Title using free-text and add/append the specified Encounter Note text, and the other's goal is to only add an Encounter Note; It does not touch Contact Title(s).
     
     Code 1 sample:
     
     Encounter once form is saved 1 sample:
     
     
     Code 2 sample:
     
     Encounter once form is saved 2 sample:
     
      
7. Save the macro and form. Test to ensure it works as expected.