iDocuMint

Overview

  • iDocuMint is a browser-based HTML control user interface to access the ICD Search (Sherpa) API to search for terms and concepts for a condition, illness, injury, disease or complaint.
  • iDocuMint can be embedded into your browser-based application using <embed> or iFrame HTML code.

Embedding iDocuMint into your application 

Embedding iDocuMint into your application 

The following example demonstrates how-to embed iDocuMint using iFrame. 

JSON Results (will populate after selecting code(s) and clicking "Save"):

Input your credentials for a full working example of iDocuMint.

  1. Click to begin a search for:
     
  2. Use iDocuMint to select a code or codes, then click the "Save" button
  3. The selected code(s) will populate the JSON results below. This is an example of how selected codes can be integrated into your application.
(Initiate the app, search, and save to see the result returned here.)

NOTE:  This iDocuMint example is best viewed on a monitor with display settings configured with a minimum resolution of 1280 x 960.

How-to : Embed iDocMint into your application:

  1. Copy the code sample in "Putting it all Together" into your browser-based application. Only the code commented as "required" is necessary, the rest is for the purposes of this demonstration.
  2. Optional: update the links to begin searching and the populateSavedCodes() javascript method to parse the JSON results into your application.
  3. Registered VitalWare users: Update the authentication credentials to your Mashery API key and VitalWare user credentials. For more details see the Authentication documentation or Contact Support if you are having issues with your credentials.
  4. Internet Explorer (IE) Users: see VitalWare recommendations for IE options. This example may not work if the recommendations are not followed.
  5. Launch the page in your application.

Troubleshooting

Minimum Display Resolution 

The minimum display settings for iDocuMint is 780 x 700 pixels. You may need to set these dimensions on your page or iDocuMint may not load correctly.

Endpoint

version endpoint details
1 https://mashery.vitalware.com/ctl/v2/idocumint.widget.js  initial release
2 https://mashery.vitalware.com/ctl/v2/idocumint.widget.v2.js 

Updated logout process on closing the iFrame .

Application Options

iDocuMint supports the following application options. To use the default parameter value, simply exclude the parameter from the options object.

Parameter Data type Description
autoload Boolean true: automatically initializes iDocuMint (default) false: the load() method on the iDocuMint object must be called explicitly by the host page to load iDocuMint
codeSet String The ICD code set to perform the search on. Valid values:
  • “ICD10CM” (default)
  • “ICD10PCS”

viewableCodeSets

String

Optional comma-delimited list of the code sets that you want users to be able to search in the UI. If this parameter is included, only the values passed will be visible for searching. Otherwise, all code sets will be visible by default. Valid values:

  • “ICD10CM”
  • “ICD10PCS”
searchText String

Optional search value to load into search in iDocuMint. iDocuMint will load without any search specified if this parameter is blank or NULL is passed.

Examples:

  • “Gout”
  • “Distal Radius Fracture”
container String The ID of the DOM element the iDocuMint iFrame will be created in.Note: “iDocuMintWidget” is used for all of the script samples in this document
callbackOnSave String Optional name of a local JavaScript method you create in your page to handle the “save” event in iDocuMint. See documentation below for implementation instructions.Example: “onSaveEventHandler”
resultFormat String Format the “save” result object should be returned in. Valid Values:
  • “JSON”
  • “CSV”
assetPrefix String URL prefix for a custom (non-default) implementation of iDocuMint. Do not modify unless instructed by VitalWare.
servicePrefix String URL prefix for a custom (non-default) implementation of iDocuMint. Do not modify unless instructed by VitalWare.
serviceParams String URL parameters to modify the default behavior of iDocuMint. Parameters must be passed as valid URL strings. Separate each parameter with an amperstand (“&”). Valid Values:
  • showContactSupport
    • “1”: show Contact Support button (default)
    • “0”: hide Contact Support button
  • disableHistory
    • “1”: back-button history in iDocuMint is DISABLED, and the iDocuMint URL will remain static
    • “0”: back-button history in iDocuMint is ENABLED, causing the URL to change on many click actions in iDocuMint (default)
  • patientAge
    • float: age of the patient in years. Use float for partial years.
  • patientGender
    • “m”: Male
    • “f”: Female
  • patientMaternity
    • “1”: Patient is definitely pregnant, or the code is related to pregnancy
    • “0”: Patient is definitely not pregnant, or the code is not related to pregnancy
  • ui
    • “desktop”: Force the desktop version of iDocuMint. This is helpful for tablets or other small devices that may default to the mobile display, but would work better in the desktop mode in your application.
  • preserveSave
    • “1”: Use this parameter if your users will manually copy/paste the selected codes into your application.
    • “0”: Default. The Save button will submit a JSON object to your application with the selected codes.
Example: “showContactSupport=0&disableHistory=1”
vwToken String Authentication token generated from API login. This token must be provided if API authentication is being used.

HTML Sample Script with options Included

<!DOCTYPE html>
<html dir=”ltr” lang=”en-US”>
    <head>
        <title>iDocuMint Embedded Demo</title>
    </head>

    <body>
        <div id="iDocuMintWidget" style=""></div>

        <script src="https://mashery.vitalware.com/ctl/v2/idocumint.widget.js?api_key={apiKey}&vwToken={vwToken}" type="text/javascript" ></script>

        <script type="text/javascript" >
            var options = {
                autoLoad: true, //Optional
                codeSet: 'icd10cm', //Optional
                searchText: 'gout',//Optional
                container: 'iDocuMintWidget', //Optional
                callbackOnSave: 'downloadCsvFromJSON', //Optional
                resultFormat: 'json', //Optional
                assetPrefix: 'https://secure.vitalware.com/iDocuMint/', //Optionalbeing called
                servicePrefix: 'https:// secure.vitalware.com/iDocuMint/', //Optional
                serviceParams: ‘showContactSupport=0&disableHistory=1’, //Optional
                vwToken: ‘{apiToken}’//Optional, replace with vwToken received during API authentication
            };

            var idmWidget = new iDocuMintWidget(options)
        </script>
    </body>
</html>

iDocuMint Method

iDocuMint currently supports the following method.

Method

Description

load( searchText, codeSet )           

Begins a new search in iDocuMint with search text and ICD-10 code set specified.   Saved conditions or procedures are preserved when the search begins.

Call load () with an empty string to clear the current iDocuMint search without loading a new search term.

Parameters:

  • searchText (string): The text to search. (example: “gout”, ”heart failure” .  Passing an empty string will leave the search field blank. 
  • codeSet (string): ICD-10 code set to search.
  • ICD-10 CM Diagnosis codes (value: “ICD10CM) 
  • ICD-10 PCS Codes (value: “ICD10PCS”)

Example iDocuMint Calls

The following examples assume that idmWidget is the iDocuMint object in your application.

<a href=”#” onClick=”idmWidget.load(‘gout’,’ICD10CM’)”>Gout search in ICD-10 CM</a>
<a href=”#” onClick=”idmWidget.load(‘bypass artery,’ICD10PCS’)”>Artery Bypass search in ICD-10 PCS</a>
<a href=”#” onClick=”idmWidget.load()”>Clear iDocuMint Search</a>

iDocuMint Events

Event Objects

All iDocuMint events return a JSON object with the following properties:

Property

Data type

Description

event

String

String name corresponding to the event that was triggered. See the list above for supported events.

Examples “save”

message

String

String message describing the event

data

Object

Object containing data specific to an event. Data objects will be JSON unless otherwise specified. See below for data objects for each event type.

Sample Event Object

{
    "event": "save",
    "message": "Save Complete",
    "data": {
        "selectedCodes": [
            {
                "code": "M10012",
                "codeDesc": "Idiopathic gout, left shoulder",
                "codeSet": "ICD10CM",
                "documentationSherpas": "gout, shoulder, left"
            },
            {
                "code": "E0821",
                "codeDesc":
                "Diabetes mellitus due to underlying condition with diabetic nephropathy",
                "codeSet": "ICD10CM",
                "documentationSherpas": "Diabetes, Mellitus"
            }
        ]
    },
}

Event Handling

To handle events, you must create a callback function to handle the event and specify the function name in the corresponding “options” parameter when initializing the iDocuMint object.

Sample HTML:  Specifying a Callback Method for Save Event

This sample saves a local copy of the CSV results when the user clicks the “Save” button in iDocuMint

<div id="iDocuMintWidget"></div>

<script src="https://mashery.vitalware.com/ctl/v2/idocumint.widget.js?api_key={apiKey}&vwToken={vwToken}" type="text/javascript" ></script>

<script>
    //loads iDocuMint with the selected options defined
    var options = {
        callbackOnSave: 'downloadCsvFromJSON'
    };
    var idmWidget = new iDocuMintWidget( options );

    function downloadCsvFromJSON(resultObj){
        console.log('downloadCsvFromJSON');
        console.log(resultObj);

        var resultData = JSON.parse(resultObj);
        var csv = resultData.data.selectedCodesCsv;
        
        console.log(csv);

        //example to save a local copy of the CSV file
        window.open( "data:text/csv;charset=utf-8," + escape(csv));
    }
</script>

Events Types

iDocuMint API currently broadcasts the following events. 

Event

Description

Save

Trigger:User clicks the “Save” button in iDocuMint

Options callback property:callbackOnSave

Returns an object containing the codes selected by the user in iDocuMint.

iDocuMintInitComplete

Trigger: iDocuMint application completes loading

Alerts the iFrame that iDocuMint is now ready to use. This event is currently only used by the iFrame to initialize application options. It will be propagated to the host page in future releases.

Save Event

The Save event returns a data object consisting of the following data objects:

Object

Properties

selectedCodes

code {string} : the ICD-10 code selected by the user

codeDesc {string}: the code description of the ICD-10 code

codeSet {string}: ICD-10 code set. Currently either “ICD10CM” or “ICD10PCS”

documentationSherpas {string}: comma-delimited list of the original search string and documentation clinical conditions selected by the user when selecting this code.
For example, if the search was for “gout”, and the user clicked the conditions “foot” and “left”, the documentation string would read “gout, foot, left”.

Sample: Save Event Object

This sample contains two ICD-10 CM code selections, M10012 and E0821:

{
    "event": "save",
    "message": "Save Complete",
    "data": {
        "selectedCodes": [
            {
                "code": "M10012",
                "codeDesc": "Idiopathic gout, left shoulder",
                "codeSet": "ICD10CM",
                "documentationSherpas": "gout, foot, left"
            },
            {
                "code": "E0821",
                "codeDesc":
                "Diabetes mellitus due to underlying condition with diabetic nephropathy",
                "codeSet": "ICD10CM",
                "documentationSherpas": "Diabetes, Mellitus"
            }
        ]
    },
}

Supported Browsers

Putting it all together

<!DOCTYPE html>
<html>
     <head>
        <meta charset="UTF-8">
        <meta name="apple-mobile-web-app-capable" content="yes">

        <title>iDocuMint Widget Example</title>

        <style>
            /* #f5f5f5 to match iDocuMint background*/
            body {
                background: #fff;
                margin: 0px;
                padding: 0px;
            }

            #samples {
                float: left;
                width: 26%;
                padding: 70px 2% 2% 2%;
                font-family: sans-serif;
                color: #444;
                line-height: 1.5em;
            }

            .code {
                font-family:"courier new";
                font-size: 0.8em;
                color: #666;
                border: 1px solid #666;
                padding: 0.5em;
                overflow: auto;
            }

            #iDocuMintWidget{
                float: left;
                width: 68%;
                margin-top: 1%;
                height: auto;
                -webkit-box-shadow: 0px 0px 15px #777;
            }
        </style>
    </head>

    <body>
        <!-- sample calls to iDocuMint -->
        <div id="samples">
            <h3>Sample Calls</h3>

            <p>Click to reload iDocuMint with the selected search</p>

            <ul>
                <li onclick="idmWidget.load('icd10cm','Gout')"><a href="#">Gout</a></li>
                <li onclick="idmWidget.load('icd10cm','Gout Foot')"><a href="#">Gout Foot</a></li>
                <li onclick="idmWidget.load('icd10cm','M10.0')"><a href="#">M10.0</a></li>
                <li onclick="idmWidget.load('icd10cm','Diabetes Mellitus')"><a href="#">Diabetes Mellitus</a></li>
                <li onclick="idmWidget.load('icd10pcs','Carotid Artery Bypass')"><a href="#">Carotid Artery Bypass Procedure</a></li>
                <li onclick="idmWidget.load('icd10cm','')"><a href="#">[empty search]</a></li>
            </ul>

            <br>

            <h4>JSON Results</h4>

            <p>Click Save to populate results</p>

            <pre id="jsonResults" class="code">&nbsp;</pre>

        </div>

        <!--  START REQUIRED IDOCUMINT WIDGET CODE -->
        <div id="iDocuMintWidget" style=""></div>

        <!-- iDocuMint will be inserted here -->

        <script src="https://code.jquery.com/jquery-1.11.3.min.js"></script>

        <script> 
            var data = {
                UserName : 'your_user_here',
                Password : 'your_password_here'
            };

            var apiKey= 'your_api_key_here';

            $.ajax({ 
                url: "https://mashery.vitalware.com/ws/v2/Auth?api_key=" + apiKey,
                dataType: "jsonp",
                method: "POST",
                data: data,
                success: function( response ) {
                    console.log(response.meta.vwToken);

                    $.ajax({
                        url: "https://mashery.vitalware.com/ctl/v2/idocumint.widget.js?api_key=" + apiKey  + "&vwToken=" + response.meta.vwToken,
                        method:"GET",
                        dataType: "script",
                        success: function() {
                            idmWidget = new iDocuMintWidget({
                                autoLoad: true,
                                codeSet: 'ICD10CM',//valid: ICD10CM, ICD10PCS, ICD9CM
                                viewableCodeSets: 'ICD10CM,ICD9CM,ICD-10PCS', //valid: ICD10CM, ICD10PCS, ICD9CM
                                //searchText: searchtext, // pass to load an empty search into iDocuMint
                                container: 'iDocuMintWidget',
                                callbackOnSave: 'populateSavedCodes',
                                resultFormat: 'json', //valid: JSON, CSV 
                                assetPrefix: 'https://secure.vitalware.com/iDocumint', 
                                                    //Build environment asset & service prefix: https://build.vitalware.com/iDocuMint
                                                    //RC environment asset & service prefix: https://rc.vitalware.com/iDocuMint
                                                    //Production environment asset & service prefix: https://secure.vitalware.com/iDocuMint
                                servicePrefix: 'https://secure.vitalware.com/iDocumint',
                                serviceParams: 'showContactSupport=0&disableHistory=1&patientAge=25&patientGender=m&patientMaternity=0',
                                vwToken: response.meta.vwToken
                            });
                        }
                    });
                },
                error: function(message) { // add custom error handling
                    console.log(message);
                }
            });

            // Sample to load iDocuMint with an empty search
            //var idmWidget = new iDocuMintWidget();
        </script>

        <!-- END REQUIRED IDOCUMINT WIDGET CODE -->

        <!-- SAMPLE CALLBACK METHODS TO INTEGRATE SAVED RESULTS INTO YOUR APPLICATION -->
        <script>
            // callbackOnSave method specified in the widget options
            // Consumes the JSON retrn object
            // you must also change the returnFormat to JSON to use this method function downloadCsvFromJSON(resultObj){
            function populateSavedCodes(resultObj) { 
                console.log('downloadCsvFromJSON');
                console.log(resultObj);

                var resultData = JSON.parse(resultObj);
                var csv = resultData.data.selectedCodesCsv;

                document.getElementById('jsonResults').innerHTML = resultObj.toString();

                // Example to save a local copy of the CSV file
                // Uncomment to perform an automatic download
                //window.open( "data:text/csv;charset=utf-8," + escape(csv));
            }
        </script>
     </body>
</html>