@procore/labs-workflows v8.0.0

Workflows

Workflows for Procore

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-workflows

This package requires Node 12+.

Dependencies

@procore/*, react, react-dom, formik, styled-components, and react-query are listed as external peer dependencies. The package will not bundle the code, and requires the app client to provide it as a dependency. The external peer dependencies are to ensure 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.

Onboarding

Technologies used

• Function Components and React Hooks are preferred, we only use class components in a few exceptions. Resource: React with Hooks.
• Storybook is used as a tool for development.
• Mock Service Worker is used for API mocking in both stories and tests, previuosly we used other mock libraries, but everything will migrate to msw overtime.
• Jest with Testing Library are used for tests (unit and integration).
• Fishery is a lib for setting up objects (pretty similar to factory_bot gem), used in mocks and tests.
• Context API along side with custom hooks are used to share state between components;
• Error Boundary is used in every component that will be consumed by external components (like hydra clients).
• Procore Design System must be used in all components.
• Styled Components is used for any css styles needed.
• jsPlumb is the tool used for our workflow builder.

Folder structure

Our components are grouped by feature and each individual component has his own folder, that's used for the tests and stories files as well.

src
├── api
│   └── workflowApi.ts
├── builder - feature group
│   ├── components
│   │   ├── AssigneeList
│   │   │   ├── AssigneeList.story.tsx
│   │   │   ├── AssigneeList.test.tsx
│   │   │   └── AssigneeList.tsx
│   │   └── ...
│   └── state
│       ├── BuilderUIContext
│       │   └── BuilderUIContext.tsx
│       └── ...
├── sharedState - shared stuff
│   ├── ErrorBoundary
│   │   ├── ErrorBoundary.story.tsx
│   │   ├── ErrorBoundary.test.tsx
│   │   └── ErrorBoundary.tsx
│   ├── ...
│   ├── CoreLabsProviders.tsx
│   ├── WorkflowsApiContext.test.tsx
│   └── WorkflowsApiContext.tsx
├── templateManagement - feature group
│   └── ...
├── testUtils
│   └── ...
├── types
│   └── ...
└── utils
    └── ...

Development Process

Although most of development can be done using storybook, it's always necessary to see how things gonna fit in the monolith. You can achieve this in many ways: with an alpha publish, using yalc or with yarn link. For the first two options refer to README.md on core-labs. The latter will give you HMR (hot module replacement), so it's pretty helpful when doing some tweaks to the code.

Versioning and Publishing

• We use SemVer for our versioning system along with this format for our CHANGELOG.
• Add a link to the PR for each entry in the CHANGELOG. The entry in the CHANGELOG.MD can match the Changelog in the PR description.
• When developing a new feature, please refer to one of the following cases below:

Case 1: Frontend is dependent on breaking backend changes

• After the frontend package is consumed, alpha published (see case 2 for alpha publishing), and tested along with the backend code in the monolith, then publish the package following SemVer format, updating the minor or major version.
• Update the CHANGELOG with the release changes. The latest changes go on the top.
• Update to the latest package in the monolith package.json(s).

Case 2: Frontend is NOT dependent on backend changes.

• Frontend changes that are NOT dependent on breaking backend changes such as UI/UX enhancements, etc... will only be alpha published. Every new alpha publish will be appended with the ticket number and the last number will increment for changes needed for re-testing via Tugboat, i.e. 1.3.0-alpha-wkf-{ticket number}.{n}.
• Alpha publishes can be consumed by the monolith for Tugboat testing, but not committed.
• Add alpha feature changes to the Unreleased section of the CHANGELOG.
• At the end of the sprint, all of the changes documented in the Unreleased section will be published using traditional SemVer and publishing guidelines described in Case 2 and added as a new major/minor version at the top of the CHANGELOG.
• Once all of the Unreleased alpha changes have been consumed and published at the end of the sprint, the Unreleased section will be wiped clean for the next sprint.

Alpha publish script

[packages/workflows]$ npm publish --tag alpha

Case 3: Minor bug fixes/patches NOT dependent on backend changes

• Simply publish and bump the minor/patch version of the package. Update the CHANGELOG with the latest minor version at the top of the file.
• Update to the latest package in the monolith package.json(s).

Yarn Linking

Follow these steps to succesfully link the workflows package.

1. Add the workflows core-labs package to yarn link:

[packages/workflows]$ yarn link

2. Link the @procore/labs-workflows within the consuming hydra client on the monolith:

[hydra_clients/workflows]$ yarn link @procore/labs-workflows

3. Start the monolith with DEV_MODE enabled to the target hydra client:

[procore]$ DEV_MODE=workflows bundle exec rails s

4. Start the hydra client:

[hydra_clients/workflows]$ yarn start

5. Run the workflows core-labs package in dev mode:

[packages/workflows]$ yarn dev

Other environment variables that can be useful when running the monolith are:

DOCUSIGN_SECRET=test
ENABLE_ALL_WORKFLOWABLE_TOOLS=true

Troubleshooting yarn link

If you are getting error messages when linking such as Invalid Hook Call Warningor translations aren't showing up, you can solve these conflicts by adding these webpack overrides in the target hydra client procore.config.js file. Note: make sure to remove before your code is merged.

module.exports = () => ({
  app: {
    webpackOverride(config) {
      config.resolve.alias
        .set('react', path.resolve('.', 'node_modules', 'react'))
        .set('react-dom', path.resolve('.', 'node_modules', 'react-dom'));
        .set(
          '@procore/core-react',
          path.resolve('.', 'node_modules', '@procore/core-react')
        );
    },
    ...
  },
  ...
});

Translations

Translations are added to src/locales/en.json for development and production. Smartling will generate the other supported locales via an auto-generated PR. Smartling will only scan the master branch to detect if there's a modification to src/locales/en.json. After the Smartling PR is merged, our team would need to do bump a minor version to consume the new generated translations.

Storybook

For local storybook development, environment keys are necessary to successfully utilize <ThirdPartyScripts />. Follow the steps below to set up your environment correctly:

1. In the root level of this package, create a .env file.
2. Log into your lastpass and find the note labeled core-labs third party scripts env keys.
3. Copy the entire note and paste it into your .env file.

Here's an example of the .env file that you should have:

STORYBOOK_BUGSNAG_API_KEY=_
STORYBOOK_GA_TRACKING_ID=_
STORYBOOK_LD_CLIENT_ID=_
STORYBOOK_PENDO_API_KEY=_
STORYBOOK_PUSHER_API_ID=_

When testing LD flags in storybook, use email user@procore.com in development environment.

LaunchDarkly Flags