Difference between revisions of "FAQ"
(→Direct Messaging) |
(→Miscellaneous) |
||
| (28 intermediate revisions by 4 users not shown) | |||
| Line 1: | Line 1: | ||
== Direct Messaging == | == Direct Messaging == | ||
| − | |||
| − | |||
| − | ==== What happens if we don't provide a | + | ==== What happens if we don't provide a Direct domain when setting up an Account? ==== |
| − | If no | + | If no Direct address is provided, direct.updoxqa.com will be used as the default Direct domain for the practice. For example, a user setup with the Direct address <code>johnsmith</code> will have the full Direct address <code>johnsmith@direct.updoxqa.com</code>. |
| − | ==== | + | ==== What happens if we don't provide a Direct address when setting up a Account? ==== |
| − | + | If no Direct address is provided, the practice will be unable to send practice-level Direct messages, as there is no default value. Note that many partners do not enable sending Direct messages from the practice, and sending from the practice requires authorizing with the practice user. | |
| − | ==== Why am I getting a Bad Request response when | + | ==== What happens if we don't provide a Direct address when setting up a User? ==== |
| − | + | If no Direct address is provided, the user will be unable to send Direct messages as there is no default value. | |
| − | + | ||
| + | ==== Do Direct addresses need to be unique within the domain? ==== | ||
| + | Yes. There is no way to distinguish different users with identical direct addresses, even if they belong to different Accounts or Vendors. For example, for a Direct message sent to <code>johnsmith@direct.updoxqa.com</code>, there will just be one unique <code>johnsmith@direct.updoxqa.com</code>. This necessarily implies that Direct addresses setup using the default <code>direct.updoxqa.com</code> domain will collide with all vendors testing with that default domain. | ||
| + | |||
| + | ==== Why am I getting a Bad Request response when calling [[API_Method_DirectMessageSend|DirectMessageSend]] with an attached file? ==== | ||
| + | This happens when the attachment fileData is null or has not been [[Base64-Encoding|base-64 encoded]], the fileName is null, or the mimeType is null. | ||
==== Can patients send Direct messages? ==== | ==== Can patients send Direct messages? ==== | ||
| − | + | Yes, using the [[API_Method_PatientDirectMessageSend|PatientDirectMessageSend]] API call. | |
| − | ==== How often | + | ==== How often can I call MessageCountSince? ==== |
| − | We ask that | + | We ask that you not make the [[API_Method_MessageCountSince|MessageCountSince]] API call more frequently than once every 1-3 minutes. |
| − | ==== Does [[ | + | ==== Does [[API_Method_DirectMessageSend|DirectMessageSend]] always return a messageId? ==== |
Upon successful send, yes. | Upon successful send, yes. | ||
| − | ==== For what reasons would our | + | ==== For what reasons would our Vendor credentials (applicationId and applicationPassword) ever change? ==== |
| − | + | These credentials would only change when moving from QA to Production or if the credentials are ever compromised by an attacker. Regardless of the ''reason'' for a change, it will always be done with advance warning and in coordination with affected parties. | |
| − | |||
| − | ==== | + | == MDNs == |
| − | + | ||
| − | ==== | + | ==== What is an MDN? ==== |
| − | + | An MDN is kind of like a receipt. What the receipt indicates depends on what type of MDN it is. | |
| − | ==== | + | ==== What does a status of Processed mean on an MDN? ==== |
| − | + | An MDN with a status of "Processed" means that the Sender's Direct mail server has handed off the message to the next system in the sequence (typically, this is the Receiver's Direct mail server) and received no indication of error. It does NOT mean that the recipient has received the transaction or that the recipient even exists. This is like getting a tracking number and a receipt from FedEx/UPS - it hasn't been delivered yet, but it's left your building. | |
| − | ==== Will all | + | ==== What does a status of Dispatched mean on an MDN? ==== |
| − | Yes | + | An MDN with a status of "Dispatched" means that the recipient exists, has received the message, and no errors were encountered. This is like getting a confirmation of delivery by FedEx/UPS via the signature of the recipient - it's been delivered... opening the package is up to the recipient, now. |
| + | |||
| + | ==== Why don't I get an MDN back for a failed Direct message send? ==== | ||
| + | We only get an MDN back on successes. In fact, during testing, the test scripts explicitly state that a passing requirement of a failure is that no MDN is received. The reason we don't get an MDN back on failure is because in almost every case the failure is because the receiving system either does not have or does not trust the sender's certificate. Since the MDN needs to be encrypted with the sender's certificate to send back, there is no way for the receiving system to properly encrypt a message to send back an MDN on failure. In the rare case that the MDN could be encrypted and sent back, there is no reason or requirement for the receiving system to send back that failure notice. | ||
| + | |||
| + | ==== Why am I now getting two MDNs for every message I send? ==== | ||
| + | DirectTrust specifically, and the industry in general, are rapidly embracing the dual MDN workflow. The extended information about delivery allowed by having multiple MDN types helps make Direct message processing more useful and less error-prone than the single MDN process. | ||
| + | |||
| + | |||
| + | |||
| + | == Vetting == | ||
| + | |||
| + | ==== What is "vetting" and how does it work? ==== | ||
| + | See our [[Vetting]] write-up. | ||
| + | |||
| + | ==== Will all Users be marked as vetted once one User is? ==== | ||
| + | Yes, unless your strategy uses address-level certs (as opposed to domain-level certs). | ||
==== Where does "phone on file" come from? ==== | ==== Where does "phone on file" come from? ==== | ||
The NPI database maintained by [https://nppes.cms.hhs.gov/ CMS]. | The NPI database maintained by [https://nppes.cms.hhs.gov/ CMS]. | ||
| − | + | ==== What happens during the vetting process if the call doesn't get to the User? ==== | |
| − | + | Regardless of the reason (straight to voicemail, answering service, out of service, wrong number), the vetting process fails if the user is not contacted directly. | |
| − | + | ||
| − | ==== What happens during the vetting process if the call doesn't get to the | + | |
| − | Regardless of the reason (straight to voicemail, answering service, out of service, wrong number), the vetting process fails if the user is not contacted directly | + | |
== How do I... == | == How do I... == | ||
| − | ==== How do I remove a | + | ==== How do I know if a Direct address is already in use? ==== |
| − | Calling the respective update method for updating the [[User_Management|user]] or [[Account_Management|account]] and setting | + | During the [[API_Method_UserCreate|UserCreate]] call, if the Direct address is already taken, the error code and message of <code>4610</code> - <code>{{Response_Code_4610}}</code> will be returned, indicating that the call has not been successful. |
| + | |||
| + | ==== How do I hide/delete/remove a User or Account? ==== | ||
| + | Calling the respective update method for updating the [[User_Management|user]] or [[Account_Management|account]] and setting <code>active</code> to <code>false</code> will accomplish this. | ||
| + | |||
| + | ==== Normally I use the Updox web product via SSO, but I want to login directly - how can I do that? ==== | ||
| + | See this [[Direct_Login|direct login writeup]]. | ||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
== Authentication/Authorization == | == Authentication/Authorization == | ||
| − | ==== Why am I getting a 4011 or 4012 response? ==== | + | ==== Why am I getting a 4011 or 4012 failure response? ==== |
| − | These error messages are returned when either the supplied | + | These error messages are returned when the <code>active</code> flag for either the supplied Account (<code>4011</code>) or User (<code>4012</code>) is not set to <code>true</code>. See documentation and code examples for [[Account Management]] and [[User Management]]. |
| Line 82: | Line 84: | ||
==== What is the URL to access the Webapp outside the API?==== | ==== What is the URL to access the Webapp outside the API?==== | ||
| − | {{webapp url}} | + | The address to access the Webapp directly is {{webapp url}}. Note that the loginId and loginPassword will need to be added to the user in order to login manually. |
== Miscellaneous == | == Miscellaneous == | ||
==== What HTTP Methods are supported? ==== | ==== What HTTP Methods are supported? ==== | ||
| − | All API calls should be | + | All API calls should be made using POST. |
| − | ==== Can one practice have multiple | + | ==== Can one practice have multiple Accounts? ==== |
| − | AccountId is unique for a practice. If the same practice wants multiple accounts, you must create unique accounts with unique | + | AccountId is unique for a practice. If the same practice wants multiple accounts, you must create unique accounts with unique <code>accountId</code>s and duplicate all of the users and settings across both accounts. |
==== What is an "account level message"? ==== | ==== What is an "account level message"? ==== | ||
Account level messages are messages sent to and from a practice. They differ from user level messages in that all of the users of a practice can view account-level messages. | Account level messages are messages sent to and from a practice. They differ from user level messages in that all of the users of a practice can view account-level messages. | ||
| − | + | ==== Is it possible to have the same userId in more than one practice? ==== | |
| − | + | Yes - userIds are only required to be unique to the practice in which they are created. For example, if user <code>jsmith</code> is created in Alpha practice, that same <code>userId</code> could be used again in Beta practice. However, the settings applied to Alpha.jsmith would have to be manually applied again to Beta.jsmith - the system considers them to be different Users. | |
| − | + | ||
| − | ==== Is it possible to have | + | |
| − | Yes | + | |
| − | + | ||
| − | + | ||
| − | + | ||
==== What is HMAC and how do I use it? ==== | ==== What is HMAC and how do I use it? ==== | ||
[[Updox_HMAC_Authentication|Documentation for HMAC authentication]] | [[Updox_HMAC_Authentication|Documentation for HMAC authentication]] | ||
| + | |||
| + | ==== Why are the subject, filename and content are getting processed/changed when I retrieve CC*.xml and/or PDF files? ==== | ||
| + | Processing of submitted CC*.xml and PDF files is an option that can be turned on or off. | ||
| + | |||
| + | ==== Patient Sync Limits ==== | ||
| + | It is recommended you sync a max of 150 patients at one time via the PatientSync api. | ||
Latest revision as of 10:03, 21 June 2016
Direct Messaging
What happens if we don't provide a Direct domain when setting up an Account?
If no Direct address is provided, direct.updoxqa.com will be used as the default Direct domain for the practice. For example, a user setup with the Direct address johnsmith will have the full Direct address johnsmith@direct.updoxqa.com.
What happens if we don't provide a Direct address when setting up a Account?
If no Direct address is provided, the practice will be unable to send practice-level Direct messages, as there is no default value. Note that many partners do not enable sending Direct messages from the practice, and sending from the practice requires authorizing with the practice user.
What happens if we don't provide a Direct address when setting up a User?
If no Direct address is provided, the user will be unable to send Direct messages as there is no default value.
Do Direct addresses need to be unique within the domain?
Yes. There is no way to distinguish different users with identical direct addresses, even if they belong to different Accounts or Vendors. For example, for a Direct message sent to johnsmith@direct.updoxqa.com, there will just be one unique johnsmith@direct.updoxqa.com. This necessarily implies that Direct addresses setup using the default direct.updoxqa.com domain will collide with all vendors testing with that default domain.
Why am I getting a Bad Request response when calling DirectMessageSend with an attached file?
This happens when the attachment fileData is null or has not been base-64 encoded, the fileName is null, or the mimeType is null.
Can patients send Direct messages?
Yes, using the PatientDirectMessageSend API call.
How often can I call MessageCountSince?
We ask that you not make the MessageCountSince API call more frequently than once every 1-3 minutes.
Does DirectMessageSend always return a messageId?
Upon successful send, yes.
For what reasons would our Vendor credentials (applicationId and applicationPassword) ever change?
These credentials would only change when moving from QA to Production or if the credentials are ever compromised by an attacker. Regardless of the reason for a change, it will always be done with advance warning and in coordination with affected parties.
MDNs
What is an MDN?
An MDN is kind of like a receipt. What the receipt indicates depends on what type of MDN it is.
What does a status of Processed mean on an MDN?
An MDN with a status of "Processed" means that the Sender's Direct mail server has handed off the message to the next system in the sequence (typically, this is the Receiver's Direct mail server) and received no indication of error. It does NOT mean that the recipient has received the transaction or that the recipient even exists. This is like getting a tracking number and a receipt from FedEx/UPS - it hasn't been delivered yet, but it's left your building.
What does a status of Dispatched mean on an MDN?
An MDN with a status of "Dispatched" means that the recipient exists, has received the message, and no errors were encountered. This is like getting a confirmation of delivery by FedEx/UPS via the signature of the recipient - it's been delivered... opening the package is up to the recipient, now.
Why don't I get an MDN back for a failed Direct message send?
We only get an MDN back on successes. In fact, during testing, the test scripts explicitly state that a passing requirement of a failure is that no MDN is received. The reason we don't get an MDN back on failure is because in almost every case the failure is because the receiving system either does not have or does not trust the sender's certificate. Since the MDN needs to be encrypted with the sender's certificate to send back, there is no way for the receiving system to properly encrypt a message to send back an MDN on failure. In the rare case that the MDN could be encrypted and sent back, there is no reason or requirement for the receiving system to send back that failure notice.
Why am I now getting two MDNs for every message I send?
DirectTrust specifically, and the industry in general, are rapidly embracing the dual MDN workflow. The extended information about delivery allowed by having multiple MDN types helps make Direct message processing more useful and less error-prone than the single MDN process.
Vetting
What is "vetting" and how does it work?
See our Vetting write-up.
Will all Users be marked as vetted once one User is?
Yes, unless your strategy uses address-level certs (as opposed to domain-level certs).
Where does "phone on file" come from?
The NPI database maintained by CMS.
What happens during the vetting process if the call doesn't get to the User?
Regardless of the reason (straight to voicemail, answering service, out of service, wrong number), the vetting process fails if the user is not contacted directly.
How do I...
How do I know if a Direct address is already in use?
During the UserCreate call, if the Direct address is already taken, the error code and message of 4610 - direct address error: direct address is taken will be returned, indicating that the call has not been successful.
How do I hide/delete/remove a User or Account?
Calling the respective update method for updating the user or account and setting active to false will accomplish this.
Normally I use the Updox web product via SSO, but I want to login directly - how can I do that?
See this direct login writeup.
Authentication/Authorization
Why am I getting a 4011 or 4012 failure response?
These error messages are returned when the active flag for either the supplied Account (4011) or User (4012) is not set to true. See documentation and code examples for Account Management and User Management.
Testing
How can we set up test accounts?
Follow this Quickstart guide.
What is the URL to access the Webapp outside the API?
The address to access the Webapp directly is https://updoxqa.com/app/html/login.html. Note that the loginId and loginPassword will need to be added to the user in order to login manually.
Miscellaneous
What HTTP Methods are supported?
All API calls should be made using POST.
Can one practice have multiple Accounts?
AccountId is unique for a practice. If the same practice wants multiple accounts, you must create unique accounts with unique accountIds and duplicate all of the users and settings across both accounts.
What is an "account level message"?
Account level messages are messages sent to and from a practice. They differ from user level messages in that all of the users of a practice can view account-level messages.
Is it possible to have the same userId in more than one practice?
Yes - userIds are only required to be unique to the practice in which they are created. For example, if user jsmith is created in Alpha practice, that same userId could be used again in Beta practice. However, the settings applied to Alpha.jsmith would have to be manually applied again to Beta.jsmith - the system considers them to be different Users.
What is HMAC and how do I use it?
Documentation for HMAC authentication
Why are the subject, filename and content are getting processed/changed when I retrieve CC*.xml and/or PDF files?
Processing of submitted CC*.xml and PDF files is an option that can be turned on or off.
Patient Sync Limits
It is recommended you sync a max of 150 patients at one time via the PatientSync api.
