HealthVault Shell Redirect InterfacesThis 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 ShellAs 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:
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 TargetsThe 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.
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.
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.
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.
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.
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.
CREATERECORD This target allows the user to create a new HealthVault record and authorize it for access to the application.
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.
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.
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.
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.
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.
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.
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.
The .NET SDK does not provide a wrapper for this target. Returning to the ApplicationThe 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:
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 TargetsApplications 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. |
