Launching Workspaces

Use launchWorkspace2 from @openmrs/esm-framework to open a workspace.

import { launchWorkspace2 } from '@openmrs/esm-framework';
 
const MyComponent = ({ patientUuid }) => {
  const openGastrodynamics = () => {
    void launchWorkspace2('gastrodynamics-form-workspace', {
      patientUuid,
    });
  };
 
  return <button onClick={openGastrodynamics}>Open gastrodynamics</button>;
};

The full signature is:

launchWorkspace2<WorkspaceProps, WindowProps, GroupProps>(
  workspaceName,
  workspaceProps,
  windowProps,
  groupProps,
);

• workspaceProps are passed to the workspace component as workspaceProps.
• windowProps are shared by workspaces in the same window.
• groupProps are shared by all windows and workspaces in the same group.
• null or omitted props are considered compatible with existing props.

launchWorkspace2 returns a Promise<boolean>. It resolves to true when the workspace is launched or restored, and false when the user cancels a required close confirmation.

Patient Workspaces That Require Visits

For patient workspaces that require an active visit, use useLaunchWorkspaceRequiringVisit from @openmrs/esm-patient-common-lib.

import React from 'react';
import { Button } from '@carbon/react';
import { useTranslation } from 'react-i18next';
import { useLaunchWorkspaceRequiringVisit } from '@openmrs/esm-patient-common-lib';
 
const OrderBasketActionButton = ({ patientUuid }) => {
  const { t } = useTranslation();
  const launchOrderBasket = useLaunchWorkspaceRequiringVisit(patientUuid, 'order-basket');
 
  return <Button onClick={() => launchOrderBasket()}>{t('launchOrderBasket', 'Launch order basket')}</Button>;
};
 
export default OrderBasketActionButton;

If visits are enabled and the patient has no active visit, O3 prompts the user to start or select a visit before launching the workspace.

Behavior

launchWorkspace2 follows the workspace v2 group and window model:

1. If the target group is not open, O3 opens the group, opens the target window, and renders the requested workspace.
2. If another group is open, or if the existing group props are incompatible, O3 checks the affected workspaces for unsaved changes, prompts when needed, and then closes the current group and its windows.
3. If the target window is already open with compatible window props, launching an already-open workspace with compatible workspace props restores that window.
4. If the target window or workspace has incompatible props, O3 checks for unsaved changes before closing the window and opening a fresh instance.
5. launchWorkspace2 does not create child workspaces. From inside a workspace, use the launchChildWorkspace prop supplied by Workspace2DefinitionProps.

Workspace titles are set by the <Workspace2 title="..."> wrapper. The v1 workspaceTitle launch option is not used by workspace v2.