Important: The JavaScript SDK is a working example of how to wrap and use the DexCare API. The SDK is not currently among the supported products of DexCare - but can be used as a toolkit to gain understanding of the DexCare API and accelerate development.

Fluent SDK Reference

You can find detailed information on using the Fluent SDK methods here. For a basic overview of the complete SDK functionality, see our Getting Started section.

• Concepts
  • Selectors
  • Execution contexts and builders
• Selector reference
  • RetailDepartmentSelector
    • Syntax
    • Selecting all departments
    • Selecting all active departments
    • Selecting previously-retrieved departments
    • Selecting departments by URL name
    • Selecting departments within a given distance of a point
  • ProviderSelector
    • Selecting previously retrieved providers
    • Selecting providers by national ID
    • Selecting any provider in specified departments
    • Selecting all providers defined in the DexCare system
    • Selecting providers by other characteristics
  • VisitTypeSelector
    • Selecting previously-retrieved visit types
    • Selecting visit types by name
  • VirtualRegionSelector
    • Selecting all regions in the default practice
    • Selecting all regions in a specified practice
    • Selecting only active regions
    • Selecting regions by region code
    • Selecting regions by market
    • Selecting communications modalities in a region
• Execution context reference
  • RetailExecutionContextBuilder
    • General syntax
    • Obtaining appointment time slots
  • RetailExecutionContext
  • VirtualExecutionContextBuilder
    • General syntax
    • Obtaining virtual visit wait time
  • VirtualExecutionContext

Concepts

The Fluent SDK is based on two key concepts: selectors and execution contexts.

)

Selectors

Selectors help you qualify the information you want to retrieve from the DexCare system by ensuring that you use only valid option combinations. For example, the RetailDepartmentSelector selector can help you define criteria to select only departments within a certain radius of a specified locatio:

RetailDepartmentSelector
        .anyDepartmentWithin(
            appConfig.clinicSearchCriteria.radius,
            RadiusFilterUnits.MILES)
        .ofLocation(appConfig.clinicSearchCriteria.lat,
            appConfig.clinicSearchCriteria.long)
        .build()

or departments with a specific “URL name”:

RetailDepartmentSelector
        .forDepartmentWithUrlName('MyLocation')
        .build()

Other selectors, such as the VirtualRegionSelector, work the same way:

VirtualRegionSelector
        .forDefaultPractice()
        .withRegionCode('WA')
        .build()

The example above selects all virtual practice regions with the specified region code.

You’ll notice that at the end of each selector’s parameters is a method called build(). This completes the creation of the selector and validates all of the specified parameters, making it ready for executoin. It’s important to always include build() at the end of your selector; if you don’t, any operations using that selector will fail.

See the Selector reference section for information about the available selectors and their use.

Execution contexts and builders

Execution contexts are where the real magic happens in the Fluent SDK. Execution context builders use the information from selectors to create and execute requests to the DexCare API in the most efficient way possible, and return the data in an easy-to-use format via the execution context. Applications can then retrieve the data from the execution context and use it to satisfy various use cases.

Expanding on the earlier retail example, you can use a RetailExecutionContextBuilder with a RetailDepartmentSelector to retrieve information about the departments you need:

let ctx: RetailExecutionContext;
try {
    ctx = await sdk.getRetailExecutionContextBuilder()
        .forBrand(appConfig.brand)
        .forDepartments(
            RetailDepartmentSelector
                .anyDepartmentWithin(
                    appConfig.clinicSearchCriteria.radius,
                    RadiusFilterUnits.MILES)
                .ofLocation(appConfig.clinicSearchCriteria.lat,
                    appConfig.clinicSearchCriteria.long)
                .build()
        )
        .withAppointmentSlots()
        .build();
} catch (error) {
    console.log(`Unable to retrieve time slots for departments: ${error.message}`);
}

You can find more information in the Execution context reference section.

Selector reference

This section explains the various selectors available in the Fluent SDK and how they can be used.

RetailDepartmentSelector

Use a RetailDepartmentSelector to identify the retail departments you’d like to include in your query to the DexCare system.

Syntax

To create a RetailDepartmentSelector, use one of the following syntaxes:

Selecting all departments

RetailDepartmentSelector
    .forAllDepartments()
    .build();

Specifies that all retail departments are to be included, regardless of status. No parameters are required.

Selecting all active departments

RetailDepartmentSelector
    .forAllActiveDepartments()
    .build();

Specifies that all active retail departments are to be included. No parameters are required.

Selecting previously-retrieved departments

RetailDepartmentSelector
    .forDepartment(retailDepartmentArray)
    .build();

Specifies that one or more specific retail departments are to be included. Retail departments specified in this way are usually retrieved from a prior execution context.

Selecting departments by URL name

RetailDepartmentSelector
    .forDepartmentWithUrlName(urlName[, urlName, ... ,urlName])
    .build();

Specifies that one or more specific retail departments are to be included. The departments to be included are specified by their URL name, which is a short name assigned to the department when it is created. One or more names can be specified, separated by commas.

Selecting departments within a given distance of a point

RetailDepartmentSelector
    .anyDepartmentWithin(radius, unit)
    .of(latitude, longitude)
    .build();

RetailDepartmentSelector
    .anyActiveDepartmentWithin(radius, unit)
    .of(latitude, longitude)
    .build();

Specifies that one or more retail departments within a given radius of a specific geographic point are to be inclulded. The anyDepartmentWithin() version selects ALL departments; the anyActiveDepartmentWithin() version only selects active departments.

ProviderSelector

Use a ProviderSelector to identify the retail providers you’d like to include in your query to the DexCare system. By default, all providers in the selected retail departments are included.

Syntax

To create a ProviderSelector, use one of the following syntaxes:

Selecting previously-retrieved providers

ProviderSelector
    .forProvider(providerArray)
    .build();

Specifies that one or more specific retail providers are to be included. Retail providers specified in this way are usually retrieved from a prior execution context.

Selecting providers by national ID

ProviderSelector
    .forProviderWithNationalId(providerId[, providerId, ... ,providerId])
    .build();

Specifies that one or more specific retail providers are to be included. The providers to be included are specified by their national ID. One or more national IDs can be specified.

NOTE: Any providers you list here will be filtered depending on whether or not a RetailDepartmentSelector is specified. If you use a RetailDepartmentSelector that identifies specific departments, then the list of providers you specify here will be modified to include only those providers that work at the specified departments. If you do not specify a RetailDepartmentSelector, or if you specify one that includes forAllDepartments() or forAllActiveDepartments() then the complete list of providers will be included.

Selecting any provider in specified departments

ProviderSelector
    .forAnyProviderInSelectedDepartments()
    .build();

Specifies that one or more specific retail providers are to be included. The providers to be included are determined based on whether or not they provide services at departments specified in the execution context using a previous RetailDepartmentSelector selector.

Selecting all providers defined in the DexCare system

ProviderSelector
    .forAllProvidersInSystem()
    .build();

Specifies that all retail providers are to be included, including providers that may be inactive. This must be used in conjuction with a RetailDepartmentSelector.forAllDepartments() selector.

Selecting providers by other characteristics

ProviderSelector
    .forAnyProviderInSelectedDepartments()
    .whoIsActive()
    .whoIsAcceptingNewPatients()
    .whoAllowsOpenScheduling()
    .whoAllowsDirectScheduling()
    .whoHandlesVisitType(visitTypeName)
    .build();

Specifies that one or more retail providers are to be included, based on specific characteristics:

• whoIsActive() selects providers that are currently active.
• whoIsAcceptingNewPatients() selects providers that are currently accepting new patients.
• whoAllowsOpenScheduling() selects providers configured to allow open scheduling.
• whoAllowsDirectScheduling() selects providers configured to allow direct scheduling.
• whoHandlesVisitType(visitTypeName) selects providers that are configured to handle a particular visit type.

Any combination of these qualifying methods can be used, but in order to better qualify the specific providers to be selected they must be used in conjunction with one of the other forProvider... methods. Generally, these methods are applicable when used with forAnyProviderInSelectedDepartments(), since they allow the total list of providers for those departments to be further qualified according to whether they are accepting new patients, allow direct scheduling, etc.

VisitTypeSelector

Use a VisitTypeSelector to identify the visit types you’d like to include in your query to the DexCare system. By default, all visit types handled by the selected departments and providers are included.

Note that departments that do not handle the specified visit types are dropped from the selector.

Syntax

To create a VisitTypeSelector, use one of the following syntaxes:

Selecting all visit types

VisitTypeSelector
    .forAnyVisitType()
    .build();

Specifies that all of the visit types supported by selected departments and providers are to be included. Selected departments and providers are defined in the execution context, using RetailDepartmentSelector and ProviderSelector selectors. See the Execution context reference for details.

Selecting previously-retrieved visit types

VisitTypeSelector
    .forVisitType(visitTypeArray)
    .build();

Specifies that one or more specific visit types are to be included. Visit types specified in this way are usually retrieved from a prior execution context.

Selecting visit types by name

VisitTypeSelector
    .forVisitTypeWithName(visitTypeName[, visitTypeName, ... ,visitTypeName])
    .build();

Specifies that one or more specific visit types are to be included. The visit types to be selected are specified by their visitTypeName, which is a characteristic assigned when the visit type is created. One or more national IDs can be specified.

VirtualRegionSelector

Use a VirtualRegionSelector to identify the virtual practice regions you’d like to include in your query to the DexCare system. By default, all virtual practice region in the default practice are included.

Syntax

To create a VirtualRegionSelector, use one of the following syntaxes:

Selecting all virtual practice regions in the default practice

VirtualRegionSelector
    .forDefaultPractice()
    .build();

Specifies that all of the virtual practice regions defined in the default practice are included.

Selecting virtual practice regions in a specific practice ID

VirtualRegionSelector
    .forPracticeWithId(practiceId)
    .build();

Specifies that all of the virtual practice regions defined in the specified practice are included. Practice IDs are defined when a new practice is created in the DexCare system.

Selecting only active virtual practice regions in a specific practice ID

VirtualRegionSelector
    .forDefaultPractice()        // .forPracticeWithId() can also be used.
    .forOnlyActiveRegions()
    .build();

Selecting virtual practice regions with a specific region code

VirtualRegionSelector
    .forDefaultPractice()        // .forPracticeWithId() can also be used.
    .withRegionCode(regionCode)
    .build();

Specifies that the specific virtual practice regions with the specified region code are included. This method must be used with either forDefaultPractice() or forPracticeWithId() to further qualify the practice to be queried.

Selecting virtual practice regions with a specific market

VirtualRegionSelector
    .forDefaultPractice()        // .forPracticeWithId() can also be used.
    .withMarket(marketName)
    .build();

Specifies that the specific virtual practice regions in the specified market are included. This method must be used with either forDefaultPractice() or forPracticeWithId() to further qualify the practice to be queried.

If not specified, virtual practice regions in all markets are selected.

Selecting communication modalities in a virtual practice region

VirtualRegionSelector
    .forDefaultPractice()        // .forPracticeWithId() can also be used.
    .withModality(modalityName)
    .build();

Specifies that the specific virtual practice regions that support the named communications modality are included. Communications modalities define the method that providers use to communicate with patients; valid values include “phone”, “virtual”, or any other customer-defined modality. This method must be used with either forDefaultPractice() or forPracticeWithId() to further qualify the practice to be queried.

If not specified, all modalities are selected.

Execution context reference

This section explains how to retrieve data from the DexCare service using selectors.

Each care type (retail or virtual) has an associated “builder” which is used to create an execution context for that care type. The execution context builders are very similar in syntax and usage to selectors, so you’ll be able to become familiar quickly. Using a builder that is specific to your care type helps to validate your request and ensures that you specify the correct information needed to retrieve the data you want.

The correct builder for your care type can be obtained from one of the SDK’s DexCareSDK builder methods:

• DexCareSDK.getRetailSchedulingContextBuilder() creates a execution context builder for retail care
• DexCareSDK.getVirtualExecutionContextBuilder() creates a execution context builder for virtual visit care.

Each builder type only allows specific selectors. This is enforced at code compile time.

RetailExecutionContextBuilder

This builder creates and executes data requests to support retail care, including

• Identifying physical care locations (departments)
• Finding providers that are available to provide care, both in provider-specific and provider-agnostic scenarios
• Determining the correct visit type required
• Finding available time slots for care

The RetailExecutionContextBuilder creates a RetailExecutionContext using a combination of your SDK’s configuration values and values you specify in the builder itself. When you call the builder’s build() method, the builder formulates and executes DexCare API calls, and returns the results in the RetailExecutionContext. The RetailExecutionContext has methods that allow you to access the returned data in various ways.

General syntax

In general, the process for using the RetailExecutionContextBuilder is shown in the code fragment below.

// Define the SDK configuration
const sdkConfiguration: DexCareConfiguration = {
    apiEndpoint: "api.care.my-healthcare-system.com",
    ecvEndpoint: "ecvcare..my-healthcare-system.com",
    schedulingEndpoint: "scheduling.care.my-healthcare-system.com",
    practiceId: "12345",
    brand: "MyGreatBrand",
    domain: "MyDexCareDomain"
}

// Create an instance of the DexCare SDK
const sdk = DexCareSDKFactory.newInstance(SDKVersion.V1, sdkConfiguration);

// Create the execution context
let ctx: RetailExecutionContext;
try {
    const ctx = 
        await sdk.getRetailExecutionContextBuilder()
            .forBrand(brandName)
            .forDepartments(departmentSelector)  // required
            .forProviders(providerSelector)      // optional
            .forVisitTypes(visitTypeSelector)    // optional
            .build();

    // retrieve data from the 'ctx' execution context object and execute your application's logic
} catch (error) {
    // perform error processing
}

At a minimum, you must specify a value for the forDepartments() method. All other methods are optional or have appropriate default values.

Obtain appointment time slots

In addition to the methods shown above, two additional methods are available.

• The withAppointmentSlots() method adds appointment time slot availability info to the execution context. For each department, the appointment slots returned include available slots for every visit type applicable to that department.
• The withAppointmentSlotsForDates(startDate, endDate) method adds appointment time slot availability info for the specified date range to the execution context. The startDate and endDate are JavaScript Date objects.

The above methods are mutually exclusive.

RetailExecutionContext

As noted above, the RetailExecutionContextBuilder creates a RetailExecutionContext to hold the data returned from the DexCare API. This class provides additional properties and convenience methods that can be used to access the returned data.

VirtualExecutionContextBuilder

This builder creates and executes data requests to support virtual care, including

• Finding the appropriate virtual care practice region based on the patients residency and/or location
• Determining availability and wait time for virtual visits
• Invoking the appropriate virtual care scheduling application

The VirtualExecutionContextBuilder creates a VirtualExecutionContext using a combination of your SDK’s configuration values and values you specify in the builder itself. When you call the builder’s build() method, the builder formulates and executes DexCare API calls, and returns the results in the VirtualExecutionContext. The VirtualExecutionContext has methods that allow you to access the returned data in various ways.

General syntax

In general, the process for using the VirtualExecutionContextBuilder is shown in the code fragment below.

// Define the SDK configuration
const sdkConfiguration: DexCareConfiguration = {
    apiEndpoint: "api.care.my-healthcare-system.com",
    ecvEndpoint: "ecvcare..my-healthcare-system.com",
    schedulingEndpoint: "scheduling.care.my-healthcare-system.com",
    practiceId: "12345",
    brand: "MyGreatBrand",
    domain: "MyDexCareDomain"
}

// Create an instance of the DexCare SDK
const sdk = DexCareSDKFactory.newInstance(SDKVersion.V1, sdkConfiguration);

// Create the execution context
let ctx: VirtualExecutionContext;
try {
    const ctx = 
        await sdk.getVirtualExecutionContextBuilder()
            .forRegion(practiceRegionSelector)
            .build();

    // retrieve data from the 'ctx' execution context object and execute your application's logic
} catch (error) {
    // perform error processing
}

Obtain virtual visit wait time

By default, the VirtualExecutionContextBuilder will automatically retrieve virtual visit wait time and availability information for the virtual practice region / market combinations you specify. That information will be available in the VirtualExecutionContext object.

VirtualExecutionContext

As noted above, the VirtualExecutionContextBuilder creates a VirtualExecutionContext to hold the data returned from the DexCare API. This class provides additional properties and convenience methods that can be used to access the returned data.

In addition there is a special getWaitTimes(searchParams) method that allows you to filter the virtual visit wait times returned by the DexCare API in various ways. This method retrieves virtual region wait time and availability information, based on search parameters you provide. The searchParams argument represents an object that contains some or all of the following properties:

The code below provides a sample getWaitTime() request specifying regionCode and onlyActive parameters:

```js ctx.getWaitTimes( { regionCode: ‘WA’, onlyActive: true });