Skip to main content

Community management

Communities are a way of managing and granting access to collections of FHIR resources, either for read or write access.

Page contents

Before you start

Once registered as an NHS England Terminology Server user, you will automatically join the 'Restricted' and 'Open' communities. This will allow you to consume (read) the national terminologies and classifications, such as SNOMED CT, ICD10 and the Data Model and Dictionary. You may also be invited to join other communities by community owners. Communities are a way of managing or granting access to collections of FHIR resources, either for read or write access.

Access is managed at both system/API level and Community level.

At system/API level the 2 main user groups are:

  • Author
  • Consumer

Community access is divided into 3 groups:

  • Owner
  • Author
  • consumer

A number of administrator and super-user roles also exist. For greater detail see our System and community roles page.

Users with system/API level Author access who have been granted a Community Owner role can create communities and are immediately the owner of any community they create. They can then appoint other owners, authors, and consumers within their community. Adding and removing users to/from these groups grants and revokes community privileges.

Note that non-NHS users will typically not be granted a Community Owner role. To request this, please email [email protected] explaining specifically why you wish to create communities.

Each community has a base FHIR security label associated with it, which is a string of characters generated when the community is created. FHIR resources can have this base label plus ".read" or ".write" added to them to grant read or write level access to that FHIR resource to members of that community.

 

Granting community write access to a user that only has read access to the FHIR API will not enable them to write to the community's resources.

Community owners can add and remove users to/from the community groups.

Community authors are granted read and write privileges to resources labelled with the community's ".read" and ".write" labels respectively.

Community consumers are granted read-only privileges to resources labelled with the community's ".read" label.

How this works

For example, a community named Bart’s CodeSystem could have the label BCS. The community's FHIR resource can have the labels BCS.read and BCS.write added to them, meaning:

  • resources with the BCS.read label are readable by users in the Bart’s CodeSystem consumers and authors groups
  • resources with the BCS.write label are modifiable by users in the Bart’s CodeSystem authors group

Resources can be labelled with more than one label, and in this case a user must have a community privilege matching at least one of the security labels to be granted the permission associated with that label.

So a resource labelled with BCS.read and XXX read will be readable by a user who is an author or consumer in either the associated BCS or XXX communities (they don't need both).

This can be used to control authorship of a collection of resources by a group of users by adding their community read and write labels, while extending read access to other communities by adding only the read labels for those communities.

How to create a community

1.  Log in to the Administration console. 

2. Click on Communities in the bar on the left. 

create a community screen shot

3. Enter your community name and security label. The security label is a short alphanumeric tag which will be a unique identifier for your community.

4. Click Save - you will get a success message pop up.

Add a user to a community

Community owners can add users to their communities.

1. Log in to the Administration console. 

2. Click on Users on the menu on the left. 

3. Search  for the user you wish to add to your community. You can do this by either:

  • searching for their name using the search bar
  • clicking the View all users and browsing to find the user4 then click on the ID of the user you wish to add to your community

Available groups section screen

4. Select the Groups tab.

ontology user screen image

5. In the Available Groups section, scroll down to find and select the community you wish to add the user to.

available groups screen

6. Click Join to to add the user to the group. Their group membership will now show the new community.

user screen highlighted

7. Repeat to add user to other communities.

Removing a user from a community

Only community owners can remove users from their communities. To remove a user from a community:

1. Log in to the Administration Console. 

2. Click on Users.

3.  Search for the user you wish to remove from your community. You can do this by either

  • searching for their name using the search bar
  • clicking the View all users button and browsing to find the user

4. Click on the ID of the user you wish to remove from your community.

Administration console user look-up

5. Select the Groups tab.

6. In the Group Membership section, scroll down to find and select the community you wish to remove the user from.

A user may be a member of more than one group. So you may need to check each group.

Administration console - group membership search

7. Click Leave to remove the user from the group or groups. You'll need to repeat to remove user from other communities.

Deleting a community

The Administration Console currently has no user interface to delete a community. A community can become dormant simply by removing all users from the associated groups. A service desk user will still always have the ability to resurrect the community and appoint new owners even if the owner group is empty.

If a community really must be deleted, this can be performed using a REST request to the authorisation server. To do that, you need to use a set of credentials that have sufficient permissions to create/delete communities such as a Service Desk role.

Deleting a community will not delete the corresponding security labels on the resources associated with it. Before deleting a community, you should therefore remove the security label for the community from all resources.

 

If security labels are not removed from resources before the community is deleted, users will be unable to access the resources unless they also have another, different, security label.

 

If this happens you will need a service desk user to remove the offending security labels to restore access.

Step 1 - Get a bearer token

This cURL command gets a bearer token from the authorisation server.

curl --location --request POST 'https://authorisation-server/auth/realms/realm-name/protocol/openid-connect/token' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'grant_type=client_credentials' \
  --data-urlencode 'client_id=XXX' \
  --data-urlencode 'client_secret=YYY'

Where the following placeholders require completion for the specific installation

Placeholder Required value
authorisation-server host name of the authorisation server for the solution
realm-name realm id for the solution
XXX client_id for the client credentials with appropriate access
YYY client_secret for the client credentials with appropriate access. 

The response will include a JSON payload similar to the following:

 

Token response

{
    "access_token": "AAA",
    "expires_in": 3600,
    "refresh_expires_in": 1800,
    "refresh_token": "BBB",
    "token_type": "bearer",
    "not-before-policy": 1601356578,
    "session_state": "12bd48fc-5373-410b-a016-f208fc827095",
    "scope": ""
}

Where "AAA" will be a long string of characters. This is the bearer token required in the next step.

 

Step 2 - List communities

The second step is to list the communities for the server. Without the exact community representation JSON, it is not possible to call the DELETE method to delete the community.

 

curl --location --request GET 'https://authorisation-server/auth/realms/realm-name/communities' \

  --header 'Authorization: Bearer AAA'

You will need to replace the authorisation-server host name and the realm-name with the real values for the deployment. The response will look similar to the following:

[

    {

        "securityLabel": "SNOMED",

        "communityName": "SNOMED"

    },

    {

        "securityLabel": "NDD",

        "communityName": "NHS Data Dictionary"

    },

    {

        "securityLabel": "bird",

        "communityName": "Bird watching"

    }

]

Step 3 - Delete community

This list command above provides a way to get the exact details to send to delete a community. The HTTP DELETE request shows how to delete a specific community. 

curl --location --request DELETE 'https://authorisation-server/auth/realms/realm-name/communities' \

--header 'Authorization: Bearer AAA' --header 'Content-Type: application/json' \

--data-raw '    {

        "securityLabel": "bird",

        "communityName": "Bird watching"

    }'

This process will delete the following artefacts related to the community:

  • groups 
  • roles
  • scopes
  • underlying database record for the community and security label

When the groups are deleted the users and roles will not be removed they will just be removed from the deleted group. Their access to any other roles or groups will not be affected. 

Last edited: 4 June 2025 9:12 am