This document focuses on what application developers need to know about the interfaces between Web applications and the Shell, which are core parts of the HealthVault API.
Redirecting to the Shell
As a general rule, all Shell functionality is accessed through a single redirector page at https://shellhostname/redirect.aspx. This page accepts two query string parameters:
- target indicates the desired Shell function. Possible target values are enumerated below with details about how to call them.
- targetqs is a URL-encoded query string that is passed as-is to the Shell page that services the given target. This query string can include the following parameters:
- redirect is for non-production use only. For redirections where the Shell redirects to the calling application after performing some function, this value overrides the ACTION URL application metadata. Details on the return mechanism are described in Returning to the Application.
- actionqs is a value that is returned as-is to the calling application. This value can be used for whatever the application wants. [1]
- extrecordid is optional and used only for targets that act on a particular record (for example, SHARERECORD). If present, it should be the record identifier that the application wants the Shell to work against.
- target-specific parameters: Different targets may require different parameters to be passed to support their functions. These parameters are documented with each target below.
For .NET SDK users, HealthServicePage offers wrappers that are intended to make redirecting to the Shell simpler. The methods RedirectToLogon and SignOut do redirection correctly; currently, the RedirectToShellUrl and related ConstructShellTargetUrl methods do not properly add the redirect parameter for development environments.
For non-.NET SDK users, the redirect process is generally fairly simple. Build an appropriate targetqs, URLEncode it, and send the browser to the URL https://shellhostname/redirect.aspx?target=TARGET&targetqs=TARGETQS.
Shell Targets
The following targets are available for use by applications. Note that much of this information is duplicated in the documentation for HealthServiceLocation.GetHealthServiceShellUrl, but that documentation is not sufficient for general use.
APPAUTH
Prompts the user to authorize and select a record or records for use by the application.
| targetqs parameter | Value | Notes |
| appid | Application identifier | |
| ismra (optional) | True or False | Default is False. If this value is true, it is an indication that this application knows how to work with multiple records. The user will be allowed to authorize multiple records at once. |
| extrecordid (optional) | Record identifier | |
| onopt# | Sequence of online optional authorization rule names identifying which rules to present. | Sequence begins with 1. Example: onopt1=name1&onopt2=name2 |
| offopt# | Sequence of offline optional authorization rule names identifying which rules to present. | Sequence begins with 1. Example: offopt1=name1&offopt2=name2 |
After app auth, the browser will be redirected back to the application with either the SELECTEDRECORDCHANGED, APPAUTHSUCCESS or APPAUTHREJECT target.
The .NET SDK does not provide a wrapper for this target.
APPREDIRECT
Redirects the user to a HealthVault application.
| targetqs parameter | Value | Notes |
| appid | Destination application identifier | |
| refappid | Referring application identifier | |
| target | Parameter value | This is used as the value of the "target" parameter when the user's browser is redirected to the destination application's action-url. |
| targetqs | Parameter value | This is used as the value of the "targetqs" parameter when the user's browser is redirected to the destination application's action-url. |
The .NET SDK does not provide a wrapper for this target.
APPSIGNOUT
This target indicates that the user is logging off from a HealthVault application and causes the Shell logon cookie to be discarded, if necessary.
| targetqs parameter | Value | Notes |
| appid | Application identifier | |
After the user signs out, the browser is redirected to the application with the SIGNOUT target.
This target is wrapped in the HealthServicePage.SignOut methods of the .NET SDK. These methods also discard the application logon cookie, so this wrapper should not be bypassed in the ASP.NET environment.
AUTH
Prompts the user to log into HealthVault and authorize records if needed.
| targetqs parameter | Value | Notes |
| appid | Application identifier | |
| ismra (optional) | True or False | Default is False. If this value is true, it is an indication that this application knows how to work with multiple records. The user will be allowed to authorize multiple records at once. |
| forceappauth (optional) | True or False | Default is False. If this value is True, the user will always be prompted to authorize records after they authenticate. |
| onopt# | Sequence of online optional authorization rule names identifying which rules to present. | Sequence begins with 1. Example: onopt1=name1&onopt2=name2 |
| offopt# | Sequence of offline optional authorization rule names identifying which rules to present. | Sequence begins with 1. Example: offopt1=name1&offopt2=name2 |
After login and (if necessary) app auth, the browser will be redirected back to the application with either the APPAUTHSUCCESS or APPAUTHREJECT target.
The .NET SDK wraps this target up in the HealthServicePage.RedirectToLogOn method, which additionally sets the actionqs parameter to the full relative path of the current page, including query string parameters, which case be used to ensure that the user lands back on the page they started from. However, this use of actionqs is by convention only and other platforms need not follow it.
CREATEACCOUNT
This target allows the user to create a new HealthVault account and authorize it for access to the application.
| targetqs parameter | Value | Notes |
| appid | Application identifier | |
| ismra (optional) | True or False | Default is False. If this value is true, it is an indication that this application knows how to work with multiple records. The user will be allowed to authorize multiple records at once. |
| onopt# (optional) | Sequence of online optional authorization rule names identifying which rules to present. | Sequence begins with 1. Example: onopt1=name1&onopt2=name2 |
| offopt# (optional) | Sequence of offline optional authorization rule names identifying which rules to present. | Sequence begins with 1. Example: offopt1=name1&offopt2=name2 |
| nsi (optional) | 0 or 1. | Default is 0. If this value is 1, account creation bypasses the page for entering an email address. |
After the user has created the HealthVault account, they will be prompted to authorize it for the application. The browser will be redirected back to the application with either the SELECTEDRECORDCHANGED, APPAUTHSUCCESS, or APPAUTHREJECT target.
The .NET SDK does not provide a wrapper for this target.
CREATEAPPLICATION
This target allows a SODA application to create a new client instance.
| targetqs parameter | Value | Notes |
| appid | Unique ID of the master application | The new client application will be an instance of this master application. |
| instanceid | Unique ID of the client application | Each client instance must have its own instance ID. |
| instancename | Name of the client application | A string, such as a computer name, that identifies the device that the new client application instance will run on |
| publickey | public key of the new client application instance | The key must be an X509 certificate that is Base64 encoded. |
CREATERECORD
This target allows the user to create a new HealthVault record and authorize it for access to the application.
| targetqs parameter | Value | Notes |
| appid | Application identifier | |
| ismra (optional) | True or False | Default is False. If this value is true, it is an indication that this application knows how to work with multiple records. The user will be allowed to authorize multiple records at once. |
| onopt# (optional) | Sequence of online optional authorization rule names identifying which rules to present. | Sequence begins with 1. Example: onopt1=name1&onopt2=name2 |
| offopt# (optional) | Sequence of offline optional authorization rule names identifying which rules to present. | Sequence begins with 1. Example: offopt1=name1&offopt2=name2 |
After the user has created the record, they will be prompted to authorize it for the application. The browser will be redirected back to the application with either the SELECTEDRECORDCHANGED, APPAUTHSUCCESS, or APPAUTHREJECT target.
The .NET SDK does not provide a wrapper for this target.
HELP
This target can be used to open the HealthVault help pages, optionally with a particular topic selected.
| targetqs parameter | Value | Notes |
| topicid (optional) | String value identifying the topic to display | If not present, the help overview page is shown. Topic IDs can be found by looking at the “topicid” parameters in the HealthVault Shell; however, most of these topics are not guaranteed to be “durable” and we do not recommend linking to them under normal circumstances. Two exceptions to this recommendation are the topics “PrivacyPolicy” and “ServiceAgreement,” which can be used to direct a browser to these important topics. |
This is a “dead end” target—the Shell does not provide a mechanism to return to the application. Because of this circumstance, we recommend that you open this target in a new browser window.
The .NET SDK does not provide a wrapper for this target.
MANAGEACCOUNT
This target takes the user to a page where they can manage their account profile.
| targetqs parameter | Value | Notes |
| N/A | N/A | |
The shell does not provide a mechanism to return back to the application. We recommend that you open this target in a new browser window.
The .NET SDK does not provide a wrapper for this target.
RECONCILE
This target prompts the user to review the individual data elements within a CCR or CCD file and decide how they want to integrate them as individual HealthVault items into their record. For each item in the file, the user can choose to add it to their record, replace an existing item with it, or ignore (not add) it.
The application must use the extrecordid parameter to indicate the record containing the CCR/CCD file.
| targetqs parameter | Value | Notes |
| appid | Application identifier | |
| extrecordid (optional) | Record identifier | |
| thingid | Thing ID of the CCR/CCD file that should be displayed to the user | |
Depending on the user action, the browser will be redirected back to the application with RECONCILECOMPLETE, RECONCILEFAILURE, or RECONCILECANCELED. RECONCILECOMPLETE indicates that the user clicked "Save Changes" and completed the transaction. RECONCILEFAILURE indicates that the user clicked "Save Changes" but the transaction failed. RECONCILECANCELED indicates that the user clicked the "Cancel" button.
The .NET SDK does not provide a wrapper for this target.
RECORDLIST
This target prompts the user to review the individual data elements within a CCR or CCD file and decide how they want to integrate them as individual HealthVault items into their record. For each item in the file, the user can choose to add it to their record, replace an existing item with it, or ignore (not add) it.
The application must use the extrecordid parameter to indicate the record containing the CCR/CCD file.
| targetqs parameter | Value | Notes |
| appid (optional) | Application identifier | If an application ID is specified, the page only displays records which that application is authorized to access |
The RECORDLIST target does not redirect the browser back to the application. It should be opened in a new browser window.
SHAREDAPPDETAILS
This target allows the user to manage application authorization for a HealthVault record.
The application must use the extrecordid parameter to indicate the authorized record.
| targetqs parameter | Value | Notes |
| appid | Application identifier | The application whose authorization should be presented to the user |
| extrecordid (optional) | Record identifier | |
The shell does not provide a mechanism to return back to the application. We recommend that you open this target in a new browser window.
The .NET SDK does not provide a wrapper for this target.
SHARERECORD
This target prompts the user to share a record with another HealthVault user.
The application uses the extrecordid parameter to indicate which record to share.
| targetqs parameter | Value | Notes |
| Appid | Application identifier | |
| extrecordid (optional) | Record identifier | |
After completing the sharing operation, the browser is redirected to the application with either the SHARERECORDSUCCESS or SHARERECORDFAILED target. If the extrecordid parameter is invalid, the browser redirects with the APPAUTHINVALIDRECORD.
The .NET SDK does not provide a wrapper for this target.
VIEWITEMS
Allows a HealthVault user to view all of the items of a specified data type in their record.
| targetqs parameter | Value | Notes |
| typeid | Data type identifier | Comma delimited list of data type IDs |
| additem | True or False | Default is False. If this value is true, the New Item dialog for the data type is displayed. |
| extrecordid | Record identifier | |
The .NET SDK does not provide a wrapper for this target.
Returning to the Application
The Shell can redirect to applications in a few different contexts, sometimes after handling a request from an application and sometimes on its own initiative (for example, when linking to an application’s privacy policy from within the Programs tab).
The Shell generally redirects to an application using its ACTION URL, which is specified in the application metadata collected at partner setup time. Two query string parameters are sent along with the request:
- target indicates the purpose of the redirection. This parameter can be an indication of the status of a redirection sent to the Shell, or it can be a simple indicator of a special page to display, such as the application’s privacy policy. Possible values are enumerated below.
- actionqs is a value originally provided by the application that is reflected back to the application on return. Use of this parameter is up to the application.[2]
When developers are working on an application, the ACTION URL method does not work because all developers use a shared application metadata record in the HealthVault partner environment, but need the Shell to redirect to their personal development machines. To deal with this situation, the Shell partner and development environments accept a “redirect” parameter; if this parameter is present, the Shell uses it to return to the application, overriding the ACTION URL.
This use raises the question: Why the complicated scheme; why not just always use a redirect parameter? The answer is to maintain browser security and avoid phishing vulnerabilities. The “redirect” parameter NEVER works in the HealthVault production environment because it is never acceptable for the Shell to redirect arbitrarily. If we allowed such redirection, phishers could create URLs that tricked the Shell into sending credential tokens back to arbitrary Web sites.
Application Targets
Applications must be sure to handle actions appropriately. Appropriate handling includes not only the “return” actions, such as APPAUTHSUCCESS, but also the actions that are used from within the programs tab and directory—in particular HOME, PRIVACY, and SERVICEAGREEMENT. Properly supporting these targets is key to providing a trustworthy experience for HealthVault application users.
APPAUTHINVALIDRECORD
Sent when the Shell finds an invalid record id in the extrecordid parameter.
APPAUTHREJECT
Sent when the user denied or cancelled an application auth request.
If this return is the result of the .NET SDK RedirectToLogOn method, the actionqs parameter is set to the relative path and query string that the user was viewing when the logon request was initiated.
APPAUTHSUCCESS
Sent when the user has successfully logged on and/or granted application auth.
If this return is the result of the .NET SDK RedirectToLogOn method, the actionqs parameter is set to the relative path and query string that the user was viewing when the logon request was initiated.
HELP
This target opens the application’s main Help page.
HOME
This target opens the application Home page. In most cases, this page does not require logging on; it contains information about the application that users can review to determine if they are interested in the application.
PRIVACY
This target opens the application’s privacy policy. This page does not require logging on, so that the user can review the policy before granting application auth.
RECONCILECANCELED
Sent when the user clicks "Cancel" on the CCR / CCD integration page.
RECONCILECOMPLETE
Sent when the user clicks "Save Changes" on the CCR / CCD integration page and the transaction completes successfully.
RECONCILEFAILURE
Sent when the user clicks "Save Changes" on the CCR / CCD integration page and the transaction fails.
SELECTEDRECORDCHANGED
This target is sent on return from an APPAUTH request where the user selects a new record for use in an SRA application.
It is important that the application refresh any cached record-related information when this target is received. Users of the .NET SDK can use HealthServicePage.RefreshAndPersist to accomplish this refresh.
SERVICEAGREEMENT
This target opens the applications’ terms of use or service agreement. This page does not require logging on, so that the user can review the policy before granting application auth.
SHARERECORDFAILED
Sent when a record-sharing invitation could not be sent.
SHARERECORDSUCCESS
Sent when a record-sharing invitation was sent successfully.
SIGNOUT
Sent on return from an APPSIGNOUT request to the Shell.
[1] One exception for those using the .NET SDK is that the current HealthServicePage RedirectToLogOn method (called automatically when the page sets the LogonRequired property to true) sets actionqs to be the relative path and query string of the calling page. This is done so that the user can be sent back to the page they started from; however, the current implementation of HealthServiceActionPage ignores the value on return.
[2] The .NET SDK makes using this parameter a bit awkward because it does “hijack” the actionqs in one circumstance—the RedirectToLogon method. See the footnote for the Shell target AUTH for more information here.