Review and updates for Location (#1001)

* formatting and updating examples for location * minor typo in parameters * removed id param on spec for name and org * param spec correction in location * param spec fix in location * PRODOC-202501: Style and formatting edits. * capitalization and linking to Organization --------- Co-authored-by: Deitrich, Casey <[email protected]>
cerner · Nov 3, 2023 · bcd02de · bcd02de
1 parent d5df796
commit bcd02de
Show file tree

Hide file tree

Showing 2 changed files with 88 additions and 164 deletions.
diff --git a/content/millennium/r4/base/entities/location.md b/content/millennium/r4/base/entities/location.md
@@ -9,15 +9,15 @@ title: Location | R4 API
 
 ## Overview
 
-The Location resource describes physical places where healthcare services are provided. In Millennium, facilities are the top level of the patient location hierarchy. A facility is also an Organization resource at which patient locations are associated. All facilities are organizations, but not all organizations are facilities. A location can also be an ambulatory patient care area like a clinic or an emergency room. The location hierarchy from highest to lowest is facility, building, nursing unit, room, and bed.
+The Location resource describes physical places where healthcare services are provided. In Cerner Millennium, facilities are the top level of the patient location hierarchy. A facility is also an [Organization](../Organization) resource that is associated with patient locations. All facilities are organizations, but not all organizations are facilities. A location can also be an ambulatory patient care area such as a clinic or an emergency room. The location hierarchy from highest to lowest is facility, building, nursing unit, room, and bed.
 
-* The following [HL7® FHIR® US Core Implementation Guide STU 4.0.0](https://hl7.org/fhir/us/core/STU4/){:target="_blank"} Profiles are supported by this resource:
+* This resource supports the following [HL7 FHIR US Core Implementation Guide STU 4.0.0](https://hl7.org/fhir/us/core/STU4/){:target="_blank"} profiles:
 
   * [US Core Location Profile](http://hl7.org/fhir/us/core/STU4/StructureDefinition-us-core-location.html){:target="_blank"}
 
 The following fields are returned if valued:
 
-* [Location id](http://hl7.org/fhir/r4/resource-definitions.html#Resource.id){:target="_blank"}
+* [Location ID](http://hl7.org/fhir/r4/resource-definitions.html#Resource.id){:target="_blank"}
 * [Status](http://hl7.org/fhir/R4/location-definitions.html#Location.status){:target="_blank"}
 * [Name](http://hl7.org/fhir/R4/location-definitions.html#Location.name){:target="_blank"}
 * [Alias](http://hl7.org/fhir/R4/location-definitions.html#Location.alias){:target="_blank"}
@@ -40,15 +40,15 @@ The following fields are returned if valued:
 
 ### Custom Extensions
 
-All URLs for custom extensions are defined as `https://fhir-ehr.cerner.com/r4/StructureDefinition/{id}`
+All URLs for custom extensions are defined as `https://fhir-ehr.cerner.com/r4/StructureDefinition/{id}`.
 
  ID                 | Value\[x] Type                    | Description
 --------------------|-----------------------------------|--------------------------------------------------------------------------------------------------------------------------------------
- `custom-attribute` | None (contains nested extensions) | A client defined custom attribute for the resource. Attribute values can be of type [`integer`], [`string`], or [`CodeableConcept`].
+ `custom-attribute` | None (contains nested extensions) | A client-defined custom attribute for the resource. Attribute values can be the following types: [`integer`], [`string`], or [`CodeableConcept`].
 
 ## Search
 
-Search for Locations that meet supplied query parameters:
+Search for locations that meet supplied query parameters:
 
     GET /Location?:parameters
 
@@ -60,24 +60,26 @@ Search for Locations that meet supplied query parameters:
 
  Name                 | Required?               | Type         | Description
 ----------------------|-------------------------|--------------|-------------------------------------------------------
- `_id`                | This or `-physicalType` | [`token`]    | The logical resource id associated with the resource.
- `-physicalType`      | This or `_id`           | [`token`]    | The location’s physical type. Example: `http://terminology.hl7.org/CodeSystem/location-physical-type|ro`
- `identifier`         | no                      | [`token`]    | The location’s identifier. Example: `653385|FSI^~BUILD^~NU` 
- [`_count`]           | no                      | [`number`]   | The maximum number of results to return. Defaults to `100`.
- `address`            | no                      | [`string`]   | A (part of the) address of the location.
- `address-city`       | no                      | [`string`]   | A city specified in an address
- `address-state`      | no                      | [`string`]   | A state specified in an address
- `address-postalcode` | no                      | [`string`]   | A postal code specified in an address
- `name`               | no                      | [`string`]   | A portion of the location's name or alias
- `organization`       | no                      | [`reference`]| Searches for locations that are managed by the provided organization
+ `_id`                | Conditionally           | [`token`]    | The logical resource ID associated with the resource. This parameter is required if the `-physicalType` parameter is not used.
+ `-physicalType`      | Conditionally           | [`token`]    | The location’s physical type. This parameter is required if the `_id` parameter is not used. Example: `http://terminology.hl7.org/CodeSystem/location-physical-type|ro`
+ `identifier`         | No                      | [`token`]    | The location’s identifier. Example: `653385|FSI^~BUILD^~NU` 
+ [`_count`]           | No                      | [`number`]   | The maximum number of results to return. Default: `100`
+ `address`            | No                      | [`string`]   | Part of the location's address. Example: `123%20Main`
+ `address-city`       | No                      | [`string`]   | The city specified in the address. Example: `Kansas`
+ `address-state`      | No                      | [`string`]   | The state specified in the address. Example: `MO`
+ `address-postalcode` | No                      | [`string`]   | The postal code specified in the address. Example: `64111`
+ `name`               | No                      | [`string`]   | The portion of the location's name or alias. Example: `Main`
+ `organization`       | No                      | [`reference`]| The Organization that manages the location. Example: `675844`
 
 
  Notes:
 
-- The `-physicalType` parameter
-  - Searching by Millennium proprietary codes is not supported.
-- The `-address-city` parameter
-  - needs address-state or address-postalcode while searching with address-city
+- When searching with the `-physicalType` parameter:
+  - Searching by Cerner Millennium proprietary codes is not supported.
+- When searching with the `-address-city` parameter:
+  - Must include any of the following parameters: `address-state` or `address-postalcode`.
+- When searching with the `name` and `organization` parameters:
+  - Must include any of the following parameters: `-physicalType`, `identifier`, `address`, `address-state`, `address-city`, or `address-postalcode`.
 
 ### Headers
 
@@ -113,7 +115,7 @@ Search for Locations that meet supplied query parameters:
 
 #### Request
 
-    GET https://fhir-open.cerner.com/r4/ec2458f2-1e24-41c8-b71b-0e701af7583d/Location?address=PA
+    GET https://fhir-open.cerner.com/r4/ec2458f2-1e24-41c8-b71b-0e701af7583d/Location?address=MO
 
 #### Response
 
@@ -126,7 +128,7 @@ Search for Locations that meet supplied query parameters:
 
 #### Request
 
-    GET https://fhir-open.cerner.com/r4/ec2458f2-1e24-41c8-b71b-0e701af7583d/Location?address-state=PA&address-city=Malvern
+    GET https://fhir-open.cerner.com/r4/ec2458f2-1e24-41c8-b71b-0e701af7583d/Location?address-state=MO&address-city=Kansas
 
 #### Response
 
@@ -152,7 +154,7 @@ Search for Locations that meet supplied query parameters:
 
 #### Request
 
-    GET https://fhir-open.cerner.com/r4/ec2458f2-1e24-41c8-b71b-0e701af7583d/Location?address=kansas&organization=3054032
+    GET https://fhir-open.cerner.com/r4/ec2458f2-1e24-41c8-b71b-0e701af7583d/Location?address=kansas&organization=667844
 
 #### Response
 
@@ -165,9 +167,9 @@ Search for Locations that meet supplied query parameters:
 
 The common [errors] and [OperationOutcomes] may be returned.
 
-## Retrieve by id
+## Retrieve by ID
 
-List an individual Location by its id:
+List an individual location by the associated ID:
 
     GET /Location/:id
 

diff --git a/lib/resources/example_json/r4_examples_location.rb b/lib/resources/example_json/r4_examples_location.rb
@@ -112,85 +112,79 @@ module Resources
     }.freeze
 
     R4_LOCATION_ADDRESS_ENTRY ||= {
-      "resourceType": 'Location',
-      "id": '982243103',
-      "meta": {
-        "versionId": '0',
-        "lastUpdated": '2019-03-29T14:40:50Z'
-      },
-      "text": {
-        "status": 'generated',
-        "div": '<div xmlns="http://www.w3.org/1999/xhtml"><p><b>Location</b></p><p><b>Name</b>: '\
-        'Anushka Org One</p><p><b>Alias</b>: ADOne</p><p><b>Managing Organization</b>: Anushka Org One</p>'\
-        '<p><b>Physical Type</b>: Facility(s)</p><p><b>Status</b>: Active</p></div>'
-      },
-      "identifier": [
-        {
-          "use": 'official',
-          "type": {
-            "coding": [
-              "system": 'https://fhir.cerner.com/ec2458f2-1e24-41c8-b71b-0e701af7583d/codeSet/73',
-              "code": 'ACCTRECEIVABLE',
-              "display": 'FIN NBR',
-              "userSelected": true
-            ]
-          },
-          "system": 'FIN NBR',
-          "value": '16000'
-        }
-      ],
-      "status": 'active',
-      "name": 'Anushka Org One',
-      "alias": [
-        'ADOne'
-      ],
-      "mode": 'instance',
-      "address": {
-        "use": 'work',
-        "text": "111th West st\nMalvern, PA 19355\nUSA",
-        "line": [
-          '111th West st'
+      "fullUrl": 'https://fhir-open.cerner.com/r4/ec2458f2-1e24-41c8-b71b-0e701af7583d/Location/20573078',
+      "resource": {
+        "resourceType": 'Location',
+        "id": '20573078',
+        "meta": {
+          "versionId": '20',
+          "lastUpdated": '2018-05-22T16:42:00Z'
+        },
+        "text": {
+          "status": 'generated',
+          # rubocop:disable Layout/LineLength
+          "div": '<div xmlns=\"http://www.w3.org/1999/xhtml\"><p><b>Location</b></p><p><b>Name</b>: Model Behavioral Health Clinic</p><p><b>Alias</b>: MX BH CL</p><p><b>Managing Organization</b>: Model Behavioral Health Clinic</p><p><b>Physical Type</b>: Facility(s)</p><p><b>Status</b>: Active</p></div>'
+          # rubocop:enable Layout/LineLength
+        },
+        "status": 'active',
+        "name": 'Model Behavioral Health Clinic',
+        "alias": [
+          'MX BH CL'
         ],
-        "city": 'Malvern',
-        "state": 'PA',
-        "postalCode": '19355',
-        "country": 'USA'
-      },
-      "physicalType": {
-        "coding": [
+        "mode": 'instance',
+        "telecom": [
           {
-            "system": 'https://fhir.cerner.com/ec2458f2-1e24-41c8-b71b-0e701af7583d/codeSet/222',
-            "code": '783',
-            "display": 'Facility(s)',
-            "userSelected": true
-          },
-          {
-            "system": 'http://terminology.hl7.org/CodeSystem/location-physical-type',
-            "code": 'si',
-            "display": 'Site'
+            "system": 'phone',
+            "value": '555 555 0001'
           }
         ],
-        "text": 'Facility(s)'
-      },
-      "managingOrganization": {
-        "reference": 'Organization/28096355',
-        "display": 'Anushka Org One'
+        "address": {
+          "use": 'work',
+          "text": '1234 Main\nKansas City, MO 64111\nUS',
+          "line": [
+            '1234 Main'
+          ],
+          "city": 'Kansas City',
+          "state": 'MO',
+          "postalCode": '64111',
+          "country": 'US'
+        },
+        "physicalType": {
+          "coding": [
+            {
+              "system": 'https://fhir.cerner.com/ec2458f2-1e24-41c8-b71b-0e701af7583d/codeSet/222',
+              "code": '783',
+              "display": 'Facility(s)',
+              "userSelected": true
+            },
+            {
+              "system": 'http://terminology.hl7.org/CodeSystem/location-physical-type',
+              "code": 'si',
+              "display": 'Site'
+            }
+          ],
+          "text": 'Facility(s)'
+        },
+        "managingOrganization": {
+          "reference": 'Organization/667844',
+          "display": 'Model Behavioral Health Clinic'
+        }
       }
     }.freeze
 
     R4_LOCATION_ADDRESS_BUNDLE ||= {
       "resourceType": 'Bundle',
-      "id": 'f4749f7a-e67d-49d1-8b92-ddbef46eae15',
+      "id": 'd7638736-7e04-4e36-9fd1-357159396499',
       "type": 'searchset',
       "link": [
         {
           "relation": 'self',
-          "url": 'https://fhir-open.cerner.com/r4/ec2458f2-1e24-41c8-b71b-0e701af7583d/Location?address=PA'
+          "url": 'https://fhir-open.cerner.com/r4/ec2458f2-1e24-41c8-b71b-0e701af7583d/Location?address=MO'
         }
       ],
       "entry": [
         {
-          "fullUrl": 'https://fhir-open.cerner.com/r4/ec2458f2-1e24-41c8-b71b-0e701af7583d/Location?address=PA',
+          "fullUrl": 'https://fhir-open.cerner.com/r4/ec2458f2-1e24-41c8-b71b-0e701af7583d/Location?address=MO',
           "resource": R4_LOCATION_ADDRESS_ENTRY
         }
       ]
@@ -203,12 +197,12 @@ module Resources
       "link": [
         {
           "relation": 'self',
-          "url": 'https://fhir-open.cerner.com/r4/ec2458f2-1e24-41c8-b71b-0e701af7583d/Location?address-state=PA&address-city=Malvern'
+          "url": 'https://fhir-open.cerner.com/r4/ec2458f2-1e24-41c8-b71b-0e701af7583d/Location?address-state=MO&address-city=Kansas'
         }
       ],
       "entry": [
         {
-          "fullUrl": 'https://fhir-open.cerner.com/r4/ec2458f2-1e24-41c8-b71b-0e701af7583d/Location?address-state=PA&address-city=Malvern',
+          "fullUrl": 'https://fhir-open.cerner.com/r4/ec2458f2-1e24-41c8-b71b-0e701af7583d/Location?address-state=MO&address-city=Kansas',
           "resource": R4_LOCATION_ADDRESS_ENTRY
         }
       ]
@@ -311,85 +305,13 @@ module Resources
       "link": [
         {
           "relation": 'self',
-          "url": 'https://fhir-open.cerner.com/r4/ec2458f2-1e24-41c8-b71b-0e701af7583d/Location?address=kansas&organization=3054032'
+          "url": 'https://fhir-open.cerner.com/r4/ec2458f2-1e24-41c8-b71b-0e701af7583d/Location?address=kansas&organization=667844'
         }
       ],
       "entry": [
         {
-          "fullUrl": 'https://fhir-open.cerner.com/r4/ec2458f2-1e24-41c8-b71b-0e701af7583d/Location/2554914033',
-          "resource": {
-            "resourceType": 'Location',
-            "id": '2554914033',
-            "meta": {
-              "versionId": '0',
-              "lastUpdated": '2017-09-19T17:38:08Z'
-            },
-            "text": {
-              "status": 'generated',
-              "div": '<div xmlns="http://www.w3.org/1999/xhtml"><p><b>Location</b></p>'\
-              '<p><b>Name</b>: ABC Taxi Company</p><p><b>Alias</b>: ABC Taxi</p>'\
-              '<p><b>Managing Organization</b>: ABC Taxi Company</p>'\
-              '<p><b>Physical Type</b>: Facility(s)</p><p><b>Status</b>: Active</p></div>'
-            },
-            "identifier": [
-              {
-                "use": 'official',
-                "type": {
-                  "coding": [
-                    "system": 'https://fhir.cerner.com/ec2458f2-1e24-41c8-b71b-0e701af7583d/codeSet/73',
-                    "code": 'ACCTRECEIVABLE',
-                    "display": 'FIN NBR',
-                    "userSelected": true
-                  ]
-                },
-                "system": 'FIN NBR',
-                "value": '16000'
-              }
-            ],
-            "status": 'active',
-            "name": 'ABC Taxi Company',
-            "alias": [
-              'ABC Taxi'
-            ],
-            "mode": 'instance',
-            "telecom": [
-              {
-                "system": 'phone',
-                "value": '8168769999'
-              }
-            ],
-            "address": {
-              "use": 'work',
-              "text": "123 Main Street\nKansas City, MO 64117\nUS",
-              "line": [
-                '123 Main Street'
-              ],
-              "city": 'Kansas City',
-              "state": 'MO',
-              "postalCode": '64117',
-              "country": 'US'
-            },
-            "physicalType": {
-              "coding": [
-                {
-                  "system": 'https://fhir.cerner.com/ec2458f2-1e24-41c8-b71b-0e701af7583d/codeSet/222',
-                  "code": '783',
-                  "display": 'Facility(s)',
-                  "userSelected": true
-                },
-                {
-                  "system": 'http://terminology.hl7.org/CodeSystem/location-physical-type',
-                  "code": 'si',
-                  "display": 'Site'
-                }
-              ],
-              "text": 'Facility(s)'
-            },
-            "managingOrganization": {
-              "reference": 'Organization/3054032',
-              "display": 'ABC Taxi Company'
-            }
-          }
+          "fullUrl": 'https://fhir-open.cerner.com/r4/ec2458f2-1e24-41c8-b71b-0e701af7583d/Location/20573078',
+          "resource": R4_LOCATION_ADDRESS_ENTRY
         }
       ]
     }.freeze