Allscripts Unity Client

The allscripts_unity_client gem is a Ruby client for the Allscripts Unity API. See http://remotecentral.allscripts.com/UnityAPIReference for more documentation on the API.

Upgrading to 5.0.0

As of January 1, 2020, all users must authenticate via AllscriptsUnityClient::Client.get_user_authentication before calling Magic API endpoints. In version 5.0.0 of this gem we will raise an error when users attempt to call said endpoints without authenticating first. In order to test your application, you can upgrade to 5.0.0-alpha first, which will only log when you make such unauthenticated calls.

Installation

Add this line to your application's Gemfile:

gem "allscripts_unity_client"

And then execute:

$ bundle install

Or install it yourself as:

$ gem install allscripts_unity_client

Usage

Creating clients

The Allscripts Unity API supports both JSON and SOAP. Both versions are supported by this gem. A Unity API client can be created using the AllscriptsUnityClient.create factory:

unity_client = AllscriptsUnityClient.create({
  base_unity_url: "http://unity.base.url",
  appname: "appname",
  username: "unity license username",
  password: "unity license password",
  ehr_userid: "userid",
  ehr_password: "password"
})

A JSON client can also be created using the :mode option:

# Mode defaults to :soap
unity_client = AllscriptsUnityClient.create({
  mode: :json,
  base_unity_url: "http://unity.base.url",
  appname: "appname",
  username: "unity license username",
  password: "unity license password",
  ehr_userid: "userid",
  ehr_password: "password"
})

SSL Management

Faraday is used in combination with EM-HTTP-Request to send HTTP requests when using JSON clients. Faraday requires some configuration when making connections over SSL. AllscriptsUnityClient will try to auto-detect the location of the operating system's CA File or CA Path, but these values can be explicitly configured when creating a client:

# Mode defaults to :soap
unity_client = AllscriptsUnityClient.create({
  mode: :json,
  base_unity_url: "http://unity.base.url",
  appname: "appname",
  username: "unity license username",
  password: "unity license password",
  ehr_userid: "userid",
  ehr_password: "password",
  ca_file: "/usr/lib/ssl/certs/ca-certificates.crt"
})

OR

# Mode defaults to :soap
unity_client = AllscriptsUnityClient.create({
  mode: :json,
  base_unity_url: "http://unity.base.url",
  appname: "appname",
  username: "unity license username",
  password: "unity license password",
  ehr_userid: "userid",
  ehr_password: "password",
  ca_path: "/usr/lib/ssl/certs"
})

Request Timeout

When using a JSON client, request timeouts can be configured:

# Mode defaults to :soap
unity_client = AllscriptsUnityClient.create({
  mode: :json,
  base_unity_url: "http://unity.base.url",
  appname: "appname",
  username: "unity license username",
  password: "unity license password",
  ehr_userid: "userid",
  ehr_password: "password",
  timeout: 30
})

Timeout is given in seconds and defaults to 90.

Security token management

Security tokens can be manually requested using the get_security_token! method:

unity_client.get_security_token! # Fetches a new security token and stores it in security_token

After calling get_security_token!, each call to magic will automatically send security_token with the request. If a security token is no longer valid, an exception will be raised by Unity.

The token can be accessed using the security_token accessor:

unity_client.security_token

Security tokens can be retired using the retire_security_token! method:

unity_client.retire_security_token! # Retires the security token with Unity and sets security_token to nil

Existence of a security token can also be checked:

unity_client.security_token?

User authentication

After a security token has been obtained and before executing Magic calls, a client must get user authentication. This is done via the get_user_authentication method:

unity_client.get_user_authentication

Note that the ehr_userid and ehr_password passed to AllscriptsUnityClient.create are the credentials used for this call.

Also note that any attempts to make Magic calls before authenticating will result in an AllscriptsUnityClient::UnauthenticatedError error.

Executing Magic calls

The endpoint used to make API calls in Unity is called Magic. Magic can be accessed with the client:

unity_client.magic({
  action: "action",
  userid: "userid",
  appname: "appname", # Only use to override default. Default: unity_client.appname
  patientid: "patientid",
  token: "token", # Only use to override default. Default: unity_client.security_token
  parameter1: "parameter1",
  parameter2: "parameter2",
  parameter3: "parameter3",
  parameter4: "parameter4",
  parameter5: "parameter5",
  parameter6: "parameter6",
  data: "data"
})

All keys in the hash given to magic are optional. See the Allscripts Unity API documentation for more information about which API calls are supported

Magic call helpers

A number of helper methods exist that abstract away the details of the Magic operation:

• get_account
• get_changed_patients(since = nil)
• get_chart_item_details(userid, patientid, section)
• get_clinical_summary(userid, patientid, extra_med_data = false)
• get_dictionary(dictionary_name, userid = nil, site = nil)
• get_encounter_list(userid, patientid, encounter_type, when_param = nil, nostradamus = nil, show_past_flag = nil, billing_provider_user_name = nil)
• get_medication_by_trans_id(userid, patientid, transaction_id)
• get_medication_info(userid, ddid, patientid = nil)
• get_patient(userid, patientid, includepix = nil)
• get_patient_activity(userid, patientid)
• get_patient_problems(patientid, show_by_encounter_flag = nil, assessed = nil, encounter_id = nil, medcin_id = nil)
• get_patient_by_mrn(userid, mrn)
• get_patients_by_icd9(icd9, start = nil, end_param = nil)
• get_provider(provider_id = nil, user_name = nil)
• get_providers(security_filter = nil, name_filter = nil)
• get_server_info
• get_task(userid, transaction_id)
• get_task_list(userid = nil, since = nil)
• last_logs
• save_rx(userid, patientid, rxxml)
• save_task(userid, patientid, task_type = nil, target_user = nil, work_object_id = nil, comments = nil)
• save_task_status(userid, transaction_id = nil, param = nil, delegate_id = nil, comment = nil)
• search_meds(userid, patientid, search = nil)
• search_patients(search)
• search_pharmacies(search)

All magic helper methods not on this list currently raise NotImplementedError. More helper methods will be added in future releases. Pull requests welcome.

Timezone

All times and dates coming from Unity are in local timezones. When creating the client, the :timezone option can be used to configure automatic timezone conversion. If no :timezone is given, then it will default to UTC. Timezones must be given in TZInfo zone identifier format. See TZInfo for more information:

unity_client = AllscriptsUnityClient.create({
  timezone: "America/New_York",
  base_unity_url: "http://unity.base.url",
  appname: "appname",
  username: "unity license username",
  password: "unity license password",
  ehr_userid: "userid",
  ehr_password: "password"
})

Any magic action that takes in a date needs to be given in UTC. Dates can be Date, DateTime, Time, or a string. Dates will be processed and formatted in the correct ISO8601 format that Unity requires.

Logging

By default Ruby's Logger is used and logs to STDOUT with a level of Logger::INFO. Custom loggers can be configured with the :logger option:

unity_client = AllscriptsUnityClient.create({
  base_unity_url: "http://unity.base.url",
  appname: "appname",
  username: "unity license username",
  password: "unity license password",
  ehr_userid: "userid",
  ehr_password: "password",
  logger: Rails.logger
})

Logging can be disabled by setting the :logger option to nil (this is the default):

unity_client = AllscriptsUnityClient.create({
  base_unity_url: "http://unity.base.url",
  appname: "appname",
  username: "unity license username",
  password: "unity license password",
  ehr_userid: "userid",
  ehr_password: "password",
  logger: nil
})

Responses are not logged and Magic action is the only parameter logged with requests. This is done to prevent exposing PHI.

Proxy

An HTTP proxy can be configured using the :proxy option:

unity_client = AllscriptsUnityClient.create({
  base_unity_url: "http://unity.base.url",
  appname: "appname",
  username: "unity license username",
  password: "unity license password",
  ehr_userid: "userid",
  ehr_password: "password",
  proxy: "http://localhost:8888"
})

Locale

This gem uses the american_date gem to force Date.parse to accept USA locale dates by default. There are currently no plans to support other locales. Pull requests welcome.

Examples

GetServerInfo SOAP

unity_client = AllscriptsUnityClient.create({
  base_unity_url: "http://unity.base.url",
  appname: "appname",
  username: "unity license username",
  password: "unity license password",
  ehr_userid: "userid",
  ehr_password: "password",
  timezone: "America/New_York"
})

unity_client.get_security_token!
unity_client.get_user_authentication

# API call made using a helper
unity_client.get_server_info

The above example would output the following Hash:

{
  server_time_zone: "Eastern Standard Time",
  server_time: #<DateTime: 2013-11-01T15:49:23+00:00 ((2456598j,56963s,0n),+0s,2299161j)>,
  server_date_time_offset: #<DateTime: 2013-11-01T19:49:23+00:00 ((2456598j,71363s,0n),+0s,2299161j)>,
  system: "Enterprise EHR",
  product_version: "11.2.3.32.000",
  uaibornondate: #<Date: 2013-07-10 ((2456484j,0s,0n),+0s,2299161j)>
}

GetServerInfo JSON

unity_client = AllscriptsUnityClient.create({
  mode: :json
  base_unity_url: "http://unity.base.url",
  appname: "appname",
  username: "unity license username",
  password: "unity license password",
  ehr_userid: "userid",
  ehr_password: "password",
  timezone: "America/New_York"
})

unity_client.get_security_token!
unity_client.get_user_authentication

# API call made using a helper
unity_client.get_server_info

The above example would output the following Hash:

{
  server_time_zone: "Eastern Standard Time",
  server_time: #<DateTime: 2013-11-01T15:49:23+00:00 ((2456598j,56963s,0n),+0s,2299161j)>,
  server_date_time_offset: #<DateTime: 2013-11-01T19:49:23+00:00 ((2456598j,71363s,0n),+0s,2299161j)>,
  system: "Enterprise EHR",
  product_version: "11.2.3.32.000",
  uaibornondate: #<Date: 2013-07-10 ((2456484j,0s,0n),+0s,2299161j)>
}

Contributing

1. Fork it
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Added some feature')
4. Push to the branch (git push origin my-new-feature)
5. Create new Pull Request

Additional Information

Maintainer(s): Neil Goodman (https://github.com/posco2k8)

License

Copyright (c) 2014 healthfinch, Inc

MIT License

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.