@procore/labs-custom-workflows v3.17.0

Custom Workflows

Provides custom workflows capabilities to procore tools

Background

Creating an interactive UI to connect all stakeholders in construction to review/approve work items with automated tasks to reduce manual work and increase overall efficiency.

Start here to learn more about workflows.

Installation

yarn add @procore/labs-custom-workflows

This package requires Node 12+.

Dependencies

The following packages are listed as external peer dependencies:

• @procore/core-react
• @procore/core-icons
• @procore/labs-toast-alert
• react
• react-dom
• styled-components

The package will not bundle the code, and requires the app client to provide it as a dependency. The external peer dep is to assure React Context is consistent in a client's React tree, the child consumers can reference the correct parent provider. If the package uses latest features or bug fixes and a new minimum version of core-react is required, it should be considered a breaking change as the peer dependency version must be met.

Usage

useFetchWorkflowTransitionStatus

A custom hook to fetch the current workflow version/transition status of the specified tool type. This hook consumes the workflow's transition status API.

Provide companyId and workflowableType.

useFetchEnabledWorkflowableTypes

A custom hook to fetch workflowable object types enabled for workflows v2. It is recommended to use this hook with WorkflowToolSettings component. See code snippet exmaple below.

Provide companyId and workflowableTypes.

Workflow Tool Settings

A preset configuration table that returns available presets associated with the provided project id and workflowable object type to handle configuring workflow instances (Storybook).

Prerequisite

You will need to create a PR to add and configure your tool's workflowable object type here for the backend.

Example

import { I18nProvider, Spinner } from '@procore/core-react';
import { ToastAlertProvider } from '@procore/labs-toast-alert';
import {
  WorkflowToolSettings,
  useFetchEnabledWorkflowableTypes,
} from '@procore/labs-custom-workflows';

const workflowableObjectType = 'Billings::Requisition';

const {
  isLoading,
  enabledWorkflowableTypes,
} = useFetchEnabledWorkflowableTypes({
  companyId,
  workflowableTypes: [workflowableObjectType],
});

const showWorkflowSettings = enabledWorkflowableTypes.includes(
  workflowableObjectType
);

if (isLoading) {
  return <Spinner />;
}

if (!showWorkflowSettings) {
  return null;
}

return (
  <I18nProvider>
    <ToastAlertProvider>
      <WorkflowToolSettings
        companyId={1}
        projectId={2}
        workflowableType={workflowableObjectType}
        filters={{ classification: '-1' }}
      />
    </ToastAlertProvider>
  </I18nProvider>
);

Workflow Popover

A popover to get contextual details about an item’s workflow status. The data to hydrate this component is provided (here).

Example

import { WorkflowPopover } from '@procore/labs-custom-workflows';

<I18nProvider>
  <ZIndex>
    <WorkflowPopover
      currentStepOccurrence={{
        name: 'Financial Review',
        due_at: '2022-06-01T18:02:00.550Z',
      }}
      item={{
        name: 'Invoice #123',
        url:
          'https:/app.procore.com/1/project/commitments/work_order_contracts/1/requisitions/1',
      }}
      timeZone={'America/Los_Angeles'}
      urgency={2} // 0 - Blocked, 1 - Overdue, 2 - Warning, 3 - InProgress, 4 - Complete
      urgencyMessage={'Due today'}
      workflowManager={{
        name: 'Marcia Example',
        login: 'marcia@example.com',
        job_title: 'Project Manager',
      }}
    />
  </ZIndex>
</I18nProvider>;

Workflow Panel

A panel for workflow participation (Storybook).

Workflow Panel Provider

Types

Metadata

Configuration

Workflow Button

A Button component to show/hide the workflow panel. If a workflow instance doesn't exist, the button will return null.

Example

import {
  WorkflowPanelProvider,
  WorkflowPanel,
  WorkflowButton,
} from '@procore/labs-custom-workflows';

<I18nProvider>
  <ToastAlertProvider>
    <WorkflowPanelProvider
      metadata={{
        company: { id: 1, name: 'Test Company' },
        project: { id: 2, name: 'Test Project' },
        workflowableObject: { id: 3, type: 'Billings::Requisition' },
        userId: 7,
        timeZone: 'UTC',
        pusherApiKey: 'PUSHER_KEY',
      }}
    >
      <WorkflowButton />
      <WorkflowPanel title="Workflow Panel Title" />
    </WorkflowPanelProvider>
  </ToastAlertProvider>
</I18nProvider>;

useWorkflowPanelContext

Example

import { useWorkflowPanelContext } from '@procore/labs-custom-workflows';
import { DetailPage } from '@procore/core-react';

const { workflowPanelStatuses, showWorkflowPanel } = useWorkflowPanelContext();

if (!workflowPanelStatuses.ready) {
  return <Loading />;
}

return (
  <DetailPage width="md">
    <DetailPage.Main>
      <DetailPage.Header>{'Header subcomponents'}</DetailPage.Header>
      <DetailPage.Body>{'Body subcomponents'}</DetailPage.Body>
    </DetailPage.Main>
    <DetailPage.Aside open={showWorkflowPanel}>
      <WorkflowPanel title="Workflow Panel Title" />;
    </DetailPage.Aside>
  </DetailPage>
);