In this article
- Video Overview
- Prerequisites and Permissions
- Proxy Users and Change Attribution
- How it Works
- App Installation
- Viewing Logs
- Disabling Procore Integration
- Reauthorization Flow
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
- 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).
- 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.
- 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
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.
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.
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.
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.
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.
Once the app is installed you can proceed to the configuration process in CxAlloy TQ.
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.
- 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.
- Click Configure Procore. You will be taken through a series of questions to configure the integration.
- 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.
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.
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.
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.
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 email@example.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.
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.