Newer Version Available

This content describes an older version of this product. View Latest

Intelligent Appointment Management Operations

The available operations for Intelligent Appointment Management include finding available appointment time slots, determining the status of an appointment slot, creating an appointment, getting a scheduled appointment, and canceling an appointment.

The URL for each operation is formed from two parts:

Protocol + Domain

This is defined in a Named Credential for appointment management.

Create a named credential in Setup.
The name of the credential must be Appointment_Management.
Associate the named credential with Intelligent Appointment Management in Setup under Intelligent Appointment Management Configuration.

Path

For each operation this defines the URI path following the value obtained from the Named Credential.

Each operation uses the default URI paths shown below. The default URI path for each operation can be overridden in Setup under Intelligent Appointment Management URL Configuration. If you override default URI paths with custom URIs, make corresponding changes in a custom Apex class that connects with your electronic health record (EHR) system’s middleware. Consistency between custom URI paths and custom Apex ensures that data from each endpoint is parsed as expected.

The comments in these JSON samples are for documentation purposes only and aren’t meant to be valid JSON.

Note

Find Available Time Slots for an Appointment

When a call center agent wants to schedule an appointment, the first step is to find the available time slots for providers who match the patient’s needs. The call center agent gathers selection criteria and then initiates a search to obtain the available slots for providers who match the criteria.

Type: Controller
Verb: POST
Default URL Path: <base-url>/Slot/_search
Content-Type (Header): application/x-www-form-urlencoded

Your Base URL is configured in Setup > Appointment Scheduling.

All communications with the external system use the FHIR R4 standard.

Request Body

1schedule:Schedule.actor:Practitioner.identifier=http://hl7.org/fhir/sid/us-npi|323,434,567,342,234,224,423
2&schedule:Schedule.actor:Location._id=epic|555,epic|123,allscripts|124,allscripts|221,cerner|222,cerner|223,athena|331,athena|332
3&schedule:Schedule.actor:Practitioner._id=epic|2342342,&start=ge2020-10-10
4&start=le2021-03-31&appointment-type=epic|ROUTINE,epic|ROUTINE,cerner|RTN,athena|REGULAR
5&service-type=epic|H999,cerner|E100,athena|C200,allscripts|A300
6&status=free
7&_include=Slot:schedule
8&_sort=start

The request payload is sent as single line. It is listed here in separate lines for readability.

Note

Multiple Source Systems

If you are working with more than one source system, the Location._id gets the source system name and ID in pipe-delimited pairs, separated by commas, like this:

1schedule:Schedule.actor:Location._id=epic|1404774,cerner|1476569

For a single source system, the Location._id is the ID only, like this:

1schedule:Schedule.actor:Location._id=1404774,1476569

Response Codes

200: Success
400: Bad request
401: Unauthorized
5xx: Server error

Response Body

To map slots, resource, resourceType, id, schedule, actor, start, and end are required in the FHIR response.
Response is a map keyed by CareProvider.careProviderId to give all available slots within the start/end range for a single practitioner+facility pair that can fulfill an appointment for the serviceTypeCode+appointmentTypeCode.
If a practitioner+facility pair is not found in the source system, the provider is ignored and nothing is returned for that careProviderId. If a practitioner+facility pair does not have availability that matches the slot range and codes, the careProviderId is returned without any slots.
By default, the list of returned slots for each provider is sorted by date/time in ascending order.
The sourceSlotId for a slot is the ID of a time slot in the source system for a care provider (eg. practitioner+facility) that can fulfill a specific serviceTypeCode+appointmentTypeCode. Given this ID during appointment booking, the source system is able to identify the practitioner, facility, time slot, service type and appointment type.

1{
2"resourceType": "Bundle",
3"id": "",
4"meta": {"lastUpdated":},
5"type": "searchset",
6"total": n,
7"entry": [    
8    "fullUrl" : ""    ,
9    "resource" : {     
10        "resourceType" : "Slot",    
11        "id" : "<String>",
12        "identifier" : [{ Identifier }],     
13        "serviceCategory" : [{ CodeableConcept }],     
14        "serviceType" : [{ CodeableConcept }],     
15        "specialty" : [{ CodeableConcept }],     
16        "appointmentType" : { CodeableConcept },    
17        "schedule" : { Reference(Schedule) }, //expects to get actor in this object
18        "status" : "<code>",    
19        "start" : "<instant>",    
20        "end" : "<instant>",    
21        "overbooked" : <boolean>,    
22        "comment" : "<string>"    
23     } 
24    ]
25}

Error Response for Multiple Source Systems

1{
2      "resourceType": "Bundle",
3      .......
4      "entry": [
5      {
6      "fullUrl": "http://hapi.fhir.org/baseR4/Slot/1939809",
7      "resource": {
8      "resourceType": "Slot",
9      .......
10      },
11      "search": {"mode": "match"}
12      },
13      {
14      "fullUrl": "http://hapi.fhir.org/baseR4/Schedule/1939822",
15      "resource": {
16      "resourceType": "Schedule",
17      "id": "1939822",
18      .....
19      },
20      "search": {"mode": "include"}
21      },
22      { //If the targeting system is FHIR R4, you get OperationOutcome resource as error. Pass it back with one of the elements in "Bundle.entry" and "extension" to identify the target system.
23      "resourceType": "OperationOutcome",
24      ....
25      "extension" : [{
26      "url" : "https://fhir-ehr-code.cerner.com/r4/ec2458f2-1e24-41c8-b71b-0e701af7583d/Slot/_search33",
27      "value" : "cerner"
28      }]
29      "issue": [ {
30      "severity": "error",
31      "code": "processing",
32      "diagnostics": "Invalid request: The FHIR endpoint on this server does not know how to handle GET operation[Slot/_search33] with parameters [[_include, _pretty, schedule:Schedule.actor:Practitioner.identifier, appointment-type, service-type, schedule:Schedule.actor:Practitioner._id, schedule:Schedule.actor:Location._id]]"
33      }
34      ]
35      }
36      ]
37      }

Identifier

1{
2  "use" : "<code>", // usual | official | temp | secondary | old (If known)
3  "type" : { CodeableConcept },  // OPTIONAL  Description of identifier
4  "system" : "<uri>", // The namespace for the identifier value
5  "value" : "$lt;string>", // The value that is unique
6  "period" : { Period }, // OPTIONAL Time period when id is/was valid for use
7  "assigner" : { Reference(Organization) }  // OPTIONAL  Organization that issued id (may be just text)
8}

CodeableConcept

1{
2  // from Element: extension
3  "coding" : [{ Coding }], // Code defined by a terminology system
4  "text" : "<string>" // Plain text representation of the concept
5}

Coding

1{ 
2  "system" : "<uri>", // Identity of the terminology system
3  "version" : "<string>",  // OPTIONAL  Version of the system - if relevant
4  "code" : "<code>", // Symbol in syntax defined by the system
5  "display" : "<string>", // Representation defined by the system
6  "userSelected" : <boolean>  // OPTIONAL  If this coding was chosen directly by the user
7}

Get Slot Status

Type: Resource
Verb: GET
Default URL Path for Single-Source System: <base-url>/Slot/{sourceSlotId}
Default URL Path for Multi-Source System: <base-url>/Slot/{sourceSystem}/{sourceSlotId}

Where:

sourceSystem identifies the source system.
sourceSlotId is the ID of a time slot in the SourceSystem returned from the Find Available Slots operation.

Your Base URL is configured in Setup > Appointment Scheduling.

All communications with the external system use the FHIR R4 standard.

Response Codes

200: Success
401: Unauthorized
404: Slot not found
5xx: Server error

Response Body

To map slots, resourceType, id, status, start, and end are required in the FHIR response.

1{     
2        "resourceType" : "Slot",    
3        "id" : "<string>"
4        "identifier" : [{ Identifier }],     
5        "serviceCategory" : [{ CodeableConcept }],     
6        "serviceType" : [{ CodeableConcept }],     
7        "specialty" : [{ CodeableConcept }],     
8        "appointmentType" : { CodeableConcept },    
9        "schedule" : { Reference(Schedule) },//As we are passing _include=Slot:schedule in query, it should include the "Schedule" resource as one of the item in "entry" field. 
10        "status" : "<code>",    
11        "start" : "<instant>",    
12        "end" : "<instant>",    
13        "overbooked" : <boolean>,    
14        "comment" : "<string>"    
15 }

The valid values for slotStatus are:

busy
free
busy-unavailable
busy-tentative
entered-in-error

Create Appointment

When the patient selects an available slot, the call center agent books the appointment, which triggers a Get Slot Status REST call to the EHR system.

Health Cloud makes a Get Slot Status REST call.
An error is displayed to the call center agent if the slot is no longer available.
Health Cloud creates a Service Appointment record and a Healthcare Practitioner Facility Appointment junction between the Service Appointment and Healthcare Practitioner Facility.
Health Cloud makes a Create (Book) Appointment REST call.
- Service Appointment is updated with the response.
- An error is displayed to the call center agent if the booking is rejected.

Type: Resource
Verb: POST
Default URL Path: [base]/Appointment/[sourceSystem]

Your Base URL is configured in Setup > Appointment Scheduling.

All communications with the external system use the FHIR R4 standard.

Request Body

The resourceType, identifier, cancelationReason, serviceType, appointmentType, slot, comment, and status are the minimum required fields in the request that Health Cloud sends.

1{
2    "resourceType" : "Appointment",
3    "identifier" : [{ Identifier }], //See Note below
4    "cancelationReason" : { CodeableConcept },
5    "serviceType" : [{ CodeableConcept }], // From WorkType --> AppointmentType
6    "appointmentType" : { CodeableConcept }, // From WorkType --> serviceType
7    "slot" : [{ Reference(Slot) }], //Health Cloud sends the slot ID received from the Find Slots API response.
8    "comment" : "<string>",
9    "participant" : [{"type" : [{ CodeableConcept }], //Health Cloud sends sourcePatientId 
10    "actor" : { Reference(Patient|Practitioner|PractitionerRole|RelatedPerson
11    | Device|HealthcareService|Location) }, //Health Cloud sends the source practitioner id
12    "status" : "<code>", 
13      ]
14}

For "identifier," Health Cloud sends 3 records:

Salesforce unique appointment id
Salesforce unique patient id
Source system (for multi-source systems only)

Note

Response Codes

200: Success
400: Bad request
401: Unauthorized
404: Slot or patient not found
5xx: Server error

Response Body

To map slots, resourceType, id, identifier, serviceType, appointmentType, slot, participant, actor, and status are required in the FHIR response.

1{
2    "resourceType" : "Appointment",
3    "id" : "<string>"
4    "identifier" : [{ Identifier }], //Source system identifier mandatory in the response if there are multiple source systems
5    "cancelationReason" : { CodeableConcept },
6    "serviceCategory" : [{ CodeableConcept }],
7    "serviceType" : [{ CodeableConcept }],
8    "specialty" : [{ CodeableConcept }],
9    "appointmentType" : { CodeableConcept },
10    "reasonCode" : [{ CodeableConcept }],
11    "reasonReference" : [{ Reference(Condition|Procedure|Observation|ImmunizationRecommendation) }],
12    "priority" : "<unsignedInt>",
13    "description" : "<string>", 
14    "supportingInformation" : [{ Reference(Any) }],
15    "start" : "<instant>",// start of the appointment - ISO 8601 format
16    "end" : "<instant>",// end of the appointment - ISO 8601 format
17    "minutesDuration" : "<positiveInt>",
18    "slot" : [{ Reference(Slot) }],
19    "created" : "<dateTime>",
20    "comment" : "<string>",
21    "patientInstruction" : "<string>",
22    "basedOn" : [{ Reference(ServiceRequest) }],
23    "participant" : [{"type" : [{ CodeableConcept }],//Patient EHR id
24    "actor" : { Reference(Patient|Practitioner|PractitionerRole|RelatedPerson | Device|HealthcareService|Location) }, //Practitioner EHR id
25    "required" : "<code>",
26    "status" : "<code>", // Mandatory in the response
27    "period" : { Period }}],
28    "requestedPeriod" : [{ Period }
29    ]
30}

"Cancelation" is spelled with one L, per the FHIR R4 specification.

Note

The valid values for status are:

proposed
pending
booked
arrived
fulfilled
cancelled
noshow
entered-in-error
checked-in
waitlist

If the request cannot be processed for any reason (e.g. it’s unsupported, there’s a timeout, etc.) status is returned as proposed.

Cancel Appointment

Type: Controller
Verb: POST
Default URL Path for Single-Source System: <base-url>/Appointment/{sourceAppointmentId}
Default URL Path for Multi-Source System:* <base-url>/Appointment/{sourceSystem}/{sourceAppointmentId}

Where:

sourceSystem identifies the source system.
sourceAppointmentId is the ID of an appointment in the source system.

Your Base URL is configured in Setup > Appointment Scheduling.

All communications with the external system use the FHIR R4 standard.

Request Body

1{
2         "resourceType": "Appointment",
3         "id": "1839594",
4         "status": "cancelled",
5         "cancelationReason" : {
6         "coding" : [
7         {
8         "system" : "http://terminology.hl7.org/CodeSystem/appointment-cancellation-reason",
9         "code" : "pat-mv"
10         }
11         ]
12         }
13         }

Response Codes

200: Success
401: Unauthorized
404: Appointment not found
5xx: Server error

To map slots, resourceType, id, identifier, serviceType, appointmentType, slot, participant, actor, and status are required in the FHIR response.

1{
2    "resourceType" : "Appointment",
3    "id" : "<string>"
4    "identifier" : [{ Identifier }], //Source system identifier mandatory in the response if there are multiple source systems
5    "cancelationReason" : { CodeableConcept },
6    "serviceCategory" : [{ CodeableConcept }],
7    "serviceType" : [{ CodeableConcept }],
8    "specialty" : [{ CodeableConcept }],
9    "appointmentType" : { CodeableConcept },
10    "reasonCode" : [{ CodeableConcept }],
11    "reasonReference" : [{ Reference(Condition|Procedure|Observation|ImmunizationRecommendation) }],
12    "priority" : "<unsignedInt>",
13    "description" : "<string>", 
14    "supportingInformation" : [{ Reference(Any) }],
15    "start" : "<instant>",// start of the appointment - ISO 8601 format
16    "end" : "<instant>",// end of the appointment - ISO 8601 format
17    "minutesDuration" : "<positiveInt>",
18    "slot" : [{ Reference(Slot) }],
19    "created" : "<dateTime>",
20    "comment" : "<string>",
21    "patientInstruction" : "<string>",
22    "basedOn" : [{ Reference(ServiceRequest) }],
23    "participant" : [{"type" : [{ CodeableConcept }],//Patient EHR id
24    "actor" : { Reference(Patient|Practitioner|PractitionerRole|RelatedPerson | Device|HealthcareService|Location) }, //Practitioner EHR id
25    "required" : "<code>",
26    "status" : "<code>", // Mandatory in the response
27    "period" : { Period }}],
28    "requestedPeriod" : [{ Period }
29    ]
30}

"Cancelation" is spelled with one L, per the FHIR R4 specification.

Note

The valid values for status are:

proposed
pending
booked
arrived
fulfilled
cancelled
noshow
entered-in-error
checked-in
waitlist

If the request cannot be processed for any reason (e.g. it’s unsupported, there’s a timeout, etc.) status is returned as proposed.

Salesforce Health Cloud Developer Guide

Intelligent Appointment Management Operations

Find Available Time Slots for an Appointment

Request Body

Multiple Source Systems

Response Codes

Response Body

Error Response for Multiple Source Systems

Identifier

CodeableConcept

Coding

See Also

Get Slot Status

Response Codes

Response Body

See Also

Create Appointment

Request Body

Response Codes

Response Body

See Also

Cancel Appointment

Request Body

Response Codes

See Also