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.

top

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.

top

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.

top

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.

top

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.

top

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.

top

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.

Syncing Issue Assignments

Issues in CxAlloy are mapped to Observations in Procore. To further align that data, it's possible to sync issue assignments to Procore as well. This option needs to be explicitly enabled in the configuration of the Procore integration.

If enabled, the integration will create Procore contacts as necessary to parity assignments. No user permissions are or created permissions as part of this process.

If this option is not enabled, observations and issues will need to be assigned independently in each system.

Projects Already Integrated with Procore

Syncing issue assignment can be toggled through the “Change Options” button.

Issues that were previously synced will not have their assignment retroactively updated in either system. Only the creation of new issues or the editing of an existing issue’s assignment will trigger an update.

Procore does not have direct equivalents for role or company assignments, only users. If an issue is assigned to a company or role, a “user” is created in Procore and treated as the corresponding “assignee” in CxAlloy.

These placeholder users will be listed in Procore as “CxAlloy : Company : [Company Name]” or "CxAlloy : Role : [Role Name]” for companies and roles respectively.

Recording CxAlloy Assets as Procore Locations

CxAlloy issues can be connected to an asset, but Procore observations lack an equivalent field. By default, issues synced from CxAlloy include the asset as additional information within the Procore Observation's description.

An additional option is available to track the CxAlloy issue’s asset in the Procore Observation’s “Location” field. Procore allows the creation of location hierarchies, and any item in that hierarchy can be set as the “Location”.

If enabled, the integration automatically creates its own hierarchy with "CxAlloy Assets" as the root, the asset type ("Systems", "Equipment", "Spaces", etc.) as the second level, and the individual assets as the third level. The “Location” field of an Observation is then set to its corresponding value accordingly.

Example Location Hierarchy in Procore

If a Procore Observation’s location is manually set to a value that does not belong to the “CxAlloy Assets” hierarchy, it is ignored and no change will be made to the issue within CxAlloy.

If a Procore Observation’s location is manually set to a different value within the “CxAlloy Assets” hierarchy, that change will be synced to the corresponding issue in CxAlloy.

NOTE If the newly assigned asset no longer exists in CxAlloy, the change is ignored.

top

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.

top

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.

top

Reauthorization Flow

Some situations may require reauthorizing the Procore integration. For example, if the Procore user who initially authorized the integration is removed from the Procore project. Through the Reauthorize function, it's possible to reauthorize under a different Procore user without having to disable and reconfigure the entire integration. 

Clicking "Reauthorize" redirects to the Procore login page and then prompts the user to authorize the CxAlloy TQ Sync app after logging in. 

The process is the same as the initial “Connect to Procore” step when first enabling the integration.

top

Still need help? Contact Us Contact Us