mPageService

The mPageService is responsible for all communications with CCL and is required by all of the Data Service components included in Clinical Office.

For many applications you will likely have no direct interaction with the mPageService other than initialization. The majority of MPages will be developed using our built in data services or your own custom data services.

Import

The mPageService should be imported and initialized in the app.component.ts script.

V4+ import { mPageService } from '@clinicaloffice/clinical-office-mpage-core';
< V3 import { mPageService } from '@clinicaloffice/clinical-office-mpage';

Initialization

Initialization should be performed in the app.component.ts script. You must pass the MPage service into your constructor. We recommend initializing your MPage service in the ngOnInit method.

constructor(public mpage: mPageService) { }

ngOnInit() {
    this.mpage.setMaxInstances(2, true, 'CHART');
}

Methods

activeTaskCount(): number
Returns the number of tasks currently running plus the number of tasks queued.

assignFromConfigFile(): void V4+
If called, assigns the contextRoot value and domain list from your assets/config.json file. See the ConfigService V4+ documentation for more details.

emptyPatientSource(Get method, no params): IPatientSource
Returns a patient source value of { personId: 0, encntrId: 0 } which is useful when working with the current patient context without needing to generate the entire patient source string.

enableServiceAutoLoad(enable: boolean) Set method, no return
When set to false, auto-loading inside "get()" methods of data services is suspended. If not used or true set, auto-loading is enabled by default.

executeCCL(payload: any, instance: number = 0, callback: any = undefined):void
The executeCCL method is the primary method called by data services to execute CCL scripts. The payload parameter needs to contain a properly formatted JavaScript object with instructions on what data is to be collected by CCL. The instance parameter is used to specify the CCL instance you wish to run. If you pass a value of 0 to the instance parameter the next available instance will be used.

The optional callback parameter allows assigning a method to be executed once your executeCCL script has been completed.

Examples:

Example 1:
----------
this.mpage.executeCCL(payload, 0, () => { this.mpage.putLog('I will run as soon as data comes back'); });

Example 2:
----------
this.mpage.executeCCL(payload, 0, () => { this.runAfterExecute() });

public runAfterExecute(): void {
    this.mpage.putLog('The runAfterExecuteMethod is called as soon as data comes back.');
}

Please read the information in the payload tab for proper payload formatting.

putLog(message: string): void
Outputs the content of the message parameter to the activity log component.

contextRoot(value: string) Set method, no return
Used to assign the location of the Discern Web Services.

setLogStatus(enableLog: boolean): void
setLogStatus can be used after mPageService initialization to enable/disable CCL logging.

setMaxInstances(maxInstances: number, enableLog: boolean = false, mode: string = 'CHART'): void

Initializes the MPage service. Can only be run once during application lifetime and is responsible for setting up the number of CCL instances that can be called as well as enabling the CCL log and MPage mode.

The maxInstances parameter will always default a minimum of 2 instances regardless of whether you choose a lower value. It is recommended for most MPages that you run a maxInstances value between 2 and 6 (4 is recommended).

Setting enableLog to true will allow the recording of events being passed back and forth from CCL. You can view the log in your MPage by including the mpage-log-component tag in your html.

The mode parameter is used to indicate if your MPage is running at the CHART or ORGANIZATION level. If you choose CHART, the PERSON_ID and ENCNTR_ID of the current patient will be passed to CCL. Selecting ORGANIZATION will result in the value 0 being passed to CCL for PERSON_ID and ENCNTR_ID.

Interfaces

A number of interfaces are also exposed in the mPageService that are primarily used internally by the mPageService itself. Some of these interfaces have no value outside of the mPageService, however the PatientSource service is used throughout all of the data services as a way of identifying which patients/visits should be used.

export interface IPatientSource {
  personId: number;
  encntrId: number;
}

Public Variables

A number of variables exist in the mPageService that can be useful in the development of your MPages. They are as follows:

• defaultPayload: Map<string, any> - Map containing default payload values. See PAYLOAD tab on this page.
• domain: string V4+ - The current domain name (e.g. B1234)
• encntrId: number - The encntrId of the current visit (chart mode only).
• inMpage: boolean - True if you are running your application from an MPage.
• nameFullFormatted: string - The full formatted name of the current patient when run in CHART mode.
• personId: number - The personId of the current patient (chart mode only).
• physicianInd: boolean - Indicates if the current user is a physician.
• position: string V4+ - The textual display of the position of the person viewing the MPage.
• positionCd: number V4+ - The code value representing the position of the person viewing the MPage.
• prsnlId: number - The personId of the current person viewing the MPage.
• prsnlName: string - The full formatted name of the current person viewing the MPage.
• serviceReady: boolean - Indicates if the initial call to the MPage service has completed.

Payload

The payload executed by the executeCCL method of the mPageService is read by CCL to determine which patients/encounters are to be used as well as which CCL scripts are to be executed.

The minimum requirements for your payload object is to have a root object called payload. While it won't actually do anything, the following is a completely valid payload to be sent to CCL.

{
  payload: { }
}

Choosing Patients/Visits

If you do not include a patientSource in your payload and are running in CHART mode, a default patientSource will be generated for the current encounter.

You can however specify one or more patients and/or visits in your payload with the patientSource element. You can use a combination of personId and/or encntrId values. If you specify an encntrId but leave personId set to 0 and call a CCL script that requires personId, it will automatically be calculated for you. Providing a personId with no matching encntrId will not default encntrId's for your CCL as the volume of encounters could be very high.

{
  payload: {
    patientSource: [
      {personId: 123456, encntrId: 0},
      {personId: 0, encntrId: 789012},
      {personId: 234567, encntrId: 911233};
    ]
  }
}

Executing CCL Scripts

Each CCL script developed for Clinical Office:MPage Edition has a unique payload tag. For example, the PersonService uses a payload tag called "person". The documentation for each data service includes a tab indicating all of the payload tags used by that service. Each data service offers a method for calling the correct payload.

Sometimes however, you may wish to call the executeCCL script manually with your own payload. This is possible and any data services you have running in your script will automatically reflect any new data loaded through a manual executeCCL call. It is also possible to call many CCL scripts at the same time through the same CCL instance. For example, you may have a custom CCL being called which collects a list of qualifying visits. Instead of writing the CCL code to pull patient demographic or encounter specific data, you can simply chain the payload values together.

In the example below, a custom script called 1_cancer_patients is called followed by the code to collect the person records and encounter records. The custom script only needs to populate the a record structure in CCL called PATIENT_SOURCE with the ENCNTR_ID's of the patients qualified. No other information is needed in the CCL to retrieve everything needed for the MPage.

{
  payload: {
    customScript: {
      script: [{name: '1_cancer_patients', run: 'pre', id: 'cancerpat', parameters: {} }] ,
      clearPatientSource: true
    },
    person: {
      patient: true,
      prsnlReltn: true
    }
    encounter: {
      aliases: true,
      prsnlReltn: true
    }
  }
}

Default Payload Tags

Each data service offers default payload values that you can override in your app.component.ts script after setting your mPageService max instances. Each default payload tag is documented with the service it is used in.

For example, the PersonService offers three default payload objects that you can easily override. The defaults are called "PERSON_MIN", "PERSON_PATIENT" and "PERSON_PRSNL". They are stored in a Map contained in the MPage service.

The "PERSON_MIN" payload tag simply indicates that along with the data from the PERSON table, it is only going to collect the PERSON_ALIAS values. During the design of your MPage, you may also want to always return code values every time "PERSON_MIN" is executed in the PersonService. You would change it by adding the following line to your app.component.ts script in the ngOnInit() method right after your call to the setMaxInstances method.

this.mpage.defaultPayload.set('PERSON_MIN',
  person: {
    includeCodeValues: true,
    aliases: true
  }
);

Default payloads can also be used in your custom payloads. In our Cancer patients example shown above we have now decided to load as much information about the patient as we can. To do this, we are going to use the "PERSON_PATIENT" payload which includes code values, aliases, person patient, names, person info, personnel relationships, person relationships and organization relationships.

We could have typed all the parameters for these person service items into our payload, but instead we chose to simplify by using the "PERSON_PATIENT" default payload. To do this, we use the Object.assign function to merge our payload contents with the content of the "PERSON_PATIENT" payload.

{
  payload: Object.assign({
    customScript: {
      script: [{name: '1_cancer_patients', run: 'pre', id: 'cancerpat', parameters:{}}] ,
      clearPatientSource: true
    },
    encounter: {
        aliases: true,
        prsnlReltn: true
    }},
    this.mpage.defaultPayload.get('PERSON_PATIENT')
    )
}

Controlling Data Collection with typeList

Data collection is quick and easy however it may not always be the most efficient. For example, you may want to collect the personAlias value for MRN and CMRN but nothing else. You can filter many data items down by type if you add typeList to your payload.

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

Each payload can have one typeList definition however it can contain typeList filters for multiple code sets. For example, if your payload was also retrieving the person names data and you only wanted to pull MAIDEN name, you could add code set 213 with a type of "MAIDEN" to filter the names.

The type field can either contain the CDF_MEANING or DISPLAY_KEY value of the code set being filtered. If you prefer, you can also directly enter the CODE_VALUE itself and leave the "type" field set to a value of "". We discourage putting code values directly into your code however you may have looked up a code value earlier in your code and may wish to use the value here instead of the textual name.

The available list of code sets allowed for each data service is listed in the service specific documentation.