Updated May 16, 2024

This project is intended to be used from a parent application like unite-us/front-end or unite-us/uniteus-emr

Table of Contents

• Table of Contents
• Setup
  • For Frontend (WebApp) Parent project
  • For SmartApp (EMR) Parent project
• Architecture
• Usages in parent apps
• Testing
• Releases
  • How to update app-create-referral version in parent apps
  • When to update the version in parent apps?

Setup

To develop locally follow this steps:

1- Open a command line console:

  $ git clone https://github.com/unite-us-engineering/app-create-referral.git
  
  $ npm i && npm link && npm run build:dist:watch

This installs the packages, creates a link for this project (to be consumed from a parent app) and starts the server in watch mode. Development changes will trigger a rebuild and refresh the browser.

For Frontend (WebApp) Parent project

  // open a new terminal
  // from the folder in `front-end/packages/app-client`
  $ npm link @unite-us/app-create-referral
  $ npm start

• Go to http://localhost:8080 and log in as a user with the uup-459-superset-phase-2 feature flag enabled (ex: [email protected])
• Find the entrypoint you want to check, e.g from the Client Facesheet, click the Refer button, it should take you to the Search step and then land in the referral flow

For SmartApp (EMR) Parent project

  // open a new terminal
  // from the root folder in uniteus-emr project
  $ npm i
  $ npm link @unite-us/app-create-referral
  $ npm start

• Go to http://localhost:8081 and log in as a user with the uup-459-superset-phase-2 feature flag enabled (ex: [email protected])
• Find the entry point you want to check (e.g click the "Create Referral" button); it should take you to the Search step. Once you select program(s), click the "Added Resources" button to open the drawer and click the "Create Referrals" button to land in the referral flow.

Architecture

Please find the Technical Design Document to know about the project.

The application includes it's own Router and React Query Client. This allows us to use React Testing Library with Mock Service Workers (MswJS) for testing as an standalone app.

• __testUtils__/: Testing utils and mock server
• actions/: Custom api calls
• api/: Default hooks and axios instances setup
• common/: Common components (this can be merged with the components folder)
• components/: Components
• constants/: Constants
• context/: App Context to serve as source of truth of the data.
• hooks/: Custom hooks
• pages/: Pages components that relates to each route
• styles/: Custom scss files
• utils/: Utils functions

AppReferrals.js: This is the main component (entry point) of the app with the Router

Usages in parent apps

The AppReferrals component is wired up in AppClient and EMR in specific routes:

AppClient:

• <Route path="referrals/2/*" component={Referrals} />
• Points to: https://github.com/unite-us/front-end/blob/master/packages/app-client/src/pages/referrals/2/Referrals.jsx

 <AppReferrals
    // general settings, urls needed to build the axios instances
    appSettings={
      {
        env: {              
          getAuthToken,
          coreUrl: CORE_API,
          employeeId: currentEmployee?.id,
          providerId: currentEmployee?.provider.id,
          sharesUrl: SHARES_URL,
          consentUrl: CONSENT_APP_URL,
        },
        basename,
      }
    }
    
    // this will be set to the app context
    appState={{            
      currentEmployee,
      currentProvider,
      enums,
      source: 'app-client',
    }}

    // callbacks functions invoked in specific places throughout the app
    callbacks={{           
      notify: {
        error: (message) => Notifier.dispatch('error', message),
        success: (message) => Notifier.dispatch('success', message),
        warn: (message) => Notifier.dispatch('warning', message),
      },
      trackEventCallback: trackEvent,
      consent: {
        updateGlobalState,
      },
      onReferralCompleted: ({ hasOnlyOONReferrals }) => {
        browserHistory.push({
          pathname: hasOnlyOONReferrals ? '/dashboard/oon-cases/open' : '/dashboard/referrals/sent/all',
        });
      },
      onSaveDraftReferral: () => {
        browserHistory.push({
          pathname: '/dashboard/referrals/sent/draft',
        });
      },
      onSubmitConsent: async () => {
        // refresh ClientHeader to refetch person to show new consent status
        setShowHeader(false);
        setTimeout(() => {
          setShowHeader(true);
        });
      },
      onDeselectProgram: dispatchRemoveProgram,
      onClickSearchStep: (searchParams, selectedPrograms) => {
        dispatchRemoveAllPrograms();
        if (!isEmpty(selectedPrograms)) {
          dispatchAddPrograms(selectedPrograms);
        }

        const serializedSearchParams = serializeQueryParams(omitBy(searchParams, isNil));
        const search = serializedSearchParams ? `?${serializedSearchParams}` : '';

        browserHistory.push({
          pathname: '/referrals/create/add-resources',
          search,
        });
      },
      onClickBackFromBuilder: () => {
        let backUrl = `/referrals/create/add-resources?person=${personId}`;
        if (resourceListId) { backUrl += `&resource_list=${resourceListId}`; }

        browserHistory.replace(`${backUrl}&from-referral=true`);
      },
    }}

    // components as props to avoid adding dependencies inside the app-create-referral repo
    components={{
      consent: ConsentReferrals,
    }}
/>

//...

EMR:

• <Route path="referrals/2/*" components={Referrals} />
• Points to: https://github.com/unite-us/uniteus-emr/blob/master/src/pages/%5Bsession_id%5D/2/referrals/Referrals.jsx

In both WebApp and SmartApp, where the user navigates to the referral flow, we need to set the selectedPrograms, as in SupersetSearch.jsx

  ...
  const { dispatch } = useAppCreateReferralContext();

  const onClickNext = () => {
    const programsToUse = Object.keys(programToServiceTypesDict)
        .map((id) => ({ id, services: programToServiceTypesDict[id] }));

    // this sets the selected programs needed inside the referral flow
    dispatch(
      init({
        selectedPrograms: programsToUse,
        person: personId,
        resourceListId,
      }),
    );

    browserHistory.push({
      pathname: '/referrals/2/create/builder',
    });
  }

Testing

The app uses React Testing Library and Mock Service Worker (MswJS) for unit testing and integration testing across components.

/__testUtils__/: Includes the custom render using React Testing Library and the Mock Server that intercepts http requests during the tests

/pages/*/__tests__: Each page includes a folder with the tests for the screen.

Please review the existing tests and follow along to keep adding more scenarios as new features are being added.

Releases

There is Github Action configured for the main branch that will generate a new version after a PR has been merged into main, usually it's the latest commit in the history for the main branch, e.g:

Automated Version Bump [skip ci] bumps version to 0.1.85

The new version created is 0.1.85

How to update app-create-referral version in parent apps

There are a few steps:

1. Update the dependency in the corresponding package.json
2. Install the dependencies
3. Create the PR to merge the new version

• unite-us/front-end

  Update the package.json: https://github.com/unite-us/front-end/blob/master/packages/app-client/package.json

    "@unite-us/app-create-referral": "0.1.85"    

  • Open the terminal

    // from the root folder of the front-end repo, run yarn:
    $ yarn

  This will update the yarn.lock file with the new version, your PR to bump the version should include the package.json and the yarn.lock file changes, e.g: https://github.com/unite-us/front-end/pull/4522/files

• unite-us/uniteus-emr

  Update the package.json: https://github.com/unite-us/uniteus-emr/blob/master/package.json

      "@unite-us/app-create-referral": "0.1.85"    

  • Open the terminal

    $ npm i

This will update the package-lock.json file with the new version, your PR to bump the version should include the package.json and the package-lock.json file changes, e.g: https://github.com/unite-us/uniteus-emr/pull/1883/files

Finally, create a PR in the parent project to use the new version.

When to update the version in parent apps?

It depends on the release cadence and the speed to verify the features by the team; one approach could be keeping the parent apps with the latest versions at all times, shipping faster but also brings the risk of "untested" features might go into production because in very small timeframes probably the tester doesn't have time to verified the feature; and any team can do a release of the parent app with a version that you still dont want to make it to production.

Another more conservative approach could be to update the version only when the team is ready to test the features and ensured they will be tested in a short timeframe (before any team does a release) to avoid the risk mentioned above; this approach is potentially not as fast, but it should keep the production releases more controlled.

It's up to the team to decide the cadence and speed of the releases.