Organisation relationship query

Organisation Data Service (ODS)
1

Hello,

We are in the process of migrating from the Organisation Data Service - ORD API to the new FHIR ODS API.

I’m comparing the relationship data and it looks like the primaryRoleID is included in the older API but not the new one and I’m not sure why that is?

Does the definition for the relationship only consist of the two organisation codes and the relationship code (for example RE4)?

In that case if an organisation changes it’s role how would we know which role the relationship relates to?

I’ve included an example of the API queries and results I’m looking at:

https://uat.directory.spineservices.nhs.uk/ORD/2-0-0/organisations/G81086

{
“Date”: [
{
“Type”: “Operational”,
“Start”: “2013-04-01”,
“End”: “2020-03-31”
}
],
“Status”: “Inactive”,
“Target”: {
“OrgId”: {
“root”: “2.16.840.1.113883.2.1.3.2.4.18.48”,
“assigningAuthorityName”: “HSCIC”,
“extension”: “99K”
},
“PrimaryRoleId”: {
“id”: “RO98”,
“uniqueRoleId”: 161529
}
},
“id”: “RE4”,
“uniqueRelId”: 256251
}

https://sandbox.api.service.nhs.uk/organisation-data-terminology-api/fhir/Organization?identifier=G81086&_revinclude=OrganizationAffiliation%3Aprimary-organization

“fullUrl”: “https://sandbox.api.service.nhs.uk/organisation-data-terminology-api/fhir/OrganizationAffiliation/256251”,
“resource”: {
“resourceType”: “OrganizationAffiliation”,
“id”: “256251”,
“meta”: {
“versionId”: “1”,
“lastUpdated”: “2024-06-26T15:15:47.832+00:00”,
“source”: “#9f7738d104dbaba4”,
“profile”: [
“https://fhir.hl7.org.uk/StructureDefinition/UKCore-OrganizationAffiliation”,
“https://fhir.nhs.uk/England/StructureDefinition/England-OrganizationAffiliation-ODS”
]
},
“extension”: [
{
“url”: “https://fhir.nhs.uk/England/StructureDefinition/Extension-England-TypedPeriod”,
“extension”: [
{
“url”: “dateType”,
“valueCoding”: {
“system”: “https://fhir.nhs.uk/England/CodeSystem/England-PeriodType”,
“code”: “Legal”,
“display”: “Legal”
}
},
{
“url”: “period”,
“valuePeriod”: {
“start”: “2013-04-01”,
“end”: “2020-03-31”
}
}
]
},
{
“url”: “https://fhir.nhs.uk/England/StructureDefinition/Extension-England-TypedPeriod”,
“extension”: [
{
“url”: “dateType”,
“valueCoding”: {
“system”: “https://fhir.nhs.uk/England/CodeSystem/England-PeriodType”,
“code”: “Operational”,
“display”: “Operational”
}
},
{
“url”: “period”,
“valuePeriod”: {
“start”: “2013-04-01”,
“end”: “2020-03-31”
}
}
]
}
],
“identifier”: [
{
“system”: “https://digital.nhs.uk/services/organisation-data-service/CodeSystem/organization-relationship-instance”,
“value”: “256251”
}
],
“active”: false,
“period”: {
“start”: “2013-04-01”,
“end”: “2020-03-31”
},
“organization”: {
“reference”: “Organization/G81086”,
“identifier”: {
“system”: “https://fhir.nhs.uk/Id/ods-organization-code”,
“value”: “G81086”
}
},
“participatingOrganization”: {
“reference”: “Organization/99K”,
“identifier”: {
“system”: “https://fhir.nhs.uk/Id/ods-organization-code”,
“value”: “99K”
}
},
“code”: [
{
“coding”: [
{
“system”: “https://digital.nhs.uk/services/organisation-data-service/CodeSystem/ODSRelationship”,
“code”: “RE4”,
“display”: “IS COMMISSIONED BY”
}
]
}
]
},
“search”: {
“mode”: “include”
}
},

Thanks

2

Hello

Currently the profile for Organization (and extension for role: https://fhir.nhs.uk/England/StructureDefinition/Extension-England-OrganisationRole) doesn’t indicate whether the role is primary or not. The primary nature of a role is not organization dependent (it is a property of the role code itself).

Note that ODS business rules do not currently permit a code to have it’s primary role changed, only non primary roles can be added/end dated during the lifecycle of the code.

You can get all the roles for all the organizations with a relationship to a given primary organization with a call like:
https://sandbox.api.service.nhs.uk/organisation-data-terminology-api/fhir/OrganizationAffiliation?primary-organization=A81060&_include=OrganizationAffiliation:primary-organization&_include=OrganizationAffiliation:participating-organization

But that won’t tell you which roles are primary.

Currently whether a role is a primary role or not is represented in the CodeSystem https://digital.nhs.uk/services/organisation-data-service/CodeSystem/ODSOrganisationRole

And you can get this with a call like:
'https://sandbox.api.service.nhs.uk/organisation-data-terminology-api/fhir/ValueSet/$expand?url=https://digital.nhs.uk/services/organisation-data-service/CodeSystem/ODSOrganisationRole/vs&property=primaryRole

Or if you only want to know primaryRoles you can use a call like:
POST

‘https://sandbox.api.service.nhs.uk/organisation-data-terminology-api/fhir/ValueSet/$expand’

with body:
{
“resourceType”: “Parameters”,
“parameter”: [
{
“name”: “valueSet”,
“resource”: {
“resourceType”: “ValueSet”,
“compose”: {
“include”: [
{
“system”: “https://digital.nhs.uk/services/organisation-data-service/CodeSystem/ODSOrganisationRole”,
“filter”: [
{
“property”: “primaryRole”,
“op”: “=”,
“value”: “true”
}
]
}
]
}
}
}
]
}

But essentially at the moment it requires two calls to answer the question … and the results need to be ‘joined’ by the consumer.

3

Hello,

Thank you for your detailed reply. Apologies I don’t think my question was clear.

I’m trying to understand what uniquely defines a relationship - Does the combination of the two org codes, the relationship code (so example RE4) and the start and end dates make a unique combination? Or is it possible for two organisation to, for example, have two RE4 relationships at the same time as they have multiple roles?

Thanks

4

Apologies.
There is a unique relationship ID for every instance of a relationship. In ORD that was the uniqueRelId, whereas in the R4 OrganizationAffiliation resource that is the property ‘id’. I’ve highlighted in your example above:

image
image747×610 24.3 KB

5

An organisation having multiple roles will not cause them to have multiple relationships of the same type to the same org, as relationships are applied at organisation type/primary role level, and an org can only ever have one primary role (but zero to many non primary roles). Hope that helps clarify.

6

Thank you. That does answer my question.

Thanks for your help.