Launching Accelerator with Web Application API

accelerator launch process provider vendor systems launch the accelerator using the following steps provider vendor system sends an auth token request through a single vendor aggregation server the request includes the system user id, system user qualifier, end user id, and roles please note that the user’s roles are papreparer, pareviewer and pasubmitter see roles https //docs surescripts com/epa accelerator/guide/launching accelerator with web application api#roles for more information the user could be the prescriber or someone working on behalf of the prescriber surescripts returns a response that includes the token the provider vendor system launches the accelerator using the token the launch includes styling parameters as well as launch options see accelerator launch options https //docs surescripts com/epa accelerator/guide/launching accelerator with web application api#accelerator launch options for more information on worklists and task history the provider vendor system closes the session user security the provider vendor is responsible for authenticating users and determining what data and activities each user will have access to this is done by specifying the end user id and permissions in the auth token request in response, the accelerator generates a token that specifies the user's access information and activities based on the permissions specified in the auth token request at a high level, the provider vendor and the accelerator share responsibilities for maintaining and enforcing user authentication and access controls for product functions responsibilities are described below the provider vendor maintains its users, their roles, their relationships (e g , delegation of authority from providers to staff), and their authentication credentials, etc includes pertinent user information when initiating the accelerator's user interface and task list components, including the end user id (as defined by the provider vendor system) the provider vendor must ensure the end user id is unique across their customer base the end user id is viewable on the user interface an assertion that the user has been authenticated by the provider vendor system the specific roles the user possesses the providers on whose behalf the user can act the accelerator logs the end user id (as defined by the provider vendor system) and activity enforces the user’s role(s) assigned by the provider vendor system enforces visibility of data according to the delegation information supplied by the provider vendor system authentication and authorization users are authenticated by the provider vendor system the accelerator tracks the end user id of the individual signed into the provider vendor system the provider vendor system authorizes a user to perform a task by assigning them to a role the types of roles are pa reviewer the pa reviewer has read only permissions pa preparer the pa preparer has create, read, and edit permissions pa submitter the pa submitter has create, read, edit, and submit permissions the user may have different roles depending on their relationship to the prescriber (e g , a user may have the pa submitter role when working on behalf of dr smith and the pa reviewer role when working on behalf of dr jones) the users and their roles are not stored by surescripts the provider vendor system must securely communicate the authenticated end user id and roles to surescripts the table below shows the role(s) authorized to perform each task role/permission map activity description/notes pareviewer papreparer pasubmitter view worklist view and select tasks that require action note tasks may also be filtered by the provider or patient included in the auth token x x x view response details read only access to all response data including answers to questions for an open response x x x prepare open response answer questions on open response x x submit parequest take the answers created from ‘prepare open response’ and submit the parequest message to pbm/payer x acknowledge closed ends the workflow process for the associated epa case x x acknowledge denial ends the workflow process for the associated epa case x x acknowledge approval user indicates agreement with approval restrictions (if any) ends the workflow process for the associated epa case x x create appeal add information required to submit initial paappealrequest and submit x x submit appeal take the answers created from ‘prepare open response’ and submit the paappealrequest message to pbm/payer x x cancel process submit pacancelrequest request to the pbm/payer x x acknowledge cancel ends the workflow process for the associated pa case x x auth token request the web service api provides an endpoint for requesting an auth token that is used when launching the accelerator the auth token identifies user and their role(s), and must be used when the accelerator is launched the token may be re used for multiple launches until it expires the request type is "post", the content type must be set to "application/json", and the request parameters are json encoded as part of the request body the token follows the jwt pattern and requires that the roles for a particular session be included in the request the json fields in the following example are defined per the table below json fields notes systemuserid the data provider id (identification of the sender of the message) use the network participant id provided in your surescripts activation form (for example, abc123) systemuserqualifier the user qualifier assigned to the provider vendor system the systemuserqualifier = "dp" enduserid id of the user logged into the provider vendor system note this value is presented to authorized viewers in task history details for epa processes provider vendors should use appropriate values to assist in tracking and troubleshooting tasks and processes enduserid must be less than 250 characters and unique across provider vendor customers roles a list of roles assigned to this provider note when common roles are included in the request, roles assigned for providers will be ignored and should not be sent products required if customer needs a specific product if not sent, all products will be returned example epa id product id at least one product id is required if ‘products’ is used value epa processtypes required if process types filter is needed note process types are not currently used for electronic prior authorization value null auth token request example post https //\[host]/uiservice/api/v0/authtoken http/1 1 host localhost connection keep alive content length 85 user agent mozilla/5 0 (windows nt 6 1; wow64) applewebkit/537 36 authorization basic zgvtb0jhc2ljqxv0aelkomrlbw9cyxnpy0f1dghqdw== content type application/json accept / accept encoding gzip,deflate,sdch accept language en us,en;q=0 8 body { "systemuserid" "epa123", "systemuserqualifier" "dp", "enduserid" "fred", "roles" { "commonroles" \[ "pasubmitter" ], "providers" \[ { "id" "6487851746001", "qualifier" "d" { ] } } note the basic authentication credentials are detailed in your surescripts activation form the body of the request utilizes the application/json format as detailed in the table above roles a list of roles is required in order to generate an auth token the provider vendor system assigns a role to the user, which authorizes them to perform certain tasks within the accelerator the provider vendor system requests an auth token, which specifies role requests for each launch of the accelerator ui the accelerator encodes the requested roles into the auth token see authentication and authorization https //docs surescripts com/epa accelerator/guide/launching accelerator with web application api#authentication and authorization for role(s) authorized to perform specific tasks roles can be specified per the following a common role can be specified across all providers assigned to that user roles can be specified on a role per provider basis or on a list of providers basis the list of providers the user can access is managed by the provider vendor system roles can be specified on a per patient basis or on a list of patients basis the list of patients is managed by the provider vendor system if an attempt to create an auth token violates one of the following rules, the accelerator will return a validation error the rules include if a role is not specified at any level (common, provider, or patient) if a provider is specified more than once if a patient is specified more than once roles definitions roles notes common roles a list of roles that apply to all submitted providers or patients when common roles are included in the request, roles assigned for providers and patient will be ignored and should not be sent providers a list of provider objects, each with a list of roles for that provider, an id, and a qualifier patient an object that describes a patient with an id, an organization, and a list of roles that apply role assignment examples the json field in the following examples is defined per the table below json fields notes roles a list of roles assigned to this provider note when common roles are included in the request, roles assigned for providers will be ignored and should not be sent common role assignment the following example shows how a single role can be assigned for all providers assigned to that user as part of an auth token request in addition to the table at the beginning of this section, the table below details additional json fields specific to this example json fields notes commonroles in this example the common role is the pasubmitter id the provider’s spi qualifier the qualifier for the provider qualifier d common role assignment example { "systemuserid" "epa123", "systemuserqualifier" "dp", "enduserid" "user1", "roles" { "commonroles" \[ "pasubmitter" ], "providers" \[ { "id" ""\<providerspi1>", "qualifier" "d" }, { "id" ""\<providerspi2>", "qualifier" "d" } ] } } role per provider assignment the following example shows how roles can be assigned on a per provider basis in addition to the table at the beginning of this section, the table below details additional json fields specific to this example json fields notes id the provider’s spi qualifier the qualifier for the provider qualifier d role per provider assignment example { "systemuserid" "epa123", "systemuserqualifier" "dp", "enduserid" "user1", "roles" { "providers" \[ { "roles" \[ pasubmitter ], "id" "\<providerspi1>", "qualifier" "d" }, { "roles" \[ pareviewer ], "id" "\<providerspi2>", "qualifier" "d" } ] } } role per patient assignment the following example shows how a specific role can be assigned for a specific patient in addition to the table at the beginning of this section, the table below details additional json fields specific to this example json fields notes id matches the medicalrecordidentificationnumberehr field ( patient/identification/medicalrecordidentificationnumberehr) specified in the painitiationrequest this field is optional in the schema, but has to be included in the original painitiationrequest in order for the resulting process to be visible when launching the accelerator for a specific patient organization the value sent in the mutuallydefined field ( patient/identification/mutuallydefined) of the painitiationrequest used to identify a patient with the same id across different locations/facilities note if this optional field is not included in the painitiationrequest, it should not be included in auth token request for the specified patient the worklist items will show when patient id equals medicalrecordidentificationnumberehr and organization equals mutuallydefined for example, if organization is null in the auth token request but mutuallydefined is “test clinic” in the painitiationrequest, the task for that patient will not be displayed id and organization must both match what is on the painitiationrequest role per patient assignment example { "systemuserid" "epa123", "systemuserqualifier" "dp", "enduserid" "fred", "roles" { "patient" { "id" "elizabeth", "organization" "clinic2", "roles" \[ "pasubmitter" ] } } } auth token response the accelerator returns the auth token response in the "application/json" format and may include a success or error message if the response is successful, the payload of the response will contain an encrypted auth token, which is used to further access the accelerator auth token response examples successful response example http/1 1 200 ok cache control no cache pragma no cache content type application/json; charset=utf 8 expires 1 date thu, 06 mar 2014 16 42 17 gmt content length 547 { "token" "eyj0exaioijkv1qilcjhbgcioijiuzi1nij9 eyjpc3mioijzzwxmiiwiyxvkijoiahr0cdov l3d3dy5zdxjlc2nyaxb0cy5jb20ilcjuymyioje0mdcxodaynzmsimv4cci6mtqwnzixnji3my wibmftzwlkijoibwlszxmilcjyb2xlijoie1wiq29tbw9uum9szxncijpbxcjwyxn1ym1pdhrl clwixsxcilbyb3zpzgvyc1wiolt7xcjsb2xlc1wiom51bgwsxcjjzfwiolwinjq4nzg1mtc0nj awmvwilfwit3jnyw5pemf0aw9uxci6bnvsbcxcilf1ywxpzmllclwiolwirfwifv0sxcjqyxrp zw50xci6bnvsbcxcik9yz2fuaxphdglvblwiom51bgx9iiwic3vyzxnjcmlwdhmuy29tl3bvcn rhbci6ijexndyifq kkt1eesjedbaxjkercusglxxtz7fge8bjwtb8w3ia7e", "utcexpiration" "2014 08 05t05 24 33 9298548z" } error response example http/1 1 400 bad request cache control no cache pragma no cache content type application/json; charset=utf 8 expires 1 date mon, 04 aug 2014 19 28 02 gmt content length 148 { "message" "the request was invalid ", "modelstate" { "" \[ "one or more invalid common role has been specified " ] } } accelerator launch overview if the hosting application is web based, the accelerator is embedded in an iframe for non web based vendor applications, the accelerator may be embedded in web browser controls that meet the minimum browser requirements embedding the web application in an iframe launch the accelerator user interface by posting a form that targets an embedded iframe the following is an example and is for illustration only \<form action="https //\[host name]/uiservice/app/v0/launch/#/worklist" method="post" target="worklist" id="worklistformid"> \<input type="hidden" name="authtoken" value="\[auth token]" /> \<input type="hidden" name="appprimarycolor" value="#0099ff" /> \<input type="submit" value="work list" /> \</form> \<iframe name="worklist" id="worklist" style="overflow y\ hidden;width 810px;height 410px">worklist\</iframe> parameters parameter description \[host name] the address of the accelerator server being used refer to your surescripts activation form and the url used to launch accelerator the route following the hostname specifies which view the accelerator will initially display (in the case above, the worklist) \[auth token] the “token” retrieved from the auth token web service styling parameters – e g , appprimarycolor in the example above see styling https //docs surescripts com/epa accelerator/guide/launching accelerator with web application api#styling below for available options styling for more information about color and font styling, refer to the associated accelerator user documentation for your product launch the iframe (or a web browser control) with a css similar to the following iframe { overflow y hidden;width 810px;height 410px; scrolling no; border 0;} the following are the styles that can be set with their default values from parameters on the initial post appfontfamily "helvetica neue", helvetica, arial, sans serif appfontsize 13px appfontcolor #333333 appborderradius 4px appbackgroundcolor #ffffff appprimarycolor #3484d6 appwarningcolor #d66934 appsuccesscolor #4fd634 appnavbar “normal” navigation bar style parameter the navigation bar style parameter is named appnavbar the default is “normal” which is set to 50px value result none navigation bar is not displayed large 70px normal 50px small 30px example – turning the navigation bar off \<input type="hidden" name="appnavbar" value="none" /> styling example post https //\<host>/uiservice/app/v0/launch/#/worklist http/1 1 body appprimarycolor=%23ff0000 \&authtoken=eyjwz connection keep alive content length 419 cache control max age=0 accept text/html,application/xhtml+xml,application/xml;q=0 9,image/webp, / ;q=0 8 origin https //sur6104 surescripts local user agent mozilla/5 0 (windows nt 6 1; wow64) applewebkit/537 36 (khtml, like gecko) chrome/33 0 1750 146 safari/537 36 content type application/x www form urlencoded accept encoding gzip,deflate,sdch accept language en us,en;q=0 8 accelerator launch options post /uiservice/app/v0/launch/#/worklist the worklist contains the user’s actionable tasks the user may select a task and trigger the accelerator to go to the appropriate view for that task tasks related to epa are assigned to the recipient of the epa message, e g the spi of the provider sent in the painitiationrequest the user viewing and working on a task does not have to be a prescriber, but the user must have the permissions for the task as described in authentication and authorization https //docs surescripts com/epa accelerator/guide/launching accelerator with web application api#authentication and authorization post /uiservice/app/v0/launch/#/process when posting ‘process’, this is the task history and shows the status of the epa and its associated tasks this endpoint launches a view showing a list of workflow processes matching the search filter criteria the user may drill down into each process to see the state of all associated tasks post /uiservice/app/v0/launch/#/process/\[initiatorsprocessid] when sending an initiatorsprocessid, ensure that the id equates to the pareferenceid in the painitiationrequest this value is assigned by the provider vendor system and is associated with all subsequent messages this endpoint launches a view that shows the state of the workflow process including the status of the process and context specific details post /uiservice/app/v0/launch/#/worklist/\[taskid] the taskid is a surescripts defined value that is assigned to a specific step within an epa process a new taskid is generated when the status of a task is updated or a new task type (represented by taskname) is created within an epa process this endpoint will launch a user to the task specific view within the process if a task’s most recent status is ‘complete’, the user should not be allowed to launch to that specific taskid, as launching to a completed task will result in an error notes launching by taskid should only be done when the status of a task is awaiting action from the user who initiated the pa (or their proxy) tasknames that may require action on part of the prescriber (or their proxy) include “complete pa form” and “acknowledge” tasks (for example, “acknowledge closed pa”) the task status is relative to the user (i e , a prescriber) to obtain taskid for purposes of launching accelerator by taskid, use “retrieve process detail” api endpoints see retrieve process detail https //docs surescripts com/epa accelerator/guide/using accelerator web service api#retrieve process detail for more details accelerator configuration parameter in addition to the basic styling and launch options currently available for accelerator customers, surescripts offers additional epa specific configuration settings that may be enabled at a global level (applicable for all customers of the accelerator enabled provider vendor) please work with a surescripts resource for additional details on which settings are available, how they function in practice, and how to enable them auto acknowledge "pa not needed" responses by default, surescripts automatically acknowledges a painititiationresponse with a reasoncode of “cc” (pa not required for patient and/or medication) please note that the auto acknowledge option is enabled by default and can be turned off by a surescripts resource these responses would still be available for review via the task history page, or via the data that is returned from accelerator api requests, but would no longer appear on a user’s worklist for acknowledgment provider vendors should ensure that they are communicating this process clearly to their end users to prevent confusion for tasks that may appear to never receive a response if the provider vendor is holding prescriptions from being sent to the pharmacy, and ‘auto acknowledge’ is enabled, they should make sure that those prescriptions are being released to the pharmacy after they have been acknowledged it should also be made clear to the end user that the prescription was released, and no further action is required on their part