Successfully reported this slideshow.
We use your LinkedIn profile and activity data to personalize ads and to show you more relevant ads. You can change your ad preferences anytime.

Health Information Flows Technical Standards - V 0.5

We are publishing a draft of the technical standards of the Personal Health Records (PHR) component of the National Health Stack (NHS)!

As a refresher, these standards govern the consented sharing of health information between Health Information Providers (HIPs) - like hospitals, pathology labs, and clinics - and Health Information Users (HIUs) like pharmacies, medical consultants, doctors, and so on. The user’s consent to share their health data is issued via a new entity called a Health Data Consent Manager (HDCM).

The problem today is that the electronic health records listed in one app or ecosystem are not easily portable to other systems. There is no common standard that can be used to discover, share, and authenticate data between different networks or ecosystems. This means that the electronic medical records generated by users end up being confined to many different isolated silos, which can result in frustrating and complex experiences for patients wishing to manage data lying across different providers.

With the PHR system, a user is able to generate a longitudinal view of their health data across providers. The interoperability and security of the PHR architecture allows users to securely discover, share, and manage their health data in a safe, convenient, and universally acceptable manner. For instance, a user could use a HDCM to discover their account at one hospital or diagnostic lab, and then select certain electronic reports to share with a doctor from another hospital or clinic. The flow of data would be safe, and the user would have granular control over who can access their data and for how long. Here is a small demo of the PHR system in action.

The standards in the draft released today offers a high-level description of the architecture and flows that make this possible.

Related Books

Free with a 30 day trial from Scribd

See all

Related Audiobooks

Free with a 30 day trial from Scribd

See all
  • Be the first to comment

Health Information Flows Technical Standards - V 0.5

  1. 1. Health Information Flows Technical Standards Sequence #: Version:​ 0.5 Author: ​iSPIRT Track: ​Standard Maturity Level:​ Draft Type:​ Technical Specifications Status:​ Draft Jul 4, 2020 Abstract​: This document presents the architecture for consented sharing of Health Information between Health Information Providers and Health Information Users via a new type of entity called Health Data Consent Managers (CMs)​. It describes the architecture at a high level and outlines the flows that are covered by the architecture. The current version is focused on ​personal health information flows ​which involve exchange of individual health data only and to the creation of ​personal health records (PHRs)​.
  2. 2. Version History Version Date Comments 0.5 04/07/2020 Preliminary Draft
  3. 3. Table of Contents Table of Contents 3 1 Introduction 5 1.1 Guiding Principles of our Architecture 6 2 High-level architecture 7 2.1 Terms and Definitions 7 2.2 Architecture 9 2.3 Roles of different entities 11 2.4 User Interactions 13 2.4.1 User interactions with HIPs and HIUs 13 2.4.2 Registration with CMs 15 2.4.2.1 Structure of a PHR ID 15 2.4.2.2 Multiplicity of PHR IDs 15 2.4.2.2 PHR ID retrieval and lookup 16 2.4.3 Discovery and Linking 16 2.4.3.1 CM-initiated discovery and linking 16 2.4.3.2 HIP-initiated linking 17 2.4.4 Consent 17 2.5 Health information (HI) types 17 3 APIs and Flows 18 3.1 Registries and related functionalities 18 3.1.1 Onboarding HIPs and HIUs using registries 18 3.1.2 Onboarding CMs and health repositories 19 3.1.2.1 CM registration 19 3.1.2.1 Repository registration 20 3.1.3 Gateway peering 21 3.1.4 Profile updation of different entities 21 3.2 APIs 21 3.2.1 gateway APIs 22 3.2.1.1 registry APIs 22 3.2.1.2 gateway-cm APIs 22 3.2.1.3 gateway-repository APIs 24 3.2.1.4 monitoring APIs 26 3.2.2 repository APIs 26 3.2.2.1 HIP-targeted APIs 26
  4. 4. 3.2.2.2 HIU-targeted APIs 27 3.2.3 cm APIs 27 3.3 Flows 29 In presenting the various flows, we use the following conventions: 29 3.3.1 PHR ID retrieval and lookup 29 3.3.2 Discovery flow 31 3.3.3 CM-initiated linking flow 31 3.3.4 HIP-initiated linking flow 32 3.3.5 Consent flow 33 3.3.5.1 Consent request from an HIU to a CM 33 3.3.5.2 Consent notification from a CM to an HIU 34 3.3.5.3 Fetching a consent artefact from a CM 35 3.3.5.4 Consent notification from a CM to an HIP 36 3.3.6 Data flow 37 4 Non-functional Requirements 38
  5. 5. 1 Introduction A ​Health Information Flow ​(HIF)​ ​is a mechanism of transferring digital health information about users from one organizational entity to another. An entity that generates or collects health information about users and stores it in digital form is referred to as a ​Health Information Provider​ (HIP). HIPs could be hospitals, diagnostic labs, pharmacies or other organizations which run software systems to collect, process and store health information of individuals. An entity that seeks health information about users from HIPs is referred to as a ​Health Information User​ (HIU). HIUs could be hospitals, insurers, medical research companies and a host of other organizations who are interested in processing health-related information gathered from different sources. A health information flow is a mechanism of moving health information from an HIP to an HIU. Some health information flows involve the transfer of ​personal ​information i.e. information which contains personally identifiable information of users or can easily be linked to a single user. We refer to such flows as ​personal health information flows (personal HIFs). ​When an HIU aggregates information about a single user from multiple different HIPs using personal HIFs, it leads to the creation of a ​personal health record (PHR)​ ​of the user: a dynamically-generated collection of digital health documents about the user sourced from multiple HIPs. A doctor seeking to treat a patient may ask for health information of that user generated at different diagnostic labs or hospitals in the past and as such, needs access to a PHR of the user. Many applications require processing aggregate health information about their users and as such, have the need to access the PHR of their users. HIFs may involve transfer of information that is not personally-identifiable as well. Such information may be non-personal by its very nature (e.g., profile details of a hospital that collects health information of users) or that has been made non-personal by applying anonymization techniques on personal health information. Such HIFs are referred to as ​non-personal HIFs​. This document outlines a technical architecture for implementing HIFs at national scale, keeping in mind evolving laws around personal data and data privacy and evolving technology frameworks for sharing and gathering data across multiple software systems. Although our architecture has been developed in India as part of the National Health Stack initiative, the design is general enough to be applicable anywhere in the world. We outline the different components and flows in our architecture and lay down the technical standard to be used by health IT systems to participate in a real-world implementation of the architecture. The document is mainly focused on personal HIFs although our architecture and approach can also be applied to non-personal HIFs. Project EKA is a community initiative that is creating an open-source implementation of different components of our architecture and reference solutions. Project EKA also hosts detailed API specifications for the APIs that are defined in our technical standard. More information about project EKA is here: ​https://projecteka.github.io/
  6. 6. 1.1 Guiding Principles of our Architecture Before we describe our architecture, we present the core guiding principles upon which the architecture is based. 1.​ ​Diversity:​ We aim to design a framework that will enable ecosystem innovation around health information flows, rather than provide a point solution for health information sharing. Our design should allow a diverse set of existing or new health IT systems, with diverse definitions of and approaches to manage health information, to participate in HIFs and to do this with ease. 2.​ ​Evolvability: ​We want our design to be simple and easily evolvable: it should be possible for capabilities to be built incrementally while allowing for rapid adoption in today’s world. It should also be possible to monitor systems at scale, so that policy corrections can be suitably informed. The design should be adaptable to future policies around health data and future technology frameworks for data exchange. 3.​ ​Privacy By Design​: ​User information needs to be protected from abuse and compromise and privacy must be built into the architecture by design. Storage of and control on user information should be d​ecentralised as far as possible and principles of transparency and choice should be applied in processes surrounding collection and sharing of personal information. In defining new software systems and processes, personal data collection should be kept to the minimum possible levels. 4.​ ​Scalability​: ​Health information flows enabled by our architecture should be able to handle data of billions of users. ​Not only the technology architecture but even the processes around implementing the architecture (registering new entities, maintaining existing ones, conducting audits, handling grievances) should be implementable at the scale of a large country like India. 5.​ ​User Centricity​: ​The design should enable simple and powerful user interfaces to develop around it and address the needs of a diverse set of users, including those who may not be literate, technologically or textually. Users should have significant control on how their information is shared in personal health information flows, in line with evolving laws around data privacy and security. 6. Transparency and Accountability​: We attempt to ensure ​Public Open Data​ is available via APIs. Access to open data will ensure high-quality analytics, accurate fraud detection, shorter cycles for system improvement and high responsiveness to user needs. We also attempt to enable strong data-driven governance practices to be put in place for various actors that the architecture incorporates.
  7. 7. 2 High-level architecture 2.1 Terms and Definitions Health Information Flow (HIF) A health information flow (HIF) refers to any interaction in which digital health data about one or more users is shared by one entity with another entity. This includes both personal health information flows, in which the said data includes personal identifiable information and non-personal health information flows, which includes all other types of information flows, including the release of anonymized data and open data by health information systems. Health Information Provider (HIP) A health information provider (HIP) is an entity that collects or generates digital health information and stores it in a software system. These could be clinical establishments like hospitals, primary or secondary health care centres, nursing homes, diagnostic centres, pharmacies, Government health programs and may also include healthcare technology companies which provide services to healthcare providers or end-users. Health Information User (HIU) A health information user (HIU) is an entity that seeks digital health information from HIPs, in order to provide services to the user. These include hospitals, clinics, healthcare technology companies, organizations working on health analytics, insurers, medical researchers, Government entities. HIUs must also run a software system for accessing and/or storing health information. An important class of an HIU is a company or organization that provides an application to create longitudinal health records of users and to maintain them in a trusted location (e.g., on users’ personal devices or on a user-trusted cloud service). We refer to such an application as a ​personal health locker ​and the corresponding provider as a ​personal health locker provider​. Personal Health Record (PHR) A personal health record of a user is any collection of health documents or files pertaining to that user (i.e. with personally identifiable information linked to that user), which is generated and stored at multiple HIPs. An HIU can create a PHR of a user by aggregating personal health information about that user via personal HIFs applied to multiple HIPs. Thus, a personal health record of a user is a ​dynamically-defined concept​: it may include all or some of the full set of health records of a user stored in HIP systems and it is created in real time based on requests generated by an HIU. A PHR may have meta-information attached to it which enables the consuming entity (the HIU) to view the contents of the PHR in a human-readable manner. Consent Manager (CM) A consent manager is an entity that acts as a consent collector for the user and mediates personal HIFs from HIPs to HIUs. Our architecture allows multiple
  8. 8. entities to play the role of a CM and each must have its own front-end (a mobile app, a Web app, or a human agent who interfaces with a mobile/Web app) for interacting with users. A CM cannot access health information of users, even in encrypted form, unless it is also an HIU and accesses information in that capacity. Its role is primarily to enable consent collection, based on which data is shared from HIPs to HIUs. It also enables HIUs to discover the different sources (HIPs and their software systems) from which user information can be shared. Consent managers are a key mechanism for ensuring ​privacy by design in our architecture. Consent Artefact A consent artefact is a machine-readable digital file that specifies the parameters of data sharing that a user consents to in a personal HIF. These parameters include the names of the entities involved in data sharing (HIP, HIU), the duration of consent, the type of data access that is permitted, the purpose of data sharing and others. Consent artefacts are generated by consent managers (CMs) and shared with HIUs and HIPs once consent collection is complete. Each consent artefact contains a digital signature which ensures that the consent parameters cannot be modified by HIUs or HIPs and thus addresses the threats of over-sharing of data and changes in access permissions by any of these entities. The notion of a consent artefact is developed in a ​technical standard​ released by the ​Ministry of Electronics and Information Technology (MEITY)​. In the current standard, we use consent artefacts that are digitally signed by the consent collector, which is the consent manager in our architecture. Consent artefacts also form a key ​privacy by design ​feature of our architecture. User The term “user” refers to any individual who is availing the services of an HIP or an HIU. Users maintain health records with HIPs in which their digital health information is stored. Users must register with CMs in order to be able to give consent to HIUs and enable personal HIFs to occur. This registration process also results in creation of a user account at the CM and an ID referred to as the user’s ​PHR ID​. Gateway A gateway is a cloud-hosted software system that enables HIPs, HIUs, and CMs to connect with each other and exchange information. Gateways ensure interoperability between software systems run by these entities and, in particular, enable any HIU, any HIP, and any CM (whose software systems implement the standardized APIs defined in this document) to communicate with any other entity in the ecosystem ​without the need of unilateral contracts with each other​. Gateways are thus the key mechanism for ensuring ​scalability of our architecture. We also envision gateways to play the role of enrolling, monitoring and auditing different entities in the HIF ecosystem in a semi-automated manner; thus, they are also a key vehicle for our design principle of ​transparency and accountability​. Gateways communicate with each other, which allows HIUs/HIPs/CMs connected in one gateway’s network to interact with those on another’s network.
  9. 9. Gateway Provider A gateway provider is an entity that runs a gateway. Gateway providers are envisaged to be regulated entities and only 1-2 gateway providers may operate at country scale. Gateway providers do not directly interface with users. Health Repository (​erstwhile referred to as​ Data Bridge) A health repository is a software system that enables HIPs and HIUs to connect to a gateway and through that, to other HIPs/HIUs and CMs in the HIF ecosystem. These software systems can be built by HIPs/HIUs themselves or by other software service providers. Repositories implement standardized APIs which are essential for communicating with other entities in the ecosystem. They may also provide storage solutions where health information obtained by HIUs/HIPs can be reliably stored. Health Repository Provider (HRP) A health repository provider is an entity that runs a health repository. Each such provider may provide services to one or more HIPs/HIUs on one side and may enable communication with one or more gateways on the other side. 2.2 Architecture The Health Information Flows (HIF) architecture uses a layered approach to health information sharing wherein we decouple the three essential components of the process: 1. The ​discovery of health information​: ​Before HIUs can obtain and aggregate health information about users, they need to be able to discover where the information resides. In our architecture, consent managers enable this discovery process for ​personal​ health information flows. For each user, a CM obtains and maintains meta-information like the names of different HIPs where a user’s health information was created and descriptors of such information like labels given to different health records kept by the HIP. This happens through the execution of a ​“​discovery flow​” ​(in which the meta-information is discovered by the CM) and a ​“​linking flow​” ​(in which authorization is given by the user or the HIP to store the meta-information at the CM). 2. The ​consent for sharing health information​: ​Once the sources and types of a user’s personal health information is known, an HIU needs to obtain consent from the user to be able to fetch that information. In our architecture, CMs enable the process of consent collection as well. We define the notion of a “​consent flow​” in which a consent request is generated by an HIU software system, consent is gathered by a CM application, and post that, a ​consent artefact​ is created and shared with the HIU and HIP. 3. The ​flow of health information: ​Once consent for fetching health information has been obtained, the HIU can fetch health information from the HIP, potentially multiple times, as per the terms in the consent artefact, and form users’ personal health records (PHRs). This is what we refer to as the “​data flow​”. In our architecture, the request for any personal health information from an HIU to an HIP is mediated by the CM but ​the information flows directly from the HIP to the HIU​, without any involvement of the CM.
  10. 10. The following diagram shows the various components of our architecture and their interactions in the health information flow ecosystem. Figure 1: The HIF architecture The diagram depicts one possible configuration in which the different components may be arranged. There is a single gateway in this depiction and four health repositories, two that interface with a set of HIPs (on the left), and two others that interface with a set of HIUs (on the right). Each hospital/lab information management system is a software system that is used by multiple physical hospitals/labs. “Aggregator software” refers to any kind of software system which serves multiple different clinical establishments like labs and clinics and enables services like patient management, EMR, e-prescriptions. While health repositories are shown as being distinct from the HIP/HIU software systems, they could be different modules in the same software system. The diagram shows two consent managers that interface with users via their respective user interfaces. In practice, there could be several consent managers, which will allow for different user segments to be
  11. 11. served differently. For example, beneficiaries of Government programs like PM-JAY could be served by a CM which enables illiterate or semi-literate users to give consent in an assisted manner, whereas users of higher socio-economic strata may be served by a CM which offers a mobile app for gathering consent directly from users. Even within one user segment, it is valuable to have multiple CMs serving that segment; this increases choice for the users and spurs innovation in the area of consent management. As discussed earlier, users can use personal health lockers for long-term storage of their health information aggregated from different HIPs. One personal health locker is shown in the diagram. Health lockers interface with users one side and with the gateway on the other side. The actual storage solution used by health lockers to store health information may be managed by the locker provider itself or externally-hosted (e.g., a personal health locker may just be a software service that stores health information on users’ smartphones). Some health locker providers may provide both storage and consent management services and thus play the dual role of locker provider as well as consent manager. Important: ​An entity that plays the role of HIU in one health information flow may play the role of HIP in another health information flow. Depending upon the consent given by a user, an HIU can aggregate health information about the user ​and store that information in its own systems ​(for a period of time specified in the consent artefact). This enables the HIU to serve as an information provider to other HIUs seeking that information and hence become an HIP to such HIUs. Indeed, for an ecosystem to develop around our architecture, it is valuable for the following principle to be enforced: Principle of Reciprocity: ​Every HIU that aggregates personal health information of users from other entities and stores that information (without violating user consent) must serve as an HIP to other HIUs who seek that information. The enforcement contours of this principle will be determined by accompanying privacy laws and is beyond the scope of the architecture document. It is particularly valuable for personal health locker providers to play the role of HIPs to other HIUs. Health lockers provide a long-term storage solution for health information of users, which even HIP software systems or health repositories may not offer and over time, personal health lockers will likely become a more reliable source of information (for ​personal HIFs​) than these other systems. 2.3 Roles of different entities Below, we summarize the roles played by entities that are unique to the HIF architecture i.e. consent managers, gateway providers and health repository providers. 1. CMs: ​Consent managers are neutral, regulated, user-facing utilities whose primary role is to collect consent from users for sharing personal health information from HIPs to HIUs. Other than enabling consent collection and providing the desired user interface for it, CMs play a few other crucial roles in our architecture which are listed below. ● Discovery of health information​: CMs help HIUs discover users’ health information and
  12. 12. they maintain meta-information about such information like the names of the HIPs which have created health records for a user and labels given to such records. This meta-information assists HIUs in determining what information to seek from HIPs. ● Consent lifecycle management: ​CMs manage the lifecycle of consent artefacts, including activities like revocation and pausing of consent. ● Consent-related notifications: ​CMs notify users, HIUs and HIPs about key consent-related events like consent revocation. CMs also receive notifications from HIU / HIP systems about events in the data flow e.g., notifications indicating transmission or receipt of data, and maintain a record of such events for the benefit of the user. By design, CMs never get access to shared health information, whether encrypted or raw. This ensures that entities who play the role of a CM are not incentivized by a need to aggregate user information and instead, are motivated to provide safe and reliable consent management services to the user. Overall, CMs are one of our main mechanisms for ensuring ​user centricity of our architecture. 2. Gateway providers:​ Gateways form the hub of information exchange in the HIF ecosystem. The role of a gateway includes all of the following: ● Routing: ​The gateway is responsible for routing all communication between a CM’s software system and a health repository and that between two health repositories, except for the transfer of health information during the data flow. In other words, gateways route ​all control communication​ ​across CMs, HIUs and HIPs - information that is shared during the discovery, linking and consent flows. The transfer of health information from an HIP to an HIU happens directly from a repository linked with the HIP to a repository linked with the HIU, and does not involve the gateway, as shown in Figure 1. This design choice is made with the consideration for scalability, and, in particular, considering the large bandwidth requirements for health information. ● Interoperability: ​The gateway implements a set of standardized APIs and can communicate with a CM system or a health repository only if such a system also implements a set of standardized APIs. This enables a many-to-many communication network to be rapidly set up across different entities and also enables evolvability of the communication protocols. ● Registry management: ​Gateway providers maintain a ​registry​ of CMs and health repositories, which stores information like the access URLs for different software services of CMs/repositories and the mapping between HIP/HIU names and their repositories. The registry is critical for routing requests between entities. ● Security: ​Gateways run a token-issuing service which is used to ensure security of all the gateway APIs, and thus of all communication in the network. ● Audit: ​Gateway providers are responsible for auditing health repositories and CM software systems and ensuring their compliance with the HIF technical standards. Gateways are envisaged to be regulated entities and only 1-2 of them are expected to operate
  13. 13. at country scale. 3. Health repository providers:​ Health repository providers are enablers for HIPs and HIUs to participate in health information flows. Their role covers the following: ● API services: ​Health repository providers enable information flows of all types for HIUs/HIPs: personal HIFs (consented data sharing), sharing of non-personal data and open data (unconsented data sharing) and compliance HIFs (unconsented data sharing, needed for audits). They implement standardized APIs that are required to be able to communicate with gateways, whereas their associated HIPs/HIUs may not implement such APIs. ● Data services: ​Repository providers implement middleware software for data standardization and data anonymization which enables HIUs and HIPs to participate in different types of HIFs. They may enable HIFs for open data and non-personal data and they may offer data analytics solutions for HIUs. ● Repository services: ​Health repository providers may provide long-term solutions to HIUs/HIPs. This is particularly useful for small establishments (e.g., rural clinics or hospitals) and enables them to participate in the HIF ecosystem. In general, repository providers ​increase accessibility of healthcare data ​in the HIF ecosystem and are key vehicles for implementing our ​diversity​ ​and ​scalability​ ​design principles​. ​They address the problem of fragmentation in the healthcare space. A few repository providers could potentially enable hundreds of thousands of disparate healthcare providers in the country to come online, manage their storage and become “HIF-enabled”. Health repository providers are not envisaged to be regulated entities, but every such provider must meet strong certification requirements which will include both the functional as well as non-functional requirements (like security and availability). In earlier versions of this specification, we referred to health repositories as data bridges or API bridges. The terminology has changed but the functionality remains the same. 2.4 User Interactions In this section, we highlight how users interact with different entities in our architecture. 2.4.1 User interactions with HIPs and HIUs Every user must have interacted with at least one HIP and at least one HIU before a health information flow for that user can occur. When users interact with HIPs, HIP software systems create two types of information: 1. A​ user profile​, with a ​verifiable ID (or IDs)​: This is created when the user interacts with an HIP
  14. 14. for the first time. It includes demographic information about the user (name, age, gender and possibly, address) and a set of identities (IDs) using which the HIP identifies and authenticates the user. The HIP may generate and assign an ID to a user (e.g., a hospital may assign a patient ID to every new patient) or it may also leverage existing IDs linked to the user like the user’s Aadhaar number, PM-JAY ID or his phone number. Requirement #1: ​At least one of the IDs used in a user profile by any HIP software system must be a ​verifiable ID​, which means that it must be possible for the HIP system to digitally authenticate the user against that ID using a user-selected password, a one-time password (OTP), biometrics or other means of user authentication. It is possible that an HIP uses verifiable IDs that are shared across multiple users as long as it has a mechanism to distinguish between multiple users with the same verifiable ID. Such IDs are referred to as ​shared verifiable IDs​. ​A user’s mobile number is a good example of a shared verifiable ID. When the mobile number is used as an ID, the HIP system could use demographic details (name, age, gender, in particular) to distinguish users with the same mobile number. 2. A​ health record: ​Every transaction with an HIP may lead to the creation of new digital health information which is stored in the HIP’s software system in the form of ​health records. ​We define a health record as any collection of documents (or database entries) containing health information about a user. The mapping from transactions to health records is HIP-determined: a single transaction may generate one or more health records and a single health record may span one or more transactions. Requirement #2: ​The health records of a user created by an HIP system must be searchable given a verifiable ID of the user (if the ID is a unique verifiable ID) or a combination of a verifiable ID and a set of unique attributes of the user (if the ID is a shared verifiable ID). Additionally, HIP systems may attach ​labels​ to each health record for the purpose of record organization and search. Labels should preferably be intelligible by users so as to assist them in recalling the care context in which the associated record was generated. An example of a label is a ​visit ID ​assigned by a diagnostic lab for each visit made by a user to the lab. Another example is a ​case ID ​assigned by a hospital for an episode of treatment provided by the hospital to a patient. HIPs are free to use any policy for assigning labels to health records. Where human-readable labels are not assigned, a transaction ID or a date-stamp could be used as the label for each health record. If an HIP system uses shared verifiable IDs to authenticate users, it is possible that two users with a shared ID can access health records of each other. When such an HIP system participates in the HIF ecosystem, it becomes possible for one user to allow an HIU to access the health record of another user with whom the user shares a verifiable ID. This can be a valuable feature in some scenarios (e.g., to
  15. 15. enable delegated access control) but it also has some obvious risks. The risks should be suitably communicated to users by every HIP which uses shared verifiable IDs in its systems. 2.4.2 Registration with CMs Every user who wishes to enable his personal health information to be shared from HIPs to HIUs must first register with a consent manager of his choice. This registration process involves collection of essential demographic details about the user and a verifiable ID. The CM validates the verifiable ID by having the user authenticate against it once. Once validated, the user creates a User ID to identify himself in future interactions. In the discovery and linking flows, described below, each such User ID is linked with a set of health records created by HIPs and these records then become discoverable by HIUs when given that User ID. Thus, every health record of a user that is shareable via HIFs and can become a part of a PHR of the user must be linked to some User ID created at a CM. We thus refer to this User ID as the ​PHR ID​ of the user. PHR IDs form a critical component of the HIF architecture. 2.4.2.1 Structure of a PHR ID The construct of the PHR ID is similar to that of the UPI ID in the Unified Payments Interface (UPI). In particular, we require that all PHR IDs are of the form phr-id​ ​:=​ <user-id>@<cm-name> where user-id is an alphanumeric string that can contain only alphabets (a-z, A-Z), digits (0-9) or the characters .(dot) and - (hyphen). CM-name is the name attached to the CM that generates the ID; this is the same name maintained in the CM registry of the gateway provider where the CM is registered. PHR IDs can be created either directly by the user or in an assisted manner. CMs may deploy different approaches to register users and to create PHR IDs. This may include partnering with both HIPs and HIUs, who have existing relationships with users. For example, CMs may partner with different diagnostic labs and implement their user registration protocol as part of existing front-desk procedures at the labs: every time a new user undertakes a diagnostic test at a lab (and a health record created for the user in its LIMS system), the user could be given an option to create a PHR ID as well. 2.4.2.2 Multiplicity of PHR IDs A user can have multiple PHR IDs across different CMs and can even create multiple PHR IDs at the same CM. This feature enables users to create a partitioned view of their health information and is in keeping with our ​privacy by design ​guiding principle. As an example, users may choose to link less sensitive health records with one PHR ID and more sensitive ones with another PHR ID, and only allow a limited set of HIUs to access health information linked to the latter ID. Every PHR ID must correspond to a single user, even if the verifiable ID used at the time of ID creation may be shared across users. Thus, each PHR ID is unique to a user and a “user-centric” form of a unique ID (the user can choose an ID that is unique to him). This is distinct from the traditional notion of a unique ID (e.g., Aadhaar), which enables the State, or entities designated by the State, to be able to
  16. 16. uniquely identify the user, and is thus more “State-centric” in design. If we were to require each PHR ID to be linked to a unique ID like Aadhaar (only one PHR ID allowed per unique ID), it would imply linkability of all PHR information to individual users, which is something we wish to avoid. A PHR ID can also be destroyed by the user who created the ID. When a PHR ID is destroyed, users may be given the option to port all information associated with that PHR ID, including the labels of all linked health records, to another PHR ID, which is important for ensuring ​health information portability. While we allow for users to have multiple PHR IDs, we also require that each user is able to link his (active) PHR IDs and enable creation of a longitudinal view of his information ​across all PHR IDs created in his lifetime​, if and when he wants to. This is important to ensure recoverability of all PHR information of a user by the user himself, or by individuals delegated by the user. For this, we have developed the idea of a ​PHR ID linking protocol,​ ​which will be described in a future version of this document. 2.4.2.2 PHR ID retrieval and lookup When users interact with HIPs and HIUs, they may be required to furnish a PHR ID in order to enable health information sharing. In order to aid the user in recalling their PHR IDs, a ​PHR ID retrieval flow must be implemented. The HIP and HIU systems can use this flow to retrieve a user’s PHR ID, based on a verifiable ID and other demographics information furnished by the user. CMs may also allow HIPs and HIUs to check for the existence of a PHR ID using a ​PHR ID lookup flow. 2.4.3 Discovery and Linking As discussed above, health information of users needs to be discovered and linked with a PHR ID before HIUs can access such information from HIPs. This can happen in two ways. 2.4.3.1 CM-initiated discovery and linking In this approach, the discovery and linking process is initiated by the CM, upon user request. There are two parts to the process: 1. A ​discovery flow​, in which a user uses the CM front-end to specify a list of candidate HIPs where his health records exist, along with the verifiable IDs used by those HIPs for the user (and, possibly, user demographics information as well). The CM system sends a request to each of the corresponding HIP systems, searching for all​ ​associated health records of the user. In response, each HIP system returns the labels of the health records discovered for the user against the verifiable IDs that are specified in the request. 2. A ​linking flow​. ​After the discovery flow is over, the user is asked to view the discovered health record labels and to select a subset of the records for linking with his PHR ID. Once the user has selected those records, the CM sends another set of requests to the HIPs, this time asking for the user-specified records to be linked. Each HIP system that receives a linking request must ask for authorization from the user for the linking to take place. This authorization involves authenticating the user against the verifiable ID which was used to discover the health records
  17. 17. earlier. Once authorized, the selected records are linked to the given PHR ID. 2.4.3.2 HIP-initiated linking In this approach, the linking process is initiated by the HIP, again upon user request. Here, the user specifies a PHR ID and a set of health record labels to the HIP and the HIP’s software system sends a linking request to the CM with the given PHR ID and the given set of labels. There is no discovery flow that is required for this type of linking to occur. However, depending upon the policies set by the HIP, user authentication may still be required before the HIP can issue the linking request to the CM. Prior to linking, the HIP system may assist the user in retrieving his PHR ID using the PHR ID retrieval flow. More details on these flows are given in Section 3. 2.4.4 Consent Once a user’s account with a CM has one or more linked HIP records, the stage is set for the user to start giving consent via the CM. In most situations, the consent process is triggered by an HIU software system issuing a consent request to a CM, which results in the CM sending a notification to the user informing him about the request. Subsequent to the notification, the user uses the CM’s front-end to view the details of the consent request, which may cover requests to access health information from multiple records in multiple HIPs. The user may approve some of these requests (and reject others), and he authorizes his approval by authenticating to the CM. Subsequently, a set of consent artefacts are generated by the CM, one for each HIP from which information is being sought, digitally signed by the CM and each consent artefact is shared with the HIU system that made the consent request. Consent artefacts are also sent to HIP systems to prepare them for future information requests. Besides the ability to give consent, users can also revoke consent that was previously given by them and may also be able to pause and resume the functioning of a consent artefact. All these functionalities can be availed by interacting with the front-end of the CM that generated the artefact. A CM may also provide users the ability to view all the consents granted by them through that CM, and details about data flow events involving each of those consents. 2.5 Health information (HI) types As discussed, a health record collected and shared by an HIP is viewed as a collection of one or more digital files (or database entries) containing health information of a user. Each such file must be of a certain type that is identifiable by HIU systems, and we refer to this meta-information as the ​health information (HI) Type ​of the file. In our architecture, HI types are mapped to ​FHIR Resources​, a taxonomy to define and represent health data in software systems. FHIR (Fast Health Interoperability Resources) is an internationally accepted data exchange standard which can be used in partnership with existing widely used standards. We use FHIR resources to define only the meta information (the “envelope”) that accompanies the health information in HIFs, but the actual information itself need not adhere to the FHIR standard. In
  18. 18. particular, we do not require existing software systems to comply with the FHIR standard in either storing or sharing of health information. This enables HIU systems to interpret health information received by them in HIFs but it still does not require HIP systems to change significantly. More details on the process of defining HI types and using them in HIFs are forthcoming. 3 APIs and Flows Before we describe the APIs and Flows in detail, we will discuss registries, which are a key building block used in the HIF architecture. 3.1 Registries and related functionalities Registries are software services that store master data about entities (users, organizations or systems) in a manner that the data is self-maintainable by these entities, provides a high degree of trust to those who wish to use the data and is accessible via open APIs. The ​National Digital Health Blueprint (NDHB) outlines several types of entities that are to be part of registries, including users (patients, beneficiaries), care professionals (doctors, nurses, ASHA workers, etc), care facilities (hospitals, labs, clinics, etc), payers (insurers, health plans, etc), government bodies (ministries, regulators), pharmaceuticals (drugs, device manufacturers etc), research organizations, and health technology companies. In the HIF architecture, these registries are valuable from the point of view of onboarding HIPs and HIUs. Since HIPs and HIUs could be care facilities, payers, government bodies, pharmaceuticals, research organizations and health technology companies, registries for all these entities can be used to verify the validity of an HIP/HIU when it is being onboarded. Other than the registries listed above, we also need registries of certain entities that are unique to the HIF ecosystem. This includes a registry for CMs, one for health repository providers and one for gateway providers. These registries must be built and maintained by gateway providers and must be available for access by other entities in the ecosystem. 3.1.1 Onboarding HIPs and HIUs using registries Any entity wishing to participate in the HIF ecosystem as an HIP or an HIU must have a health repository provider associated with itself. To create this association, it has two options: the entity may choose to become a health repository provider itself (and register itself as such) OR it may enter into a contract with an existing health repository provider, asking for its repository services. Once an HIP/HIU has an associated health repository provider, it must register with a gateway provider and go through an ​onboarding​ ​process​. Onboarding has two components: 1. Entity validation: ​An entity wishing to onboard as an HIP/HIU may list itself as an entity registered in one of the NDHB-defined registries and prove itself as such. If the entity does not exist in any of the external registries, it should prove its identity by other approaches defined by
  19. 19. the gateway provider. This process would also enable the gateway provider to create a profile of the entity, which must include the name of the entity and an entity ID. For example, in the case of care facilities, this could be a facility ID assigned by the facility registry or an HIP/HIU ID created by the gateway. 2. Submitting health repository details: ​The entity must furnish the name of its associated health repository provider and the access URL - in the repository provider’s domain - for all the HIF APIs of this entity. The access URL must be in the list of access URLs provided by the entity’s repository provider when registering itself. All these steps must be undertaken by suitable human representatives of the entity that is being onboarded. 3.1.2 Onboarding CMs and health repositories Like HIPs and HIUs, CMs and health repository providers also need to register themselves with a gateway provider. This process also involves an entity validation step and an information submission step. However, in the case of CMs and repositories, there are no externally available registries and as such, gateway providers need to create these registries. 3.1.2.1 CM registration CMs need to validate themselves by providing information about license, if any, obtained from a healthcare or other regulator and details about their registration as a company (or, if they are not a company, then details of having registered as an organization of the type they are). CMs may also be required to submit a certificate from a certification agency that claims the CM’s software system to be compliant with the HIF standards. Through the certificate or otherwise, CM’s must provide SLAs on all the HIF APIs implemented by them. Once validated, CMs must submit all data that is required to create the CM’s entry in the CM registry. The base schema for the CM registry is given below. This schema may be extended by the gateway. Schema for CM registry: cm-info:​ { // private attributes: cm-id:​ “integer”, // UUID used for addressing CM internally license​: “string” // Base-64 encoded license document issued by a regulator sla-details: ​“object” // Details of SLA provided by the CM reg-time​: “string” // Registration time of the CM, in date-time format last-updated​: “string” // Time of last update of CM info, in date-time format // public attributes: cm-full-name​:​ “string”, // Full name of the CM, an arbitrary alpha-numeric string cm-name​:​ “string”, // Name of the CM used in all PHR IDs issued by it, format: [a-z|A-Z|-|.]*
  20. 20. accessURLs​:​ [ // list of URLs that could be used to access CM APIs accessURL: ​“string”, // URL for accessing CM APIs ] pki-certificate​:​ “string”, // Base-64 encoded X.509 certificate with CM’s long-term public key. isActive​:​ “boolean” // Flag indicating whether CM is currently active or not isBlacklisted​:​ “boolean” // Flag indicating whether CM has been blacklisted by the gateway } 3.1.2.1 Repository registration Like CMs, health repository providers must also furnish company registration details at the time of registration in order to validate themselves. Software certification and SLAs must also be submitted. As in the case of CMs, repository providers must submit other information that is needed to create a registry entry for the repository provider. The base repository provider registry schema is given below. It is extensible by gateway providers. Schema for repository provider registry: repository-provider-info:​ { // private attributes: repo-provider-id:​ “integer”, // UUID used for addressing the provider internally sla-details: ​“object” // Details of SLA provided by the repository provider reg-time​: “string” // Registration time of the repository provider, in date-time format last-updated​: “string” // Time of last update of repository provider info, in date-time format hip-list: ​[​ ​// List of HIPs for whom this is an associated repository provider hip-id: ​“string” // HIP ID as defined at the time of HIP registration ] hiu-list: ​[​ ​// List of HIUs for whom this is an associated repository provider hiu-id: ​“string” // HIU ID as defined at the time of HIU registration ] // public attributes: repo-provider-full-name​:​ “string”, // Full name, an arbitrary alpha-numeric string accessURLs​:​ [ // list of URLs that could be used to access repository provider APIs accessURL: ​“string”, // URL for accessing repository provider APIs ] pki-certificate​:​ “string”, // Base-64 encoded X.509 cert with provider’s long-term public key isActive​:​ “boolean” // Flag indicating whether provider is currently active or not isBlacklisted​:​ “boolean” // Flag indicating whether provider has been blacklisted }
  21. 21. 3.1.3 Gateway peering Each gateway provider needs to share information about itself with other gateway providers. This results in every gateway provider maintaining a gateway registry which is mirrored at all other gateway providers. Each gateway registry entry contains essential information like the name of the gateway provider, a gateway ID, access URL, a PKI certificate and information about SLAs. Details about this are forthcoming. 3.1.4 Profile updation of different entities Information about different entities (HIPs, HIUs, CMs, repositories, gateways) needs to be kept up-to-date by the gateway providers. This may involve look-ups with externally hosted registries and checking for the status of PKI certificates. In the case of health repositories, there is one additional type of update that is performed regularly: when an HIP (resp HIU) with whom the repository is associated either registers with a gateway or de-registers from a gateway where it is registered, the attribute hip-list (resp hiu-list) ​for that provider’s registry entry must be updated. Details about these update protocols are forthcoming. 3.2 APIs The following diagram shows the different APIs that are to be implemented by all software systems in the HIF architecture: Figure 2: APIs to be implemented by all software systems in the HIF architecture Gateways need to implement five sets of APIs: gateway-cm APIs (interface to CMs), gateway-repository APIs (interface to health repositories), registry APIs (APIs for accessing the registry), cross-gateway APIs
  22. 22. (APIs for peering with other gateways) and monitoring APIs. Each health repository implements a set of APIs titled “repository APIs” which is meant for interfacing with a single gateway. Repositories may also implement APIs for interfacing with HIPs and HIUs, but these APIs are not part of the HIF standard. Each CM implements a set of APIs titled “cm APIs” which is meant for interfacing with a single gateway. Again, CMs may have APIs that enable the CM back-end to interface with the CM front-end; these too are not part of the standard. For ensuring high scalability and in order to minimize state management overheads at the gateway, we use a fully asynchronous approach in our design of the gateway APIs. For every API with an action verb ​V in the gateway-repository (resp. gateway-cm) API set, there is a corresponding callback API with action verb ​on-V ​in the repository (resp. cm) API set, using which the gateway submits the response that is generated in response to action ​V. ​Similarly, for every API with action verb ​V ​in the repository (resp. cm) API set, there is a corresponding callback API with action verb ​on-V ​in the gateway-repository (resp. gateway-cm) API set, using which the gateway receives the response that is generated in response to action ​V. The details of all APIs and flow diagrams are available from ​https://projecteka.github.io/​. This document only provides the high-level descriptions of the APIs. 3.2.1 gateway APIs 3.2.1.1 registry APIs CM registry APIs GET /cm-registry/all This is an API used by data repositories to get a list of all consent managers registered with the gateway provider GET /cm-registry/{cm} This is an API used by health repositories to fetch public information about a CM 3.2.1.2 gateway-cm APIs The gateway-cm API set consists of five categories of APIs, one each for the PHR-ID retrieval and search flows, the discovery flow, the linking flow, the consent flow and the data flow. PHR ID Retrieval and Lookup APIs POST /users/on-get-id This is the callback API corresponding to the /users/get-id API in the cm API set. The body contains either a PHR ID or an error message, to be filled if PHR ID retrieval failed. POST /users/on-find This is the callback API corresponding to the /users/find API in the cm API set. The body contains either the name of a user (whose PHR ID was given
  23. 23. in the find request) or an error message, to be filled if the find request failed. Discovery Flow APIs POST /care-contexts/discover This is the API used by CMs to initiate a discovery flow. The body contains at least one verifiable ID of a user required for discovery, the user’s PHR ID and, possibly, other information required to uniquely identify the user in the HIP system. The header contains the HIP-ID of the destination HIP. It is expected that the destination HIP system will return a set of (potentially masked) care-context labels (equivalent to health record labels). CM-initiated Linking Flow APIs POST /cm-links/link/init This is the API used by CMs when initiating a linking flow. The request body contains a PHR ID and a list of care-context labels to be linked with the ID and the header contains the HIP-ID of the destination HIP. POST /cm-links/link/confirm This API is used by CMs to submit a token sent by an HIP to the user during link initiation. The token is destined for the HIP system where link initiation happened. The body contains the token and a link reference number. The header contains the destination HIP’s ID. HIP-initiated Linking Flow APIs POST /hip-links/link/on-init This is the callback API corresponding to the /hip-links/link/init API in the cm API set. The body contains either information about a successful link initiation (a link reference number created by the CM that issues this request and details about the type of user authentication performed by the CM) OR an error message, to be filled if the link request was not fulfilled. The header contains the destination HIP’s ID. POST /hip-links/link/on-conf irm This is the callback API corresponding to the /hip-links/link/confirm API in the cm API set. The body contains either information about whether linking succeeded or not OR an error message in case linking fails. The header has the destination HIP’s ID. Consent Flow APIs POST /consent-requests/on-init This is the callback API corresponding to the /consent-requests/init API in the cm API set. The body contains either a consent request ID assigned by the CM to the consent request or an error message in case the consent request was not fulfilled. The header has the destination HIU’s ID.
  24. 24. POST /consent-requests/on-stat us This is the callback API corresponding to the /consent-requests/status API in the cm API set. The body contains either information about a successful status notification (the associated consent request’s ID, the status of that consent request, and optionally, a list of consent artefact IDs, specified in case consent was granted against that request) or an error message in case the consent status request was not fulfilled. The header has the destination HIU’s ID. POST /consents/hiu/notify This API is used by a CM to send consent-related notifications, targeted at an HIU’s health repository. The header contains the destination HIU’s ID. The body contains either a consent request ID (OR a consent artefact’s consent ID) for which notification is sent. There is a status flag indicating whether consent was granted against the specified consent request or not (OR whether the specified consent artefact was revoked, paused or resumed). If the notification is about consent being granted, the body also contains a list of consent IDs corresponding to the consent artefacts that were generated. POST /consents/hip/notify This API is used by a CM to send consent-related notifications, targeted at an HIP’s health repository. The header contains the destination HIP’s ID. The body contains the consent artefact’s consent ID for which notification is sent. There is a status flag indicating whether consent was granted, revoked, paused or resumed. If the notification is about consent being granted, the body also contains the corresponding consent artefact. POST /consents/on-fetch This is the callback API corresponding to the /consents/fetch API in the cm API set. The header contains the destination HIU’s ID. The body contains the consent artefact that was requested. 3.2.1.3 gateway-repository APIs The gateway-repository API also consists of four categories of APIs, as defined below. PHR ID Retrieval and Lookup APIs POST /users/get-id This is the API used by health repositories to fetch a PHR ID. The body contains a verifiable ID of the user whose PHR ID is required and, optionally, other user information (to help uniquely identify the user in the CM system). POST /users/find This is the API used by health repositories to check for the existence of a PHR ID. The body contains a PHR ID. Discovery Flow APIs
  25. 25. POST /care-contexts/on-discover This is the callback API corresponding to the care-contexts/discover API in the repository API set. The body contains either a set of (potentially masked) care-context labels or an error message, to be filled if the discovery request was not fulfilled. CM-initiated Linking Flow APIs POST /cm-links/link/on-init This is the callback API corresponding to the links/link/init API in the repository API set. The body contains either information about a successful link initiation (a link reference number and some meta-information about the type of user authorization being done by the HIP) or an error message, to be filled if the link request was not fulfilled. POST /cm-links/link/on-conf irm This API is the callback API corresponding to the links/link/confirm API in the repository API set. The body contains either information about successful linking (the unmasked care-context labels successfully linked) or an error message, indicating that linking failed. HIP-initiated Linking Flow APIs POST /hip-links/link/init This is the API used by health repositories to initiate a linking request on behalf of an HIP system. The body contains a PHR ID and a set of care context labels to be linked to the PHR ID. The header contains the destination CM’s name. POST /hip-links/link/confirm This API is used by health repositories to submit a token sent by a CM to the user during link initiation. The token is destined for the CM where the linking is required to take place. The body contains the token and a link reference number. The header contains the destination CM’s ID. Consent Flow APIs POST /consent-requests/init This is the API used by an HIU’s health repository to send a consent request to a CM. The header contains the CM-name of the destination CM. The body contains the consent details, which includes all parameters associated with the consent request like the PHR ID of the user, the HI types of the records that are required to be accessed and other details that would eventually go into the consent artefact once consent is granted. POST /consent-requests/status This is the API used by an HIU’s health repository to send a request to check status of a consent request earlier issued by the same repository. The header contains the CM-name of the destination CM. The body contains the ID of the consent request whose status check is requested.
  26. 26. POST /consents/hiu/on-notify This is the callback API used by an HIU’s health repository to respond to a consent notification sent by the gateway. The body contains either an acknowledgement or an error message. The header has the destination CM’s name. POST /consents/hip/on-notify This is the callback API used by an HIP’s health repository to respond to a consent notification sent by the gateway. The body contains either an acknowledgement or an error message. The header has the destination CM’s name. POST /consents/fetch This API is used by an HIU’s health repository to request for a consent artefact. The body contains the consent ID associated with that consent artefact. The header has the destination CM’s name. 3.2.1.4 monitoring APIs Details about monitoring APIs will be provided soon. 3.2.2 repository APIs APIs in the repository API set mirror the APIs in the ​gateway-cm API set​. Each has a corresponding API in the gateway-cm API set, with a similar name and almost similar contents. We describe them briefly here, highlighting the differences with the corresponding gateway-cm APIs. 3.2.2.1 HIP-targeted APIs PHR ID Retrieval and Lookup APIs POST /users/on-get-id This is the callback API corresponding to the /users/get-id API in the gateway-repository API set. POST /users/on-find This is the callback API corresponding to the /users/find API in the gateway-repository API set. Discovery Flow APIs POST /care-contexts/discover This is the API used by gateways during a discovery flow. CM-initiated Linking Flow APIs POST /links/link/init This is the linking initiation API used by gateways for CM-initiated linking. POST /links/link/confirm This is the API used by gateways to submit a token and confirm
  27. 27. CM-initiated linking. HIP-initiated Linking Flow APIs POST /hip-links/link/on-init This is the callback API corresponding to the hip-links/link/init API in the gateway-repository API set. POST /hip-links/link/on-conf irm This is the callback API corresponding to the hip-links/link/confirm API in the gateway-repository API set. Consent Flow APIs POST /consents/hip/notify This API is used by a gateway to send consent-related notifications to an HIP with whom the repository is associated. 3.2.2.2 HIU-targeted APIs Consent Flow APIs POST /consent-requests/on-init This is the callback API corresponding to the /consent-requests/init API in the gateway-repository API set. POST /consent-requests/on-status This is the callback API corresponding to the /consent-requests/status API in the gateway-repository API set. POST /consents/hiu/notify This API is used by a gateway to send consent-related notifications to an HIU with whom the repository is associated. POST /consents/on-fetch This is the callback API corresponding to the /consents/fetch API in the gateway-repository API set. 3.2.3 cm APIs APIs in the cm API set mirror the APIs in the ​gateway-repository API set​. Each has a corresponding API in the gateway-repository API set, with the same name and similar contents. We describe them briefly here. PHR ID Retrieval and Lookup APIs POST /users/get-id This is the API used by gateways to fetch a PHR ID from the CM. POST /users/find This is the API used by gateways to check for the existence of a PHR ID.
  28. 28. Discovery Flow APIs POST /care-contexts/on-discover This is the callback API corresponding to the care-contexts/discover API in the gateway-cm API set. CM-initiated Linking Flow APIs POST /cm-links/link/on-init This is the callback API corresponding to the links/link/init API in the gateway-cm API set. POST /cm-links/link/on-confirm This API is the callback API corresponding to the links/link/confirm API in the gateway-cm API set. HIP-initiated Linking Flow APIs POST /hip-links/link/init This is the linking initiation API used by gateways for HIP-initiated linking. POST /hip-links/link/confirm This is the API used by gateways to submit a token and confirm HIP-initiated linking. Consent Flow APIs POST /consent-requests/init This is the API used by gateways to send a consent request to a CM. POST /consent-requests/status This is the API used by gateways for checking status of a consent request earlier issued to the same CM. POST /consents/hiu/on-notify This is the callback API used by a gateway to respond to an HIU-targeted consent notification sent by a CM. POST /consents/hip/on-notify This is the callback API used by a gateway to respond to an HIP-targeted consent notification sent by a CM. POST /consents/fetch This API is used by a gateway to request for the consent artefact corresponding to a given consent ID.
  29. 29. 3.3 Flows In presenting the various flows, we use the following conventions: ● Solid lines for interactions which are covered by this standard; dotted lines for interactions which are also part of the flows but not covered by the standard. ● API names in bold and API parameters in brackets in the form of (​header; body​). ● HIP-IDs, HIU-IDs and CM-names are referred to as ​hip, hiu ​and ​cm ​respectively​. ● The symbol “|” denotes the logical operator OR. ● Parameters enclosed in square brackets “[ .. ]” are to be treated as optional parameters. ● We require that every request have a unique request ID (a UUID generated by the API requester) and a timestamp. These are not explicitly shown in the flow diagrams. Every callback API (API ending in ​on-V ​for some verb ​V​) must additionally have an ID whose value is the request ID of the API request that is being responded to. This is also omitted in the diagrams. ● We specify only key body parameters in the flow diagrams and do this at a high level e.g. consent-details​ is a parameter which contains various details related to a consent creation request. Detailed description of API body contents and parameters is available from: https://projecteka.github.io/ ​3.3.1 PHR ID retrieval and lookup We illustrate how PHR ID retrieval works when initiated at an HIP system. Retrieval can also be initiated by an HIU system but that flow is not shown here. PHR ID retrieval begins with the user submitting a verifiable ID to an HIP along with demographic information, triggering a get-id request to the associated health repository. The health repository first gets a list of all available CMs from the gateway using the registry API. For all CMs in the list of CMs, the repository sends simultaneous requests containing the verifiable ID and demographic information submitted by the user. Each CM internally matches the provided information against all user profiles and returns a PHR ID (and name of the user) if a match succeeds. The matching algorithm is CM-determined and may involve doing fuzzy matches on user demographic information. Eventually, the HIP system displays ​all ​PHR IDs returned by the different CMs and lets the user select which PHR ID to use in succeeding flows.
  30. 30. The next diagram illustrates the PHR ID lookup flow, when the lookup is initiated by an HIU system. PHR ID lookup can also be initiated by an HIP system, but that is not shown here. The ​response ​given by the CM in this flow is a boolean response, indicating whether the given PHR ID exists or not.
  31. 31. 3.3.2 Discovery flow Discovery involves the CM querying an HIP system about the existence of health records for a user with a given set of verifiable IDs. In response, the HIP system provides a set of care context labels (in masked form) which is sent by the health repository associated with the HIP. 3.3.3 CM-initiated linking flow The CM initiated linking flow begins with the CM requesting an HIP system to link a set of care context labels to be linked with a given PHR ID of the user. In response, the HIP system specifies the type of authentication that the HIP system wishes to perform for the user (and associated parameters) for the linking to take place and a ​link reference number​. In the current specification, only OTP-based authentication is supported: the HIP system sends an OTP (aka token) to the user to a communication address (phone number or email address) associated with his verifiable ID and the OTP needs to be submitted by the user to the HIP system, via the CM front-end, in a stipulated period of time. The CM submits this token to the HIP system along with the link reference number that was earlier received. If authentication succeeds, the HIP system responds with a success message and linking is deemed complete.
  32. 32. 3.3.4 HIP-initiated linking flow In the HIP initiated linking flow, the user submits the linking request to the HIP along with his PHR-ID and the HIP system optionally authenticates the user against his verifiable ID registered with it. The HIP system sends a linking request to the CM (via its associated health repository), specifying the care context labels it wishes to link for the user, and the CM then attempts to receive authorization from the user for the linking to be completed. Currently, we allow only OTP/token-based authorization: the CM sends an OTP to the user which must be then submitted back to the CM via either the CM front-end or a front-end of the HIP system. (The diagram below shows the latter use case.) Once authorized, the CM sends a confirmation message back to the HIP system.
  33. 33. 3.3.5 Consent flow The consent flow has four components which we describe below: 3.3.5.1 Consent request from an HIU to a CM Consent collection begins with an HIU system issuing a consent request to a CM against a given PHR ID. (The CM to issue the request to is determined based on the PHR ID.) The CM acknowledges the request by responding with a ​consent request ID ​(which is routed via the gateway and the health repository back to the HIU system)​. ​Consent collection from the user happens asynchronously after a consent request has been received by the CM. The CM may send a notification (e.g., via SMS) to the user at the time of receipt of a consent request and ask the user to view the details of the request and either grant consent or deny it. Subsequently, the CM notifies the HIU system that issued the consent request about the change in status of the consent request. This notification, described in the next section, informs the HIU whether the request was granted, in which case it also contains a list of consent artefact IDs of the
  34. 34. consent artefacts that were created against the request, OR it informs the HIU that consent was denied, in which case no artefact IDs are sent. 3.3.5.2 Consent notification from a CM to an HIU Consent-related notifications from a CM to an HIU system serve two purposes: first, when a consent request is fulfilled by a CM (i.e. consent is either granted or denied by the user), the CM notifies the HIU about the fulfillment of the request. In case fulfillment resulted in consent being granted, a list of consent artefact IDs are sent to the HIU system. Each consent artefact ID or consent ID in this list corresponds to a single consent artefact generated by the CM and contains information about consent given to the HIU to fetch health information from a single HIP. Corresponding to each such consent artefact is also an “HIP-facing” version of the artefact which contains nearly the same information, except that it does not specify the name of the HIU. (See below.) If consent is denied, no artefact IDs are sent and the HIU is informed about the denial of consent. The second purpose of notifications from the CM to the HIU is to inform the HIU about a change in status of a ​single ​consent artefact. In particular, if the consent artefact has been revoked, paused or resumed by the user, a notification corresponding to this update is sent to the HIU system that triggered the creation of the consent artefact. In this case, it is important that the CM receive acknowledgement that the notification about the change in status of the artefact has been recorded by the HIU system, which is accomplished by the /consents/hiu/on-notify/ callback APIs, as shown in the diagram below.
  35. 35. 3.3.5.3 Fetching a consent artefact from a CM Once consent has been granted by the user, the CM notifies the HIU system as above and for each consent artefact ID specified in the notification, the HIU system can issue a request to the CM to fetch the corresponding artefact as shown below. In situations where the notification about consent grant is not received from the CM in a timely manner (according to SLAs provided by the CM), the health repository associated with the HIU system can request for the status of the consent request that was earlier issued. In response, the CM responds with the status of the consent request and if consent has been granted, it also sends the IDs of the consent artefact(s) that were generated in response to the original consent request. This is illustrated in the next sequence diagram.
  36. 36. 3.3.5.4 Consent notification from a CM to an HIP As discussed above, whenever consent is granted by a user through a CM, two lists of consent artefacts are generated by the CM. One is meant to be shared with the consent-seeking HIU, and these are fetched by the HIU system using the consent fetch flow described above. For each artefact in this list of artefacts, there is also an HIP-facing version of the artefact which has information about the HIP from whom information can be fetched using the artefact, but which ​does not ​have information about the HIU seeking the information. This enables HIUs to be hidden from the purview of the HIPs providing health information and prevents HIPs from providing differentiated service to HIUs. Each HIP-facing consent artefact is sent by the CM to the respective HIP using a consent notification. As in the case of HIU-targeted consent notifications, HIP-targeted consent notifications also have a dual purpose. The first is to notify HIPs about the generation of a consent artefact for fetching information available from that HIP. In this case, the notification contains the artefact ID as well as the consent artefact itself. The second purpose is to notify the HIP about a change in status of an already generated consent artefact i.e. to notify the HIP that an artefact has been revoked, paused or resumed by the user. In this case, the notification contains only the artefact ID. In both cases, the notification contains a status attribute which is set to either GRANTED, REVOKED, PAUSED or RESUMED. In both cases, the corresponding HIP system must send an acknowledgement for receipt of the consent notification via the /consents/hip/on-notify APIs, as shown in the diagram. Acknowledgement is important for the CM to be assured that the HIP received the consent notification.
  37. 37. 3.3.6 Data flow The data flow takes place in roughly three stages. In the first stage, the HIU system (via its associated health repository) communicates a health information request to the HIP system. This communication happens via the CM, which sets a transaction ID (txn-id below) for the entire data flow. The transaction ID is communicated to the HIU’s repository as well as the HIP’s repository. Within the health information request, the HIU’s health repository embeds three key elements: ● The consent ID corresponding to the consent artefact against which the information request is being made ● A ​data push URL. ​This is a callback URL where the information can be pushed by the HIP’s health repository. The HIU may choose to specify a URL which hides its identity from the HIP system to the extent possible. In particular, this URL need not be the same as the access URL specified by the HIU at the time of registration with the gateway provider. ● A set of other parameters (denoted as ​params ​in the flow diagram). This includes the date-time range for which information is requested and a set of encryption parameters to enable the HIP repository to encrypt the information. In this standard, we use the Diffie-Hellman based encryption for encrypting health information. More details on this are forthcoming and will be provided in Section 4. All this information is relayed from the HIU’s health repository to the CM (via the gateway) and then from the CM to the HIP’s health repository (via the gateway), as shown in the diagram. In the next stage, the HIP health repository validates the information request. For this, (a) it ensures that the consent ID corresponds to an artefact that is neither expired, revoked nor paused; (b) the date-time range specified in the request is contained in the time window for which the consent artefact allows information access; (c) the encryption parameters are correctly defined. Once validated, the repository (or the HIP system) encrypts the requested health records and sends the encrypted data, along with the previously obtained transaction ID, to the data push URL communicated by the HIU. The encrypted data must also be ​digitally signed ​using a long-term private key associated with the HIP system.
  38. 38. In the third and final stage, notifications are sent to the CM by the sending and receiving systems. The HIP’s health repository sends a notification indicating that information was transmitted and the HIU system (or the HIU’s health repository) sends a notification when it receives the information, indicating whether the information fetch succeeded or failed. 4 Non-functional Requirements Besides adhering to the API specifications defined in the preceding section, CMs and health repositories are also required to fulfill a set of non-functional requirements which will ensure high security and reliability of information in HIFs. Details of these requirements are forthcoming.

×