Export (0) Print
Expand All

Shell redirect interface

HealthVault

This article 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.

Last updated: March 2013

This topic contains the following sections.

An application can access publicly available Shell functionality by using a single redirector page at http://ShellURL/redirect.aspx . For example, an application will redirect the user to the Shell login page for authentication.

To use Shell functionality, the application should construct the redirect URL with two query string parameters:

  • target indicates the desired Shell function, discussed further in the Shell redirect targets API section.

  • 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 ActionURL application metadata.

    • actionqs is a value that is returned as-is to the calling application. This value can be used for whatever the application wants.

    • 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 for the record that the application wants the Shell to work against.

    • lcid or culture is used to specify the display language for the destination target. The lcid parameter must be a valid Locale ID (decimal, such as 1033, not hex). The culture parameter must be a valid ISO format (such as en-US). The language must be supported on that instance of HealthVault. For more information about supported languages, see the Global HealthVault instances section in HealthVault development basics.

    • target-specific parameters may be required by some of the redirect targets. These parameters are documented with each redirect target below.

    • aib (allow instance bounce) indicates whether the user can be redirected to another instance on this request. For more information, see The allow instance bounce (aib) parameter.

An application can use Shell functionality by creating a proper redirect URL. Construct the redirect URL with target query parameters: https://ShellUrl/redirect.aspx?target=TARGET&targetqs=TARGETQS.

You should URL-encode the targetqs. For example:

https://ShellUrl/redirect.aspx?target=APPAUTH&targetqs=appid%3dguid%26ismra%3dtrue

Using the .NET SDK

The .NET SDK has some helper methods that create the URL for you. Using the classes in the Microsoft.Health.Web namespace, a web application can extend the HealthServicePage class and invoke the RedirectToShellUrl method or can use the WebApplicationUtilities class to redirect to the Shell. For example, if the page extends from the HealthServicePage class:

 
this.RedirectToShellUrl("APPAUTH", "appid=" + this.ApplicationId.ToString() +
    "&ismra=true" + "&extrecordid=12854139-f27b-4ab4-ab68-c1757b9fad0w");

Redirecting the Shell back to your app

After the target action, the Shell will redirect to the application using its ActionURL, which is specified in the application metadata set in the Application Configuration Center (ACC).

These 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.

  • actionqs is a value originally provided by the application that is sent back to the application on return. Use of this parameter is up to the application.

  • targetDetails includes additional information and is used only in special situations (explained later in this document).

  • instanceID uniquely identifies the instance in which the shell target was completed. For a list of existing instances, see HealthVault Instance Configurations. For more information, see HealthVault global architecture.

When developers are working on an application, the ActionURL may not work because all the developers use a shared application metadata record in the HealthVault development environment (PPE) but need the Shell to redirect to their personal development machines. To deal with this situation, the Shell development environments accept a redirect parameter; if this parameter is present, the Shell uses it to return to the application instead of using the ActionURL.

Shell defines the following redirect targets.

APPAUTH

Prompts the user to select a record or records and authorize the application access to them.

An example request URL:

https://ShellUrl/redirect.aspx?target=APPAUTH&targetqs=appid%3Dguid%26ismra%3Dtrue

An example request URL with redirected response:

https://ShellUrl/redirect.aspx?target=APPAUTH&targetqs=appid%3dguid%26ismra%3dtrue%26extrecordid%3dguid&trm=post

targetqs parameter

Value

Notes

appid

Application identifier

Comma-delimited list of appids. (Multiple appid is supported only for the APPAUTH target.)

ismra (optional)

True or False

Default is False. If this value is True, it is an indication that this application wants to be treated as an MRA. The user will be allowed to authorize multiple records at once.

extrecordid (optional)

Record identifier

Selects the record to be used with the application.

onopt# (optional)

Sequence of online optional authorization rule names identifying which rules to present.

The sequence begins with 1.

Example: onopt1=name1&onopt2=name2

offopt# (optional)

Sequence of offline optional authorization rule names identifying which rules to present.

The sequence begins with 1.

Example: offopt1=name1&offopt2=name2

trm (optional)

Get or Post

Determines the token redirection method. Default is Get.

For more information about optional rules, see the Requesting authorization to optional rules section of Connectivity lifecycle.

After app auth, the browser will be redirected back to the application as per the ActionURL value with the SELECTEDRECORDCHANGED, APPAUTHSUCCESS or APPAUTHREJECT target. For more information, see Return application targets.

An example response from the Shell:

http://ActionURL?target=AppAuthSuccess

In case of an online web application, the application needs to store the auth token and should exchange it in any future calls to the HealthVault web service.

APPREDIRECT

Redirects the user to another HealthVault application. This target enables one application to communicate with another HealthVault application via the Shell interface.

An example request URL:

https://ShellUrl/redirect.aspx?target=APPREDIRECT&targetqs=appid%3dguid

targetqs parameter

Value

Notes

appid

Destination application identifier

This is the only method where appid parameter is used for the target application.

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 ActionURL.

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 ActionURL.

APPSIGNOUT

Signs the user out of HealthVault.

An example request URL:

https://ShellUrl/redirect.aspx?target=APPSIGNOUT&targetqs=appid%3dguid

targetqs parameter

Value

Notes

appid

Application identifier

credtoken (optional)

Authentication token

Optional but highly recommended. This is used to invalidate the HealthVault authentication token used by the application.

After the user signs out, the browser is redirected to the application with the SIGNOUT target. See Return application targets.

An example response URL:

https://ActionURL?target=SignOut

The .NET SDK wrapper for this target is the HealthServicePage..::..SignOut method. This method also discards the application auth cookie; discarding the cookie is required to sign the user out of the application. If the application does not use this method, it must manually delete the auth cookie when signing the user out.

AUTH

Allows the user to log into HealthVault. If the user has not authorized any records for the application, or if the foreceappauth parameter is passed in, the user will also be asked to authorize one or more records.

A scenario where this target will be used is when the user is first signing in to HealthVault.

An example request URL:

https://ShellUrl/redirect.aspx?target=AUTH&targetqs=appid%3dguid

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 wants to be treated as an MRA. The user will be allowed to authorize multiple records at once.

trm (optional)

Get or Post

Determines the token redirection method. Default is Get.

After login and (if necessary) application authorization, the browser will be redirected back to the application with either the APPAUTHSUCCESS or APPAUTHREJECT or SELECTEDRECORDCHANGED target. See Return application targets.

Response URL example:

http://ActionURL?target=SelectedRecordChanged

The .NET SDK wrapper for this target is the HealthServicePage..::..RedirectToLogOn method, which additionally sets the actionqs parameter to the full relative path of the current page, including query string parameters, which is 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.

In case of an online web application, the application needs to store the auth token and should exchange it in any further calls to the HealthVault web service.

CONNECT

Allows a user to view (and accept or reject) a Patient Connect request.

An example request URL:

https://ShellUrl/redirect.aspx?target=CONNECT&targetqs=packageid%3dguid

targetqs parameter

Value

Notes

packageid

Identity code for the connection request

The unique code generated by HealthVault that identifies the request.

For more information about Patient Connect, see Establishing authorization with a user using Patient Connect.

CREATEACCOUNT

Allows the user to create a new HealthVault account and authorize the application to access it.

An example request URL:

https://ShellUrl/redirect.aspx?target=CREATEACCOUNT&targetqs=appid%3dguid

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 wants to be treated as an MRA. 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.

The sequence begins with 1.

Example: onopt1=name1&onopt2=name2

offopt# (optional)

Sequence of offline optional authorization rule names identifying which rules to present.

The sequence begins with 1.

Example: offopt1=name1&offopt2=name2

flow (optional)

eprep or WMgmt

Currently there are 2 specialized sign-up workflows that are supported: eprep for the emergency preparedness workflow, and WMgmt for the weight management workflow.

daddrec

True or False

True to disable the Add another family member link; otherwise, False.

To pass in user data that was collected by your application in order to pre-populate the account and record creation pages, see the discussion in Posting user data with application-initiated account and record creation .

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 the APPAUTHSUCCESS or APPAUTHREJECT target. See Return application targets.

An example response URL:

http://ActionURL?target=AppAuthSuccess&targetDetails=CreateAccountSuccess

Using the CreateAccount target doesn't guarantee that the user will create a new account. Users will be redirected to the account sign up page. But the user can then sign in to an existing account and authorize it. The application can check if the user canceled creating a new account by parsing the targetDetails after the user returns to the application. See Return application targets.

CREATEAPPLICATION

Allows a SODA application to create a new client instance.

An example request URL:

https://ShellUrl/redirect.aspx?target=CREATEAPPLICATION&targetqs=%3Fappid%3Dguid%26appCreationToken%3Dtoken%26instanceName%3Dinstance%26ismra%3Dtrue

targetqs parameter

Value

Notes

appid

Unique ID of the master application

The new client application will be an instance of this master application.

appCreationToken

Token obtained from HealthVault containing the shared secret and information needed to provision the application instance

The token is obtained by calling the NewApplicationCreationInfo method in the HealthVault web services XML API. For more information, see the Method browser.

instancename

Name of the client application

A string, such as a mobile device name, that identifies the device that the new client application instance will run on.

Once the child application is created, the Shell will automatically redirect the user to the sign-in page. Upon successful user login, the Shell will redirect to the record selection page. After the user selects records and gives the application access to them, the browser will be redirected back to the application with the APPAUTHSUCCESS target. The application should then invoke the GetAuthorizedRecords HealthVault web services XML method to get the authorized records for the application instance.

CREATERECORD

Allows the user to create a new HealthVault record and authorize it for access by the application.

An example request URL:

https://ShellUrl/redirect.aspx?target=CREATERECORD&targetqs=appid%3dguid

targetqs parameter

Value

Notes

appid

Application identifier

ismra (optional)

True or False

Default is False.

True to have the Shell treat the application as an MRA. 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.

The sequence begins with 1.

Example: onopt1=name1&onopt2=name2

offopt# (optional)

Sequence of offline optional authorization rule names identifying which rules to present.

The sequence begins with 1.

Example: offopt1=name1&offopt2=name2

To pass in user data that was collected by your application in order to pre-populate the record creation pages, see the discussion in Posting user data with application-initiated account and record creation.

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 the APPAUTHSUCCESS or APPAUTHREJECT target. For more information, see Return application targets.

An example response URL:

http://ActionURL?target=AppAuthSuccess

EDITRECORD

Prompts the user to edit the profile information of the specified record.

An example request URL:

https://ShellUrl/redirect.aspx?target=EDITRECORD&targetqs=appid%3dguid%26extrecordid%3dguid

targetqs parameter

Value

appid

Application identifier

extrecordid

Record identifier

After the user has either saved or canceled, the browser will be redirected back to the application with EDITRECORDCOMPLETE or EDITRECORDCANCEL. See Return application targets.

An example response URL:

http://ActionURL?target=EditRecordComplete

HELP

This target can be used to open the pages displayed at help.aspx, such as HealthVault Help, the privacy policy, the service agreement, and the code of conduct.

targetqs parameter

Value

Notes

topicid (optional)

String value identifying the topic to display

If no topicID is present, the help 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 PrivacyPolicy and ServiceAgreement topics, which can be used to direct a browser to these important topics.

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.

MANAGEACCOUNT

Takes the user to a page where they can manage their account profile.

An example request URL:

https://ShellUrl/redirect.aspx?target=MANAGEACCOUNT&targetqs=appid%3dguid

targetqs parameter

Value

appid

Application 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.

PICKUP

Allows a user to pick up a DOPU package.

An example request URL:

https://ShellUrl/target=PICKUP&targetqs=packageid%3dguid

targetqs parameter

Value

Notes

packageid

Identity code for the package

The unique code generated by HealthVault that identifies the package.

More information about DOPU packages can be found in the article HealthVault drop-off and pick-up (DOPU).

RECONCILE

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. If the document was automatically reconciled, then the user will be taken instead to an interface to review the data that was added.

The application must use the extrecordid parameter to indicate the record that contains the CCR/CCD file.

An example request URL:

https://ShellUrl/redirect.aspx?target=RECONCILE&targetqs=appid%3dguid%26extrecordid%3dguid%26thingid%3dguid

targetqs parameter

Value

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. For more information, see Return application targets.

RECORDLIST

Displays the records in the user's HealthVault account.

An example request URL:

https://ShellUrl/redirect.aspx?target=RECORDLIST

targetqs parameter

Value

Notes

appid (optional)

Application identifier

If an application ID is specified, the page displays only the records which that application is authorized to access.

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.

SHAREDAPPDETAILS

Allows the user to update application authorization for a HealthVault record.

The application must use the extrecordid parameter to indicate the authorized record.

An example request URL:

https://ShellUrl/redirect.aspx?target=SHAREDAPPDETAILS&targetqs=sappid%3dguid%26extrecordid%3dguid

targetqs parameter

Value

appid

Application identifier

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.

SHARERECORD

Provides an interface for the user to share a record with another HealthVault user. Only custodians can share records with other users.

The application uses the extrecordid parameter to indicate which record to share.

Ff803620.alert_note(en-us,MSDN.10).gif Note

The data types to be shared are pre-selected based on application authorization rules of specified AppId. It includes both online and offline authorization rules.

An example request URL:

https://ShellUrl/redirect.aspx?target=SHARERECORD&targetqs=appid%3dguid%26extrecordid%3dguid

targetqs parameter

Value

Notes

appid

Application identifier

extrecordid (optional)

Record identifier

Default record will be used when extrecordid is not present in the URL.

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. See Return application targets.

VIEWITEMS

Allows a HealthVault user to view all of the items of a specified data type in their record.

An example request URL:

https://ShellUrl/redirect.aspx?target=VIEWITEMS&targetqs=appid%3dguid%26typeid%3dguid%26additem%3dtrue%26extrecordid%3dguid

targetqs parameter

Value

Notes

appid

Application identifier

typeid

Thing type identifiers

Comma-delimited list of thing type IDs.

additem

True or False

Default is False. If this value is True, the Add Item dialog box for the data type is displayed.

extrecordid

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.

If an application collects the user's demographic information before the user signs up for a HealthVault account, the application can send the demographic information to the Shell. The Shell uses the information to create the new HealthVault account or record, simplifying the sign up and record creation processes.

The application can send user information in POST data. The parameters to the redirect target (the targetqs parameter) are the same as a GET request.

Users will be redirected to the account sign up page for a new account. At that point, if the user signs in to existing account, the profile data from the application will be ignored and the user will proceed to application authorization.

These Shell redirect targets support POST data:

  • CREATEACCOUNT

  • CREATERECORD

The application should validate the user information before sending it to the Shell. For example, ensure that the data uses the correct date format for birthdate. If the Shell detects an error, it will display a field validation error message to the user.

Item

POST parameter name

Requirements and validation rules

Requested action

CreateAccountAndRecord

True or False. Set to True if you are using with CreateAccount target.

Requested action

CreateRecord

True or False. Set to True if you are using with CreateRecord target.

If CreateRecord=True, don't post account data, as it won't be used even if the user needs to create an account.

Account first name

Account.FirstName

Required when CreateAccountAndRecord=True.

1 – 50 printable characters, including Unicode characters.

White space is allowed. The less-than sign (<) and the greater-than sign (>) characters are not allowed.

Account last name

Account.LastName

Required when CreateAccountAndRecord=True.

1 – 50 printable characters, including Unicode characters.

White space is allowed. The less-than sign (<) and the greater-than sign (>) characters are not allowed.

Account date of birth

Account.BirthDate

Required. ISO 8601 date format (yyyy-MM-dd).

Account postal code

Account.PostalCode

Required when CreateAccountAndRecord=True.

Account e-mail address

Account.Email

Required when CreateAccountAndRecord=True.

Regular expression is defined by HealthVault Platform:

^([\w-+\.]+)@((\[[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}\.)|(([\w-]+\.)+))([a-zA-Z]{2,8}|[0-9]{1,3})(\]?)$

Account country

Account.CountryCode

Required when CreateAccountAndRecord=True.

ISO country/region code (2 characters) from ISO 3166 vocabulary.

Account locale

Account.LanguageCode

Required when CreateAccountAndRecord=True.

First part of Windows locale ID (for example, "en" of en-US).

Language code defined by ISO 639. If specified one is not supported by HealthVault platform, it will fall back to default language for that deployment.

Account gender

Account.Gender

Required when CreateAccountAndRecord=True.

F, M, or UNSP ("UNSP" means unspecified) (vocab code from wc.gender)

Account state

Account.StateCode

Optional for US. 2-character code from wc.states.

Required for Canada when CreateAccountAndRecord=True. 2-character code from wc.provinces.

Required for UK when CreateAccountAndRecord=True. 2-character code from wc.constituentcountries.

Record relationship

Record.Relationship

Required. Code from vocabulary wc.relationship-types.

Record first name

Record.FirstName

Required.

1 – 50 printable characters, including Unicode characters.

White space is allowed. The less-than sign (<) and the greater-than sign (>) characters are not allowed.

Record middle name

Record.MiddleName

Optional.

1 – 50 printable characters, including Unicode characters.

White space is allowed. The less-than sign (<) and the greater-than sign (>) characters are not allowed.

Record last name

Record.LastName

Required.

1 – 50 printable characters, including Unicode characters.

White space is allowed. The less-than sign (<) and the greater-than sign (>) characters are not allowed.

Record street address

Record.StreetAddress1

Optional.

1 – 100 printable characters, including Unicode characters.

White space is allowed.

Record street address 2

Record.StreetAddress2

Optional.

1 – 100 printable characters, including Unicode characters.

White space is allowed.

Record city

Record.City

Optional.

1 – 100 printable characters, including Unicode characters.

White space is allowed.

Record state

Record.StateCode

Optional for US. 2-character code for US from vocab wc.states

Required for Canada. 2-character code from vocab wc.provinces

Required for UK. 2-character code from vocab wc.constituentcountries

Record postal code

Record.PostalCode

Required.

Record country/region

Record.CountryCode

Required. ISO country/region code (2 characters) from ISO 3166 vocabulary.

Record email address

Record.Email

Optional.

Regular expression is defined by HealthVault Platform.

^([\w-+\.]+)@((\[[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}\.)|(([\w-]+\.)+))([a-zA-Z]{2,8}|[0-9]{1,3})(\]?)$

Record phone number

Record.PhoneNumber

Optional.

Record birth date

Record.BirthDate

Required. ISO 8601 date format (yyyy-MM-dd).

Record gender

Record.Gender

Required. F, M, or UNSP (vocab code from wc.gender).

Record ethnicity

Record.EthnicityCode

Optional. Code from vocabulary wc.ethnicity-types.

Record language

Record.LanguageCode

Optional. Code from vocabulary ISO 639.

Applications must be sure to handle actions appropriately. Properly supporting these targets is a key to providing a trustworthy experience for HealthVault application users.

APPAUTHINVALIDRECORD

Returned when the Shell finds an invalid record id in the extrecordid parameter.

APPAUTHREJECT

Returned when the user canceled an application auth request.

If this return is the result of the .NET SDK HealthServicePage..::..RedirectToLogOn or WebApplicationUtilities..::..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.

In addition, TargetDetails are also appended to the return target; either CREATEACCOUNTSUCCESS or CREATEACCOUNTFAILURE.

For instance in case of the CreateAccount target, the Shell can redirect to the app with CREATEACCOUNTSUCCESS in the TargetDetails parameter as part of APPAUTHREJECT upon successful account creation but failure in to authorize the application to access the record.

APPAUTHSUCCESS

Returned when the user has successfully logged on and/or granted application authorization.

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.

In addition, TargetDetails are also appended to the return target; either CREATEACCOUNTSUCCESS or CREATEACCOUNTFAILURE.

EDITRECORDCOMPLETE

Returned when the user clicks "Save" on the Edit Record page.

EDITRECORDCANCEL

Returned when the user clicks "Cancel" on the Edit Record page.

RECONCILECANCELED

Returned when the user canceled the reconcile process for a CCR or CCD.

RECONCILECOMPLETE

Returned when the CCR/CCD reconcile transaction completes successfully.

RECONCILEFAILURE

Returned when the CCR/CCD reconcile transaction fails.

SELECTEDRECORDCHANGED

Returned 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 the HealthServicePage..::..RefreshAndPersist method to accomplish this refresh.

SHARERECORDFAILED

Returned when a record sharing invitation could not be sent.

SHARERECORDSUCCESS

Returned when a record sharing invitation was sent successfully.

SIGNOUT

Returned from an APPSIGNOUT request to the Shell.

Show:
© 2014 Microsoft