Encounter Service

Overview

The EncounterService is responsible for retrieving encounter related data from Cerner.

To use this service, you must import the service, assign it to an object, execute a data collection operation (either with the load method on this or any other MPage Developer service, or with the MPage Service executeCCL method). Finally, you need to do something with the data you have retrieved.

Import

import {Component, inject, OnInit, ...etc...} from '@angular/core';
import {EncounterService} from '@clinicaloffice/mpage-developer';

Object Assignment

Using the Angular inject command, assign the EncounterService to a new object. It is recommended that you scope your object as "protected" to allow access to your component HTML.

@Component({...
...})
export class YourComponent implements OnInit {
    protected encounterService = inject(EncounterService);
    ....remaining code...

Data Collection

The examples below demonstrate data collection methods you can use.

// Load the encounter for the current encounter with a default payload of "ENCOUNTER_MIN"
this.encounterService.load();

// Use the MPage Service to load multiple payload items
this.MPageService.executeCCL({
    payload: {
        patientSource: [{personId: 0, encntrId: 0}],
        person: true,
        encounter: {
            aliases: true
        }
});

Payload Options

The encounter service offers several payload options described in the following table.

Default Payload Tags that Reference the Personnel Service

{
    encounter: {
        aliases: true
    }
}

{
    encounter: {
        aliases: true,
        encounterInfo: true,
        encounterPlanReltn: true,
        personReltn: true,
        prsnlReltn: true,
        locHist: true
    }
}

{
    encounter: {
        aliases: true,
        encounterInfo: true,
        encounterPlanReltn: true,
        personReltn: true,
        prsnlReltn: true,
        locHist: true
    },
    person: {
        aliases: true,
        patient: true,
        names: true,
        personInfo: true,
        prsnlReltn: true,
        personReltn: true,
        personPlanReltn: true,
        orgReltn: true,
        personCodeReltn: true,
        loadExtendedPersons: true
    },
    prsnl: {
        aliases: true
    }
}

Using Callbacks

Both the service load method and MPageService executeCCL methods offer a callback parameter as the final parameter. You can use this callback or another option of your choosing to work with the data returned from Cerner.

this.MPageService.executeCCL({
    payload: {
        ...
    }
}, () => { ...do something here... }

Accessing from HTML

The encounters(), get(), getAlias(), getEncntrInfo(), getPersonReltn(), getPrsnlReltn(), and getLocationHistory() methods in the encounter service can be accessed directly from HTML. The encounters() method will return all loaded encounter information for all encounters where the various get() methods return data for a specific encounter id.

@let visit = encounterService.get();
<h2>{{ visit?.locFacility }}</h2>
<p>Room: {{ visit?.locRoom }}, Bed: {{ visit?.locBed }}</p>

Methods / Usable Objects

Reference to the encounter service Map containing all loaded encounter data.

Returns the record for a specific encntrId if loaded or undefined if not loaded.

If it exists, the getAlias method returns a specific encounter alias value where the aliasType or aliasTypeMeaning value matches the incoming aliasType string.

If it exists, the getEncntrInfo method returns a specific encounter info value where the infoType, infoTypeMeaning, infoSubType, or infoSubTypeMeaning value matches the incoming nameType string. Additional filtering is used for determining the internal sequence and priority sequence. If 1 is passed to either value, a 0 or 1 will qualify where ENCNTR_INFO records with sequences greater than one must be identified in the search.

Returns a specific location history record for an encounter at a specific date/time if it exists.

If it exists, the getPersonReltn method returns a specific person relation value where the personReltnType or personReltnTypeMeaning value matches the incoming reltnType string. If provided in the call, additional filtering is used for determining the internal sequence and priority sequence.

Returns all health plans associated with a encntrId.

Returns a specific health plan associated with a encntrId and priority sequence.

If it exists, the getPrsnlReltn method returns a specific prsnl relation value where the reltnType or reltnTypeMeaning value matches the incoming reltnType string.

Indicates if a specific encntrId has been loaded.

Returns a count containing the number of encounter values loaded in memory.

Loads encounter information for encounters identified in the patientSource array. The payload can be any valid payload string or default payload (see payload tab).

The loadList method is used to execute a custom CCL script designed to load multiple encounters. This CCL script can be one of the ones provided with Clinical Office or it can be a script of your own.

Write a line of text to the MPage Developer log. Valid values for type include 'info', 'error', 'payload', and 'debug'. You should only use the values 'info' or 'error' as 'payload' and 'debug' are reserved for system use. The processId and statusText values can safely be ignored.

Returns an iterable iterator representation of all loaded encounter values.

loadList Method

The EncounterService loadList method has been designed to offer the MPage developer a simple way of loading multiple encounters regardless of if the encounters being loaded are associated to the current patient being viewed in PowerChart.

The goal is to allow the developer complete flexibility in loading encounters while at the same time offering a solution that is simple to implement.

Required Parameters

• script: string

  Represents the name of the CCL script responsible for collecting encounters. The script name should be fully qualified with the group it was compiled with. It is recommended that all scripts be compiled as group1. (e.g. "1co5_mpage_enc_list:group1")

• parameters: any

  A required JavaScript object that is unique to each CCL script. Please see the specific documenation for each script further down on this page.

• clearPatientSource: boolean

  A boolean value indicating whether the patientSource record structure should be cleared before executing the CCL script. The documentation shown below for each CCL script will indicate if the clearPatientSource will be used to restrict data collection to only personId records loaded in the patientSource object.

  clearPatientSource limits results to personId values in patientSource if false. If set to true, only the date field type and date range along with any typeList values will be used for filtering.

Optional Parameters with Defaults

• customId: string = ''

  Represents a unique identification field used by the CustomService data service. If this field is populated with a value other than '' and you have an instance of CustomService running on the same page as the EncounterService, the CustomService Map will be loaded with data from the CCL script.

• typeList: ITypeList = [{codeSet: 0, type: '', typeCd: 0}]

  Contains an array of TypeList code values. The typeList parameter allows you the ability to pass additional TypeList values to the loadList method. These TypeList values will be appended to any typeList entries found in the payload being passed to the loadList method. A list of available typeList values are shown in the documentation for each CCL script discussed below.

• payload: any = 'ENCOUNTER_LIST_MIN'

  The payload field will accept any default payload tag name or a fully qualified JavaScript payload object. For information on formulating your own payload object, please see the mPageService documentation.

  Please take note that the loadList method will create the appropriate "customScript" payload variable and append it to any payload being passed in the payload parameter.

  The structure of the ENCOUNTER_LIST_MIN payload tag is:

  {
    payload: {
      encounter: {aliases: true},
      person: {aliases: true},
      typeList: [{codeSet: 4, type: 'MRN', typeCd: 0}]
    }
  }

  If you wish to have the person data loaded into your MPage, you must also have the PersonService data service instantiated on your MPage.

• patientSource: IPatientSource = [{personId: 0, encntrId: 0}]

  The patientSource parameter defaults the current patient if the MPage is running from the chart level. If being run from the organizer level, no patient data is passed in the default. You can send multiple personId/encntrId object pairs in your patientSource.

  Depending on the CCL script being executed, the patientSource may be erased if the the clearPatientSource parameter has been set to true.

Results

The following patientSource object is returned to the CustomService object if customId has been populated in the optional parameters.

{
    visits: [{ personId: value, encntrId: value}]
}

Available CCL Scripts

Parameters (Required unless specified below)

{
    dateField: 'name of encounter date field (e.g. REG_DT_TM)',
    fromDate: Date,
    toDate: Date,
    organizations: [ {orgName: 'name of organization'} ]  (Optional)
}

Available typeList filtering value types

[
    {codeSet: 19, type: 'EXPIRED', typeCd: 0},    // Discharge Disposition
    {codeSet: 69, type: 'INPATIENT', typeCd: 0},  // Encounter Type Class
    {codeSet: 71, type: 'INPATIENT', typeCd: 0},  // Encounter Type
    {codeSet: 34, type: 'CARDIOLOGY', typeCd: 0}, // Medical Service
    {codeSet: 220, type: 'SOUTH-1', typeCd: 0}    // Nurse Unit
]

Available typeList filtering value types

[
    {codeSet: 69, type: 'INPATIENT', typeCd: 0},  // Encounter Type Class
    {codeSet: 220, type: 'SOUTH-1', typeCd: 0}    // Nurse Unit
]

typeList Filtering

You can limit the amount of data collected in CCL by optionally adding a typeList object to your payload. For example, if you only wanted to load "FIN NBR" aliases for visits, and you never plan on using the other types, simply add a typeList entry for code set 319 to your payload. In addition to code set 319, you can also set a typeList filter for code set 351 to filter person relationship types.

Include the codeSet value, type or typeCd where type represents a cdf_meaning or display_key value, and typeCd represents the actual code value you want to filter by.

{
    payload: {
        patientSource: [{personId: 0, encntrId: 0}],
        encounter: {
            aliases: true,
            personReltn: true
        }
        typeList: [
            {codeSet: 319, type: 'FIN NBR', typeCd: 0},
            {codeSet: 351, type: 'GUARDIAN', typeCd: 0}
        ]
    }
}

Interfaces

IEncounter {
  encntrId: number;
  personId: number;
  encntrClass: string;
  encntrType: string;
  encntrTypeClass: string;
  encntrStatus: string;
  preRegDtTm: Date;
  preRegPrsnlId: number;
  regDtTm: Date;
  regPrsnlId: number;
  estArriveDtTm: Date;
  estDepartDtTm: Date;
  arriveDtTm: Date;
  departDtTm: Date;
  admitType: string;
  admitSrc: string;
  admitMode: string;
  dischDisposition: string;
  dischToLoctn: string;
  readmit: string;
  accommodation: string;
  accommodationRequest: string;
  ambulatoryCond: string;
  courtesy: string;
  isolation: string;
  medService: string;
  confidLevel: string;
  vip: string;
  location: string;
  locFacility: string;
  locBuilding: string;
  locNurseUnit: string;
  locRoom: string;
  locBed: string;
  dischDtTm: Date;
  organizationId: number;
  reasonForVisit: string;
  encntrFinancialId: number;
  financialClass: string;
  trauma: string;
  triage: string;
  triageDtTm: Date;
  visitorStatus: string;
  inpatientAdmitDtTm: Date;
  encntrClassCd: number;
  encntrTypeCd: number;
  encntrTypeClassCd: number;
  encntrStatusCd: number;
  admitTypeCd: number;
  admitSrcCd: number;
  admitModeCd: number;
  dischDispositionCd: number;
  dischToLoctnCd: number;
  readmitCd: number;
  accommodationCd: number;
  accommodationRequestCd: number;
  ambulatoryCondCd: number;
  courtesyCd: number;
  isolationCd: number;
  medServiceCd: number;
  confidLevelCd: number;
  vipCd: number;
  locationCd: number;
  locationOrgId: number;
  locFacilityCd: number;
  locBuildingCd: number;
  locNurseUnitCd: number;
  locRoomCd: number;
  locBedCd: number;
  financialClassCd: number;
  traumaCd: number;
  triageCd: number;
  visitorStatusCd: number;
  aliases: IEncntrAlias[];
  personReltn: IEncntrPersonReltn[];
  prsnlReltn: IEncntrPrsnlReltn[];
  encntrInfo: IEncntrInfo[];
  encntrPlanReltn: IEncntrPlanReltn[],
  locHist: IEncntrLocHist[];
}

IEncntrPersonReltn {
  relatedPersonId: number;
  nameFullFormatted: string;
  personReltnType: string;
  personReltnTypeMeaning: string;
  personReltnTypeCd: number;
  personReltn: string;
  personReltnCd: number;
  relatedPersonReltn: string;
  relatedPersonReltnCd: number;
  contactRole: string;
  contactRoleCd: number;
  geneticRelationshipInd: number;
  livingWithInd: number;
  visitationAllowed: string;
  visitationAllowedCd: number;
  familyReltnSubType: string;
  familyReltnSubTypeCd: number;
  defaultReltnInd: number;
  copyCorrespondence: string;
  copyCorrespondenceCd: number;
  prioritySeq: number;
  internalSeq: number;
  relationSeq: number;
}

IEncntrPlanReltn {
  encntrPlanReltnId: number,
  personPlanReltnId: number,
  personId: number,
  healthPlanId: number,
  organizationId: number,
  prioritySeq: number,
  memberNbr: string,
  signatureOnFile: string,
  signatureOnFileCd: number,
  balanceType: string,
  balanceTypeCd: number,
  deductAmt: number,
  deductMetAmt: number,
  deductMetDtTm: Date,
  verifyStatus: string,
  verifyStatusCd: number,
  verifyDtTm: Date,
  verifyPrsnlId: number,
  insuredCardName: string,
  groupName: string,
  groupNbr: string,
  policyNbr: string,
  memberPersonCode: string,
  lifeRsvDays: number,
  lifeRsvRemainDays: number,
  lifeRsvDailyDedAmt: number,
  lifeRsvDailyDedQual: string,
  lifeRsvDailyDedQualCd: number,
  cardIssueNbr: number,
  cardCategory: string,
  cardCategoryCd: number,
  programStatus: string,
  programStatusCd: number,
  denialReason: string,
  denialReasonCd: number,
  coverageComments: string,
  verifySource: string,
  verifySourceCd: number,
  extPayerName: string,
  extPayerIdent: string,
  altMemberNbr: string,
  genericHealthPlanName: string,
  planType: string,
  planTypeCd: number,
  planClass: string,
  planClassCd: number,
  planName: string,
  planDesc: string,
  financialClass: string,
  financialClassCd: number,
  babyCoverage: string,
  babyCoverageCd: number,
  combBabyBill: string,
  combBabyBillCd: number,
  serviceType: string,
  serviceTypeCd: number,
  planCategory: string,
  planCategoryCd: number,
  priorityRankingNbr: number
}

IEncntrAlias {
  aliasPool: string;
  aliasType: string;
  aliasTypeMeaning: string;
  alias: string;
  aliasFormatted: string;
  aliasSubType: string;
  aliasPoolCd: number;
  encntrAliasTypeCd: number;
  encntrAliasSubTypeCd: number;
}

IEncntrPrsnlReltn {
  reltnType: string;
  reltnTypeMeaning: string;
  personId: number;
  prioritySeq: number;
  internalSeq: number;
  prsnlType: string;
  nameFullFormatted: string;
  physicianInd: number;
  position: string;
  nameLast: string;
  nameFirst: string;
  userName: string;
  encntrPrsnlRCd: number;
  prsnlTypeCd: number;
  positionCd: number;
}

IEncntrInfo {
  infoType: string;
  infoTypeMeaning: string;
  infoSubType: string;
  infoSubTypeMeaning: string;
  valueNumericInd: number;
  valueNumeric: number;
  valueDtTm: Date;
  chartableInd: number;
  prioritySeq: number;
  internalSeq: number;
  value: string;
  longText: string;
  infoTypeCd: number;
  infoSubTypeCd: number;
  valueCd: number;
}

IEncntrLocHist {
  begEffectiveDtTm: Date;
  endEffectiveDtTm: Date;
  arriveDtTm: Date;
  arrivePrsnlId: number;
  departDtTm: Date;
  departPrsnlId: number;
  location: string;
  locFacility: string;
  locBuilding: string;
  locNurseUnit: string;
  locRoom: string;
  locBed: string;
  encntrType: string;
  medService: string;
  transactionDtTm: Date;
  activityDtTm: Date;
  accommodation: string;
  accommodationRequest: string;
  admitType: string;
  isolation: string;
  organizationId: number;
  encntrTypeClass: string;
  locationCd: number;
  locationOrgId: number;
  locFacilityCd: number;
  locBuildingCd: number;
  locNurseUnitCd: number;
  locRoomCd: number;
  locBedCd: number;
  encntrTypeCd: number;
  medServiceCd: number;
  accommodationCd: number;
  accommodationRequestCd: number;
  admitTypeCd: number;
  isolationCd: number;
  encntrTypeClassCd: number;
}