6. API Sample Client JavaScript Implementation

For this article you will need to have access to the Sample Client (attached to this article), which is an HTML page that uses JavaScript to implement the API interactions. Please download the zip file attached to this article and unpack this anywhere on your hard drive. Once you have the sample client, save it anywhere on your local machine and double-click on the file. This will load the following page.

  

You can use your browser's developer tools to see the JavaScript code as well as the request and responses for this example. 

 

NOTE: This article does not provide a complete overview of all the possible values of the request and response messages. For more information on that please see 5. Request/Response Structure.

Step 1. Authentication

You will need to set up an integrator account in the LogicNets AUC Portal application. To do this, first sign up for the AUC Portal here.

Follow the instructions in the AUC Portal and set up your user account and organization. In your account setup you will NOT YET see the Integrator option for the Organization Type. LogicNets will enable that option after you contact us. 

 

1. Organization Type:  Select Integrator. NOTE: This option is only available upon request.
2. Contract ID:  This ID is automatically generated when you select Integrator for the organization type. The Contract ID is used for billing purposes, and billing is only active when the API is used in Production mode.
3. API Password:  The system automatically generates the API Password when you select Integrator for the organization type.

The example client makes use of basic authentication. We will use the Contract ID and API password for this. You will need to provide the Contract ID and the API key in the input boxes of the example client.

If you have the correct permissions, you can test by clicking on one of the Start buttons. If the setup is correct you will see the response populated in the Response text area.

 

1. Click either the Start relaxed mode or the Start strict mode button to initiate the call to the AUC Web Service.
2. Review the response in the text area.
3. Click on the ‘switch to’ line to toggle between the raw response view and the card detail view.

 

Troubleshooting Requests

When there is a problem with the authentication, if the request body is malformed, or if there is another issue, the Response field displays the error details.

 

In case of a 403 error, double check your Contract ID and the API key. Verify the organizationId, which must be an existing external ID for Providers and empty for Integrators and Billing organizations. If these items are correct, contact LogicNets for additional assistance.

Tip: Both the Contract ID and API Key fields are stored into the local browser storage. This means that when you reload the page the system retrieves the previously entered values.

Step 2. CDS-Hooks Request Structure

The initial request consists of the following main structure, according to the cds-hooks protocol:

 

The AUC validation request may require multiple round trips, so the client should generate a unique hookInstance ID (see line 11 in the image above: "hookInstance": "61ed65d1-5dda-4398-923e-71064d04748f"). This ID needs to be used for each of the multiple requests during the validation process. You must generate a new hookInstance ID for a new validation.

In the client, we generate the hookInstance ID uuid with the jQuery.fn.uuid function on line 65. In this example, we left the prefetch section empty. You can use this section to specify patient data, which you can map to the decision points in the guidelines. 

Draft Orders ServiceRequest Structure

The entry section specifies the ServiceRequest with the draft order (see lines 8-17 below). It also specifies the reason/indication that needs to be validated by a guideline (see lines 25-41 below).

  

Order

The imaging order is specified in the code section (see lines 8-17 above), and in the example above we used our internal LogicNets code system. You can also use the CPT code system, which would look like this:  

   

Reason/Indication

The reason or indication is specified in the reasonCode section of the ServiceRequest. In the example below you see an example of both ICD-10 and SNOMED. You can use either one to map to the correct guideline.

  

Step 3. Making the Call

When you click one of the Start buttons (1) in the Sample Client, you will see that the Results section shows the returned raw data.

 

The call made to the web service is made in the jQuery.fn.start function. The endpoint must include parameters verb=start and code=auc-hook, and you can also include the mode parameter to access the web service in test mode. Since LogicNets supports rewrite rules, you can also use a friendlier URL: e.g. https://auc.logicnets.net/auc/auc-hook?mode=test.

Note: In test mode, the system will not log validations and you will not accumulate charges. The system will set the pama-rating-consult-id in the response to "test" and this response cannot be used for validation purposes.

If you click the start button in "relaxed mode", the system ignores any recommended order sets, and it returns an appropriate validation result if the suggested order matches one of the recommended orders. If you select the "strict mode" start button, all of the orders in the recommended order set of the guideline need to match the suggested orders set. If there is a partial match, the system will return an incomplete order status and is not appropriate. 

Additionally, you can review 5. Request/Response Structure for more information on the difference between starting the AUC Web Service in relaxed and strict mode using the validation_mode parameter.

Refresh the Launch URL

If you are switching to the cards view/parsed output, there is an entry ‘Refresh launch expiry’. The launch URL has a limited validity time and must be ‘refreshed’ to ensure the call can be made. After you click the refresh link, the system prints the timestamp of that moment next to the link. 

 

Step 4. Processing the Response

In the jQuery.fn.start function the third argument of the POST function processes the data of the response. This is where we copy the raw data into the textarea1 box and iterate through the returned data structure.

The structure of the data is in the form of an array of "cards", also called "app-link-cards". These cards have a complete set of information per guideline that matches the ReasonCode in the request.

 

If you do not provide a ReasonCode the system will iterate through all the guidelines and return app-link-cards for all the guidelines that reference the imaging order.

 

Each card contains the basic cds-hooks elements. The extension element is used to map the additional AUC data in the response.   

 

The system returns the following AUC elements:

• pama-rating
• HCPCSModifier
• PLESpecification
• Specification
• Icon
• PLELicensor
• ClinicalPriorityArea
• NPI
• ReferringOrganization
• DraftOrder
• pama-rating-qcdsm-consulted
• pama-rating-consult-id
• pama-rating-auc-applied
• Report

In the example, we parsed out the name of the Guideline, the Outcome, URL, and formatted the URL as a clickable link.

 

The pama-rating (or outcome in the screenshot) is insufficient-patient-data, because there was no pathway in the guideline that could validate the order based on the data provided. To complete the validation the user will need to interact with the guideline. You could present a link to the user as we did in this example, but you could also open the guideline directly.

 

SMART Web Messaging

The link to open the iframe makes use of SMART Web Messaging. You can use SMART Web Messaging to create seamless integrations between an EHR and an external SMART app. For more information on SMART Web Messaging see https://build.fhir.org/ig/HL7/smart-web-messaging/.

 

SMART Web Messaging also ensures that opening and managing the data communication between an iframe and the parent window is done in a secure way using a messaging handle construction. The smart_web_messaging_handle must be an unique identifier for your client-session, and the identifier should be unique for all client sessions. Requiring this parameter is part of a defense-in-depth strategy to mitigate some cross-site-scripting (XSS) vulnerabilities. Every message you receive back in the client will return the smart_web_messaging_handle. The client checks the messaging_handle against the handle that was provided initially, and they should match before the system processes the response. Meanwhile, the user can continue to interact with the application in the iframe.

Navigation and Recommendations

 

You can navigate through the guideline by selecting the options on the left side of the screen or by interacting with the graph on the right side of the screen. Ultimately, the guideline displays a list of imaging recommendations that either contain the imaging order that you started with in the request or not. If the list of recommendations contains the imaging order the system will generate an outcome of appropriate. If the list of recommendations does not contain an imaging order the system will generate an outcome of not-appropriate.

In our example, you see that the reason Hip Pain the CT hip w/ contrast (MARS) is in the list of imaging recommendations. It is not the primary but the alternative recommendation. At this point, you can select the Confirm draft order button, which will trigger a SMART Web Messaging message. This is handled in the receiveMessage function.

This function handles the following scenarios:

• ui.done => when the VGN session is finished; the payload contains the result message (save or cancel)
• scratchpad.create / scratchpad.delete / scratchpad.update => sent when different orders are selected in the VGN; the payload contains the new, updated order or order that must be deleted.

Note that we are using the same HookInstance ID that we generated at the beginning. When we call the web service again during the "done" scenario it will use the answers the user gave during the interactive session to evaluate the reason and the order. The system can now complete the validation and, since the order was part of the recommended orders, the outcome now is appropriate.

The response object contains the applink card again, which now includes all of the relevant information for completing the validation. The following image is an example of how the result information appears in the AUC web portal: