Procore Integration

In this article


Video Overview

CxAlloy TQ projects can enable Procore integration to connect the CxAlloy TQ project to a Procore project and either copy or sync the issues in the CxAlloy TQ project to the corresponding Procore project.

Procore integration offers two approaches to accommodate different project needs: issues can be brought over via a one-time copy to be managed exclusively through Procore, or they can be kept in sync with updates in Procore going back to CxAlloy TQ and vice versa.

Prerequisites and Permissions

Two different user authorizations are necessary to enable Procore Integration, represented as two discrete steps in the Procore Integration.
Step 1: "Connect to Procore"
CxAlloy TQ must receive an authorization for a specific Procore user, and that Procore user must approve the CxAlloy TQ Sync app. Clicking "Connect to Procore" redirects to the Procore login page and then prompts the user to authorize the CxAlloy TQ Sync app after logging in. The Procore user must have the following Procore permissions:
  • Admin on the project’s Admin tool (Necessary to configure project webhooks).
  • Admin level permissions on the project’s Observations tool (Necessary to allow for deleting of observations).
Step 2: "Configure Procore"
The integration must then be configured and enabled by a CxAlloy TQ user with the following project permissions:
  • Manage for Settings
  • Manage for Design Issues and/or Construction Issues (only necessary with the Ongoing Sync approach).

Ultimately both steps must be performed by a CxAlloy TQ user that has Manage permissions for Settings, as both steps are within the Project Settings area. However, the two steps ("Connect to Procore" and "Configure Procore") do not have to be performed by the same CxAlloy TQ user. In addition, the user that performs the "Connect to Procore" step does not need to retain the Manage permission for Settings after successfully connecting.

This means that you could invite in a GC that has the required Procore permissions and have them perform the "Connect to Procore" step, authorizing the integration under their Procore user account. You could then remove them from the project or turn off their Manage permission for Settings, and have a different CxAlloy TQ user perform the "Configure Procore" step.

Limitations

Certain incompatibilities and limitations between Procore and CxAlloy’s data structure and API influence the way the integration works.
  • The Procore API does not allow updating an observation comment after being created. This means edits to issue comments are not synced.
  • Procore allows rich text (bold, italic, etc.) in their observation description which is not supported in CxAlloy TQ. This means Procore rich text formatting is ignored.
  • Attachments to comments in Procore are not brought over to CxAlloy TQ.
  • Assignments are not synced. Issues and observations must be assigned independently in CxAlloy TQ and Procore, respectively.
  • Observation notifications (Procore documentation) are not sent automatically. This is due to limitations in the Procore API: "Individual observations can only be sent using the Procore web user interface."
  • Due to limitations of the Procore API, comments on observations in Procore may take up to an hour to sync to CxAlloy TQ.
  • When conflicts between simultaneous changes in both CxAlloy TQ and Procore occur the "winner" is determined by which change is received last.

Proxy Users and Change Attribution

Using the Procore Integration with the Ongoing Sync approach entails giving up some control over project data to the corresponding Procore project. Similarly, the Procore project gives up some control over project data to CxAlloy TQ. This is because the authorized Procore user and enabling CxAlloy user, respectively, are used to apply all changes back and forth between the two projects. They effectively serve as a proxy user for other users' actions. This has several implications:

  • All edits that originated from CxAlloy TQ and were subsequently applied in Procore via the integration are shown as having been performed by the authorized Procore user when viewed within Procore, regardless of who originated the change in CxAlloy TQ.
  • All edits that originated from Procore and were subsequently applied in CxAlloy TQ via the integration are shown as having been performed by the enabling CxAlloy TQ user when viewed within CxAlloy TQ, regardless of who originated the change in Procore.
  • All edits to Procore Observations are synced to CxAlloy TQ, even if they are made by a user that would not be able to make that change directly in CxAlloy TQ.
  • All edits to CxAlloy TQ issues are synced to Procore, even if they are made by a user that would not be able to make that change directly in Procore.
  • All status changes to Procore Observations are synced to CxAlloy TQ, even if the change would otherwise be forbidden by the project's status permissions.
  • Deleting an issue in CxAlloy TQ will delete the corresponding Observation in Procore.
  • Unpublishing an issue in CxAlloy TQ will delete the corresponding Observation in Procore.

How It Works

One-Time Copy

The one-time copy option is for those situations where you want to create issues in CxAlloy TQ but want issue follow-up and resolution to be managed exclusively through Procore.

With the one-time copy approach, CxAlloy TQ issues with a designated status are copied to Procore, including the issue's comments and files. After being copied, the CxAlloy TQ's issue status is updated to indicate the copy was completed. After copying, any future changes to the issue are not synced to Procore.

You choose which status triggers the copy to Procore, and which status is set after the issue is successfully copied.

You may want to create dedicated statuses such as “Copy to Procore” and “Copied to Procore” for this purpose.
Technical Details
Once enabled, every few minutes CxAlloy TQ looks at all the issues in your project. Any issues that have the status you’ve designated for copying will be copied to Procore and their status updated per your settings.
After copying, no ongoing connection between the CxAlloy TQ issue and the Procore observation is maintained. Edits to the observation in Procore are not brought over to CxAlloy TQ and edits in CxAlloy TQ do not affect the observation in Procore.
If an issue that has previously been copied to Procore has its status set to your designated copy status again, the issue is copied again and creates a new observation in Procore. 

Ongoing Sync

With the ongoing sync approach, all CxAlloy TQ design and/or construction issues created in the project are copied to Procore. Updates to the observation in Procore are synced back to the CxAlloy TQ issue, and updates to the CxAlloy TQ issue are synced back to the Procore observation.

As with the copy operation, the ongoing sync approach includes issue comments and files, with the addition that new comments and files in Procore are brought over to CxAlloy.

Technical Details
The first time the Procore Integration runs with the Ongoing Sync approach all eligible issues in the CxAlloy TQ project are copied to Procore and the date and time of that initial sync is recorded.
From that point on every few minutes CxAlloy TQ looks at all issue activity within your project since the last sync time. This includes issue updates, new issues created, and files and comments added to issues. Those updates are then applied to the corresponding observations in Procore (or new observations are created in the case of new issues). The last sync time is then updated.
Changes made in Procore are handled differently. Whenever a change is made in Procore, CxAlloy TQ is notified that a change occurred to a Procore observation. CxAlloy TQ is then responsible for determining the nature of the change and applying that same change to the corresponding CxAlloy TQ issue.
A new comment on an observation has special handling due to limitations of the Procore API. Procore notifies CxAlloy TQ whenever a new comment is added to an observation but does not provide any information about what observation the comment belongs to. Because CxAlloy TQ does not know what observation the comment belongs to it is forced to reconcile all comments on all observations to identify the new comment. This can be a time-consuming operation and could create problems if it had to run for every new comment that is added. Instead, when CxAlloy TQ is notified of a new comment on a Procore observation a flag is set and CxAlloy TQ will pick up the comment on the next scheduled sync.

App Installation

The Procore Integration is made possible by the CxAlloy TQ Sync app for Procore. That app must be installed, either explicitly or implicitly, under the Company account that owns the Procore project for the integration to work.

Implicit Installation

If the CxAlloy TQ Sync app is not already installed, it will be automatically installed during the configuration process when you select the Procore Company account to use.

If the Procore Company account has toggled off the "Allow User Installs" option then the implicit install option will not work. Instead the CxAlloy TQ Sync app must be explicitly installed.

If you get the error message "Implicit Oauth Connections Are Not Allowed For This Company" that means that the Company has toggled off the "Allow User Installs" option and the app must be installed explicitly.

Explicit Installation

Search for "CxAlloy TQ Sync" in the Procore Marketplace, then click "Install" on the app. If you are not a Company admin you can click "Request App" which sends a request notification to company admins. Additional info about requesting an app is available at the Procore support site.

https://support.procore.com/products/online/user-guide/company-level/admin/tutorials/manage-app-install-requests

Once the app is installed you can proceed to the configuration process in CxAlloy TQ.

Setup

Enabling the Procore integration requires connecting to Procore, configuring the integration, and then enabling it. These actions are all done via the "Procore Integration" tab of project settings.

1
Click Connect to Procore. You will be taken to Procore's login page. After successfully logging in, you will be redirected back to the Procore Integration settings.

2
Click Configure Procore. You will be taken through a series of questions to configure the integration.

3
After stepping through the configuration questions, click Enable Procore to activate your configuration settings. At this point the Procore Integration will take effect and you will see eligible CxAlloy TQ issues show up in Procore within a few minutes.

Field Mapping

The ability to customize a project's statuses, priorities, disciplines, and other settings is key to CxAlloy TQ. It was important to us to preserve that functionality even when using the Procore Integration. In service of that you will be prompted to map your custom statuses, priorities, and disciplines to Procore's when using the "Ongoing Sync" approach.

The mapping must be configured in both directions. For example, the system needs to know what CxAlloy TQ status to set when the Procore status is changed to "Ready for Review". It also needs to know what Procore status to set when the CxAlloy TQ status is changed to "In Progress".

Because CxAlloy TQ supports an arbitrary number of statuses it's possible that multiple CxAlloy TQ statuses result in the same Procore status. Similarly, you may choose to have multiple Procore statuses result in the same CxAlloy TQ status. All of these options are acceptable.

Default Values

If the sync encounters a situation where a mapping does not exist it will use an appropriate default value. These default values are:

  • If a Procore status is not mapped, the corresponding CxAlloy TQ issue status will be the initial issue status (usually "Open")
  • If a CxAlloy TQ status is not mapped, the corresponding Procore Observation status will be "Initiated".
  • If a CxAlloy TQ priority is not mapped, the corresponding Procore Observation priority will be "Low"
  • In all other cases where a value is not mapped, the corresponding value will not be set.

Viewing Logs

If you encounter any problems with the sync you can view the Procore sync logs by clicking "View Logs" on the Procore Integration settings page. For additional help please contact CxAlloy Support at support@cxalloy.com.

Disabling Procore Integration

If you need to turn off the Procore Integration click "Disable" on the Procore Integration settings page. Confirm by clicking "Disable" again in the confirmation dialog. The integration will stop running and changes between the two systems will no longer be synced. All content in both CxAlloy TQ and Procore will remain. Links to corresponding Procore Observations from within CxAlloy TQ will no longer be shown.

You can re-enable Procore Integration again at any time.

Still need help? Contact Us Contact Us