Create launch parameter for app to track customer usage for auditing and billing.

[isaacvetter]

It's often important for an app being accessed by multiple health systems to receive an identifier, when the app is launched from the EHR, that uniquely describes the health system.

In practice, this technique is widely and consistently implemented to accomplish auditing and even billing based upon usage. Ultimately, the needs of the app dictate a health system identifier. This identifier is consumed by the app and can either be specified by the app, or could be some type of tenant identifier from the EHR, or could even be a department or facility identifier.

I typically see this identifier named something like "healthsystem" or "client".

Any suggestions for a great name for this launch parameter?

[daliboz]

I don't think we're settled on this, but right now we call this tenant in our system. I'll throw that out as an option. It's not always as 1:1 with what an app might consider a "client" (sometimes it is many:1 app "client"). Because of that, I would avoid the client term.

[jmandel]

Yeah, this is definitely what Cerner calls "tenant", but I'm not sure that term is widely understood. I don't have any fabulous naming suggestions (and at the end of the day we'll just pick something and move on) but my top suggestions would be:

• billing_account
• billing_code
• customer

[kpshek]

Sorry for coming late on this thread.

Yeah, this is definitely what Cerner calls "tenant", but I'm not sure that term is widely understood.

Our use of tenant is rooted here, which I've found to be very prevalent throughout the computing industry. So, tenant isn't some term Cerner invented or appropriated. :-)

I would not use terms like billing_account or billing_code as it is not clear whom is the billable entity. Eg, billable by the FHIR server or billable by the SMART app developer?

I'd avoid the term client as that is overloaded in this space. Eg, OAuth clients, browser clients, etc.

customer is OK but can be awkward as it sounds biased towards vendor-based FHIR servers. For example, imagine a healthcare institution that manages it's own FHIR server instance. In this case, it would be it's own "customer".

I still thinktenant is a better choice. I realize I'm biased here since Cerner is already using this term today; however, as I mentioned earlier, this is an industry term. Ultimately, what we're identifying here is the owner of the data represented by the FHIR server (the iss parameter value). I would avoid terms that conflict with the FHIR resources to avoid confusion. The big one I thought of is organization.

Here's a proposal for the documentation on this new launch context parameter:

Launch context parameter	Example value	Meaning
tenant	"123" or "abc" (any string value)	An opaque string identifying the healthcare organization that is the owning tenant for the data within the FHIR server (see iss parameter).

[kpshek]

From @jmandel on #131:

Also noting: #133 address another use case that some have expressed for location: the ability to tell "whom to charge" for a given app launch.

When we land on a parameter name and meaning, let's get information from existing SMART EHR systems on how they would implement this parameter. Then, we'll take that to the mailing list and get feedback from all of the SMART app developers to see if this would meet their needs. If we get majority agreement, we have a good plan for progressing forward.

If we get a significant number of developers looking for location-based information that isn't available elsewhere, we can regroup and figure something else out. Based upon the developers I've worked with, I don't expect location being a common requirement.

[davidhay25]

"An opaque string identifying the healthcare organization that is the owning tenant for the data within the FHIR server (see iss parameter)." - so why not 'organisation' or 'custodian'?

[kpshek]

I was trying to avoid the word "organization" by itself as to not cause confusion that we are referring to a FHIR Organization. 😄

Custodian is a bit blurry to me because I think of a data custodian in which case the healthcare organization and the EHR both have distinct & shared responsibilities as the custodian of the data contained within the FHIR server.

Naming things is hard. 😛

At the end of the day, I think that for whatever parameter name we come up with, if we document how each of the EHR vendors is populating that field, we should be good.

[jmandel]

Naming things is hard. 😛

It sure is!

FWIW, billing_code is still my preference. It gets at the reason this field exists, and makes people less inclined to try to use it for other purposes. We'd document the fact that it's about the app or server tracking who called it for its own internal accounting/billing purposes:

Launch context parameter	Example value	Meaning
billing_code	"abc1" (any string value)	An opaque string that the app can use to associate this launch with a particular billing account, for internal tracking. This is useful when a given FHIR server is used by multiple sites, departments, or other organizational entities that the app wants to track and bill separately. Using this field correctly requires a common understanding between the EHR and the app.

[kpshek]

FWIW, billing_code is still my preference. It gets at the reason this field exists, and makes people less inclined to try to use it for other purposes

This is actually just one use case for this new field. Another use case is for the SMART app developer to identify the data source in their private set of data. For example, imagine a Population Health SMART app that aggregates data from multiple EHRs. When the SMART app is launched from each EHR, they need to identify what logical data set to pull their data from.

[jmandel]

This part is less clear to me @kpshek. Can you shed light onto why the issuer (FHIR server base URL) is the wrong choice for identifying the "logical data set"?

Overall, if there are two different concepts, we can also consider creating two parameters and giving them different names. I understand Cerner used one thing, called "tenant id" for both of these; but I'd want to know whether this combination makes sense in other environments, too.

[whitehatguy]

I might point this discussion towards the ITU-T publication "Cloud Computing - Overview and vocabulary (Y.3500)" as published by the International Telecommunications Union standards group. Within it, it defines several possible (standard) naming choices:

3.2.11 cloud service customer: Party (3.1.6) which is in a business relationship for the purpose of using cloud services (3.2.8).
3.2.37 tenant: One or more cloud service users (3.2.17) sharing access to a set of physical and virtual resources.

The document also provides this useful tidbit in the "key characteristics" of cloud computing section:

Multi-tenancy: A feature where physical or virtual resources are allocated in such a way that multiple
tenants and their computations and data are isolated from and inaccessible to one another. Typically, and within the context of multi-tenancy, the group of cloud service users that form a tenant will all belong to the same cloud service customer organization. There might be cases where the group of cloud service users involves users from multiple different cloud service customers, particularly in the case of public cloud and community cloud deployments. However, a given cloud service customer organization might have many different tenancies with a single cloud service provider representing different groups within the organization;

The question primarily comes down to what apps need - if the intent is to identify a party in which a business relationship is established, then it would be possible that multiple FHIR instances might return the same "cloud service customer" value as part of launch. If the intent is to disambiguate at a lower level (perhaps different "facilitities" or "locations"), then "tenant" may be an appropriate choice, especially if it's intended that client applications need to know something more detailed than the just the party in which they do business relationships with. Just my two cents - thanks for reading.

[kpshek]

This part is less clear to me @kpshek. Can you shed light onto why the issuer (FHIR server base URL) is the wrong choice for identifying the "logical data set"?

You can use the FHIR server base URL if the owner of the FHIR server actually segments the data between tenants/customers/data sources. It's entirely possible the a FHIR server opts to not do this and instead uses the user identity to ensure that they have access to just the data they should have access to.

Eg, imagine a completely cloud-based EHR written from the ground up that has a common identity across all of the customers/tenants. So, whether I'm seeing patients at Hospital A or go across the street to Hospital B, I'm using the same identity. The EHR app is a single webapp or mobile app that allows me to sign-in and view all patient records I have access to.

I'm not saying systems like this exist but I sure how someday we have something like this and in which case, this system would have a single FHIR base URL for all of it's customers.

Another consideration when using FHIR base URLs to map to the SMART app developer's private data set is that the FHIR base URLs change when new FHIR versions are supported. This requires the developer to do the mapping again. Not a deal breaker, but something to be aware of.

Overall, if there are two different concepts, we can also consider creating two parameters and giving them different names. I understand Cerner used one thing, called "tenant id" for both of these; but I'd want to know whether this combination makes sense in other environments, too.

The argument I was trying to make are that there are two use cases for this singular concept we are discussing. I don't think we need two different fields based upon all of the SMART app developers whom I've talked with and are using the vendor specific fields in use today.

[jmandel]

I'm not saying systems like this exist but I sure [hope] someday we have something like this and in which case, this system would have a single FHIR base URL for all of it's customers.

It's a great thought experiment! In a future-looking system like this, there may be multiple levels to care about. Clearly the FHIR base URL becomes non-differentiating. Does "tenant" mean an organization like "Boston Children's Hospital" (i.e. equivalent to a FHIR base URL in today's world) or a finer-grained app-billing oriented org unit like "the cardiology department" (if they're the ones who have a paid subscription to this particular app)? It seems to me that the "billing code" concept is really an app-specific identifier saying "which charge account do I associate this launch with", whereas "tenant" is supposed to be "a static, persistent truth about the organizational unit whose data are being accessed in this launch".

Another consideration when using FHIR base URLs to map to the SMART app developer's private data set is that the FHIR base URLs change when new FHIR versions are supported. This requires the developer to do the mapping again. Not a deal breaker, but something to be aware of.

This is a most interesting point, @kpshek. It suggests that a "tenant id" in this sense would need to be globally unique (not just unique with respect to a particular FHIR base). Is that right? If so, let's update the proposed language to indicate "globally unique" instead of just "opaque".

[kpshek]

It seems to me that the "billing code" concept is really an app-specific identifier saying "which charge account do I associate this launch with", whereas "tenant" is supposed to be "a static, persistent truth about the organizational unit whose data are being accessed in this launch".

I think this is a fair characterization and speaks to the two use cases being discussed here.

This is a most interesting point, @kpshek. It suggests that a "tenant id" in this sense would need to be globally unique (not just unique with respect to a particular FHIR base). Is that right? If so, let's update the proposed language to indicate "globally unique" instead of just "opaque".

Good point. Cerner's tenant ids happen to be globally unique.

---

Perhaps we should take a step back and take an inventory of how this proposed field would be populated by EHRs today. I'll start off and will update this table as we get new values.

EHR	Contact	Value
Cerner	@kpshek	A globally unique value that identifies the source/owner of the data. A single Cerner EHR customer may have multiple tenants within their EHR; this value will identify each tenant distinctly.

@isaacvetter - What value would you populate this with in Epic?

[SiddShah]

At eClinicalWorks we use a term called 'practice code' that uniquely and globally identifies a data source system. We would ideally pass this code to the app. In fact it is identified in our FHIR URL.
Having said that, there is a chance that there are multiple tenants within that system, but this use case is hard to model unless we define this ID to be a 1:1 mapping with a taxID of the entity/organization.

[bdoolittle]

@kpshek At athenahealth, we do not use globally unique ids to identify our users or ogranizations, to achieve global uniqueness for SMART, we could generate a UUID for each of our tenants.

Since SMART apps would be using the tenant code internally, it may make sense for the SMART app to assign this value to its users. This would give the app developer the flexibility to uniquely identify its users in whatever way makes the most sense. In this implementation, different SMART apps would provide different tenant ids and the EHR would be responsible for storing these ids and surfacing the proper id when launching a SMART app.

I also want to point out that the tenant id may apply to several different entities:

1. Individual users (a provider extending the services provided by their practice)
2. Departments within a healthcare organization
3. A healthcare organization
4. A healthcare network (all users on an EHR may be granted access to a SMART app that provides a core service to the EHR)

Having tiers of tenants may complicate the issue. With EHR defined tenant ids, we would have to worry about uniqueness across all levels of SMART app payers (from a single provider to a network of outpatient practices). With SMART app defined tenant ids, we're guaranteed uniqueness, but the EHR would have to make sure that it can manage the tenant ids properly so that the right tenants are being billed.

[jldanford]

@kpshek Allscripts supports unique identifiers by database, although the method varies across the product platforms. As for selecting a name I'd recommend against using anything that references a particular function, i.e. billing*. Experience has shown me that about a week after you do something like this you find a completely different use case and the name then just causes confusion. It might be safer to go with some of the more generic suggestions like tenant id (which is one value we use), or custodian, or even something completely utilitarian like dataSourceID.

[isaacvetter]

Given the significant lack of clearcut consensus on this feature, I don't think that we should try to include it in the SMART spec balloted by HL7. Further, I'm inclined to close the issue.

Any concerns?

[isaacvetter]

Voted on during SMART ballot call, closing.

[isaacvetter]

Hey Everybody, CDS Hooks added an optional field in its request named tenant containing a string. Could we reconsider this issue in light of that ?