Overview

Health Gorilla uses the PractitionerRole FHIR endpoint for creating users and managing the associated UUIDs. See PractitionerRole for more details. Two types of users can be created via the PractitionerRole endpoint. Clinical users represent those users with NPI numbers. Non-clinical users represent staff, office managers, nurses and other users without associated NPI numbers. Each user is created using a PractitionerRole FHIR resource. The process of creating a non-clinical user is detailed here. More examples can be found at the Health Gorilla Git Repository.

The create_users scope is required when creating Users via the PractitionerRole API.

Supported Attributes of PractitionerRole Resource

Attribute	Required	Notes
resourceType	Yes	will always be "PractitionerRole"
meta	Yes	This field will contain a required profile attribute as well as an optional "tag" attribute that controls email invitations and notifications for new users.
active	Yes	will always be set to "true" for creating new users
practitioner	Yes	Will contain a reference to an internal Practitioner Resource that describes the user to be created
code	Yes	Will contain the required administrative-role
extension	No	This attribute is used to pass an optional security-role for the user.
organization	No	This field is used when creating a user in a different tenant. (See Creating a Tenant)

Supported Attributes of Internal Practitioner Resource

Attribute	Required	Notes
resourceType	Yes	Will always be Practitioner
id	Yes	the ID of the resource. This ID is referenced in the PractitionerRole.practitioner attribute.
meta	Yes	will contain a required profile attribute
identifier	No	This attribute can be used to assign a UUID to the user for use with Health Gorilla's Single SIgn On option
name	Yes	will contain the user's real name
telecom	No	This attribute can be used to add the user's email to the account.
extension	Yes	This attribute is use to pass a required username and an optional password for the account.

Creating A Non-Clinical User

Controlling Email Invitations and Notifications

The PractitionerRole.meta.tag array will allow you to decide if an email invitation will be sent to the created user as well as turning off any notifications set for a new user. By default, an email invitation is sent by Health Gorilla to new users. This email is sent to validate the account. This functionality can be turned off by using the "VERIFIED" option in the tag array per the example below.

By default, a new user account has email notifications turned on. You can turn off this functionality by using the "NO_SUBCRIPTIONS" option in the tag array per the example below.

The tag attribute is optional and is only used if the VERIFIED or NO_SUBSCRIPTIONS functionality is required.

"tag":[
        {
           "system":"https://www.healthgorilla.com",
           "code":"VERIFIED"
        },
        {
           "system":"https://www.healthgorilla.com",
           "code":"NO_SUBSCRIPTIONS"
        }
     ]

Setting the Administrative Role

The PractitionerRole.code array is used to set the administrative role for the user. This attribute is required for user creation. The options are nurse, officeManager, staff, and billingStaff. This attribute is only used as a label inside of your tenant and does not affect access to data or functionality.

"code": [
      {
        "coding": [
          {
            "system": "https://www.healthgorilla.com/administrative-role",
            "code": "officeManager",
            "display": "Office Manager"
          }
        ]
      }
    ],

"code": [
      {
        "coding": [
          {
            "system": "https://www.healthgorilla.com/administrative-role",
            "code": "staff",
            "display": "Staff"
          }
        ]
      }
    ],

Setting the Security Role

The security-role extension is used to grant a user specific security roles inside of your tenant in Health Gorilla. Options are readonly, administrator, and staff.

"extension":[
      {
        "url": "https://www.healthgorilla.com/fhir/R4/StructureDefinition/practitionalrole-security-role",
        "valueCodeableConcept": {
            "coding": [
                {
                    "system": "https://www.healthgorilla.com/security-role",
                    "code": "administrator",
                    "display": "Administrator"
                }
            ],
            "text": "Administrator"
        }
    }
 ],

"extension":[
      {
        "url": "https://www.healthgorilla.com/fhir/R4/StructureDefinition/practitionalrole-security-role",
        "valueCodeableConcept": {
            "coding": [
                {
                    "system": "https://www.healthgorilla.com/security-role",
                    "code": "readonly",
                    "display": "Readonly"
                }
            ],
            "text": "Readonly"
        }
    }
    ],

"extension":[
      {
        "url": "https://www.healthgorilla.com/fhir/R4/StructureDefinition/practitionalrole-security-role",
        "valueCodeableConcept": {
            "coding": [
                {
                    "system": "https://www.healthgorilla.com/security-role",
                    "code": "staff",
                    "display": "Staff"
                }
            ],
            "text": "staff"
        }
    }
    ],

Creating a UUID for a User

Health Gorilla allows the use of Single Sign On. This can be used in conjunction with the Health Gorilla iframe. The internal Patient FHIR resource uses the Practitioner.identifier attribute to create the UUID. There is no specification for the unique identifier. Any unique ID can be passed. The SSO facility associated with the user's tenant must be referenced in this attribute.

"contained":[
  {
   "resourceType": "Pracitioner",
    .....
			"identifier":[
            {
               "type":{
                  "coding":[
                     {
                        "system":"http://terminology.hl7.org/CodeSystem/v2-0203",
                        "code":"PRN",
                        "display":"Provider Number"
                     }
                  ],
                  "text":"Provider Number"
               },
               "value":"<User's UUID>",
               "assigner":{
                  "reference":"Organization/f-<SSO FACILITY ID>"
               }
            }
     ]
}
]

Setting the User's Real Name

The Practitioner.name attribute is used to pass the user's real name to Health Gorilla. The user's real name is required to create a user account in Health Gorilla.

"contained": [
  {
    "resourceType": "Practitioner",
    ......
		"name": [
          {
            "use": "official",
            "text": "<FULL NAME>",
            "family": "<LAST NAME>",
            "given": [
              "<FIRST NAME>"
            ]
          }
    ]
  }
]

Setting the User's Email

The Practitioner.telecom attribute is used to pass the user's email to the user account. This field is optional.

"contained":[
  {
    "resourceType": "Practitioner",
    .....
		"telecom": [
          {
            "system": "email",
            "value": "<USER EMAIL>",
            "use": "work"
          }
    ]
	}
]

Setting the Username and Password

Health Gorilla uses extensions to allow for creation of a username and password. The username is required for account creation. A password is optional and is only required if the user will log into the Health Gorilla UI via the Health Gorilla log in screen.

"contained":[
  {
    "resourceType":"Practitioner",
     .....
		"extension": [
          {
            "url": "https://www.healthgorilla.com/fhir/R4/StructureDefinition/hg-practitioner-login",
            "valueString": "<USERNAME>"
          },
          {
            "url": "https://www.healthgorilla.com/fhir/R4/StructureDefinition/hg-practitioner-password",
            "valueString": "<PASSWORD>"
          }
        ]
	}
]

Setting the Target Tenant (Only used for IPA customers)

Health Gorilla allows customers to manage multiple tenants if required by their business needs. In this workflow, the need exists to create users in multiple tenants. The organization attribute is used to pass the target tenant's unique identifier to Health Gorilla.

"organization": {
        "reference": "Organization/t-111e1e656869ac26d411820e"
},

Non-Clinical User Full Example

The following example payload is contains all available attributes. More examples can be found at the Health Gorilla Git Repo

{
    "resourceType": "PractitionerRole",
    "meta": {
      "profile":[
        "https://healthgorilla.com/fhir/StructureDefinition/hg-user"
      ],
      "tag":[
        {
           "system":"https://www.healthgorilla.com",
           "code":"VERIFIED"
        },
        {
           "system":"https://www.healthgorilla.com",
           "code":"NO_SUBSCRIPTIONS"
        }
     ]
    },
    "active": true,
    "practitioner": {
      "reference": "#1"
    },
    "code": [
      {
        "coding": [
          {
            "system": "https://www.healthgorilla.com/administrative-role",
            "code": "staff",
            "display": "Staff"
          }
        ]
      }
    ],
    "extension":[
      {
        "url": "https://www.healthgorilla.com/fhir/R4/StructureDefinition/practitionalrole-security-role",
        "valueCodeableConcept": {
            "coding": [
                {
                    "system": "https://www.healthgorilla.com/security-role",
                    "code": "staff",
                    "display": "Staff"
                }
            ],
            "text": "Staff"
        }
    }
    ],
    "contained": [
      {
        "resourceType": "Practitioner",
        "id": "1",
        "meta": {
          "lastUpdated": "2021-07-28T12:33:05.136+03:00",
          "profile": [
            "http://hl7.org/fhir/us/core/StructureDefinition/us-core-practitioner",
            "https://healthgorilla.com/fhir/StructureDefinition/hg-practitioner"
          ]
        },
        "identifier":[
            {
               "type":{
                  "coding":[
                     {
                        "system":"http://terminology.hl7.org/CodeSystem/v2-0203",
                        "code":"PRN",
                        "display":"Provider Number"
                     }
                  ],
                  "text":"Provider Number"
               },
               "value":"<USER'S UUID>",
               "assigner":{
                  "reference":"Organization/f-<SSO FACILITY ID>"
               }
            }
         ],
         "name": [
          {
            "use": "official",
            "text": "<FULL NAME>",
            "family": "<LAST NAME>",
            "given": [
              "<FIRST NAME>"
            ]
          }
        ],
        "telecom": [
          {
            "system": "email",
            "value": "<USER EMAIL>",
            "use": "work"
          }
        ],
        "extension": [
          {
            "url": "https://www.healthgorilla.com/fhir/R4/StructureDefinition/hg-practitioner-login",
            "valueString": "<USERNAME>"
          },
          {
            "url": "https://www.healthgorilla.com/fhir/R4/StructureDefinition/hg-practitioner-password",
            "valueString": "<PASSWORD>"
          }
        ]
      }
    ]
  }