Procore Integration - CxAlloy Issues Sync
In this article
- Overview
- Requirements and Permissions
- Quick Start
- Configuration
- CxAlloy Assets as Procore Locations
- Viewing Logs
- Disabling Procore Integration
- Limitations
- App Permissions
- Proxy Users
- Change Attribution
- How it Works
Overview
CxAlloy projects can enable Procore integration to connect to a Procore project and either copy or sync the issues from CxAlloy to Procore.
Procore integration offers two approaches to accommodate different project needs: a one-time copy of issues to Procore, or continuous sync with updates in Procore going back to CxAlloy and vice versa.
Requirements and Permissions
Quick Start
Enabling the Procore Integration requires installing an app from the Procore Marketplace and then enabling the Procore Integration. In this quick start we'll walk through the process step-by-step. The steps are:
In Procore
- Install the CxAlloy Issues Sync app.
- Add Procore project under "Permitted Projects".
- Get the Procore Company ID.
In CxAlloy
- Connect to Procore.
- Configure and enable the integration.
In Procore
- 1
-
Install the CxAlloy Issues Sync app app.
The Procore Integration depends on the installation of the CxAlloy Issues Sync app from the Procore Marketplace. The app must be installed into the Procore Company that contains the Procore project you want to integrate with.
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
Procore will guide you through the installation process. During installation you can review the app's requested permissions and add permitted projects.
NOTE Be sure to install the "CxAlloy Issues Sync" app, not the "CxAlloy TQ Sync (Legacy)" app.
- 2
-
Add the Procore project to the app's "Permitted Projects".
Once the app is installed, make sure that the Procore project you want to sync with is included in the list of "Permitted Projects" under the app's Permissions tab. You may have already done this during installation. If not you can add permitted projects at any time.
- Navigate to Apps -> App Management
- Click "View" next to "CxAlloy Issues Sync"
- Click the "Permissions" tab
- Verify the desired project is in the list of "Permitted Projects" and add it if it is not.
- 3
-
Get the Procore Company ID.
During setup in CxAlloy you must have the ID of the Procore company the Procore project belongs to. The easiest way to get this is from the URL. The company ID is the number that comes before the /company/ part of the URL on any Procore Company page. Write it down; you will need it later.
In CxAlloy
Once you have completed the previous steps in Procore you are ready to turn on the integration from CxAlloy.
- 1
-
Connect to Procore.
- Navigate to the desired CxAlloy project
- Navigate to Project -> Project Settings
- Click the "Procore Integration" tab
- Click "Connect to Procore"
If you have completed the previous steps the Procore app is already installed. Provide the Procore Company ID you wrote down earlier and click "Next". CxAlloy will verify that the provided company ID is valid and that the app is installed for that company ID.
- 2
-
Configure and enable the integration. See the Configuration section for details on configuration options.
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 issues show up in Procore within a few minutes.
Configuration
During the configuration process you choose a Procore project to integrate with, the integration approach (one-time copy vs. continuous sync), which issues to use, field mappings, whether to sync assignments, and what observation type the Procore Observations should have.
Select Project and Approach
Select the desired Procore project from the dropdown. Select either "One-Time Copy" or "Sync" option.
Select Issue Phases
Choose whether the integration should include only construction phase issues, only design phase issues, or both construction and design phase issues.
Map Fields
Choose how to map your CxAlloy statuses, priorities, and disciplines to Procore's equivalents.
The mapping must be configured in both directions. For example, the system needs to know what CxAlloy 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 status is changed to "In Progress".
Because CxAlloy supports an arbitrary number of statuses it's possible that multiple CxAlloy statuses result in the same Procore status. Similarly, you may choose to have multiple Procore statuses result in the same CxAlloy status. All of these options are acceptable.
Sync Issue Assignments
Choose whether to sync assignments. Assignment syncing is based on the assignee's email address. The assignee will sync from CxAlloy to Procore if a matching user is found in Procore. Assignees will always sync from Procore to CxAlloy. The integration will create Contacts in CxAlloy for any assignee that does not already exist in the CxAlloy project.
Syncing assignment will not create users or contacts in Procore.
Procore does not have direct equivalents for role or company assignments, only users. If an issue is assigned to a company or role in CxAlloy, that assignment will not sync.
Select Observation Type
All Procore observations must have a type. Select which Observation Type should be used for the Procore observations created from CxAlloy issues.
Enable the Integration
Click "Enable" to activate your options and turn on the integration. Within a few minutes you should see your CxAlloy issues appearing in the configured Procore project.
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.
In addition, the Procore Observation's "Location" field will be used to show the CxAlloy issue’s asset. Procore allows the creation of location hierarchies and any item in that hierarchy can be set as the “Location”.
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.
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 and Procore will remain. Links to corresponding Procore Observations from within CxAlloy will no longer be shown.
You can re-enable Procore Integration again at any time.
Limitations
- 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.
- 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."
- When conflicts between simultaneous changes in both CxAlloy and Procore occur the "winner" is determined by which change is received last.
App Permissions
The CxAlloy Issues Sync app has been designed to have only the minimum permissions necessary. The following explains the need for each permission.
Project Admin - Admin
This permission is necessary for the app to activate a Procore "webhook". The webhook notifies CxAlloy every time a Procore observation is updated. This permission also allows the integration to create Procore locations as described in the CxAlloy Assets as Procore Locations section.
Project Directory - Standard
This permission is necessary to sync assignments. It allows the integration to look up existing users in the Procore project by their email address as described in the Sync Issue Assignments section.
Project Observations - Admin
This permission is necessary for the app to create, update, and delete observations.
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.
Proxy Users
The Procore Integration creates dedicated users within both CxAlloy and Procore to facilitate data syncing.
Installing the CxAlloy Issues Sync app within Procore will automatically create a corresponding "cxalloy-issues-sync" user that will be visible in the Company directory and the Project directories of any permitted projects.
Enabling the integration within CxAlloy will automatically create a corresponding "Procore Integration User" that will be visible in the account and project "People" lists where the integration is enabled.
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. This is because the integration's Procore user and CxAlloy user, respectively, are used to apply all changes back and forth between the two projects. This has several implications:
- All edits originating from CxAlloy and subsequently applied in Procore via the integration are shown within Procore as having been performed by the "CxAlloy Issues Sync" user associated with the installed CxAlloy app. This is true regardless of who originated the change in CxAlloy.
- All edits originating from Procore and subsequently applied in CxAlloy via the integration are shown as having been performed by the "Procore Integration" user when viewed within CxAlloy, regardless of who originated the change in Procore.
- All edits to Procore Observations are synced to CxAlloy, even if they are made by a user that would not be able to make that change directly in CxAlloy.
- All edits to CxAlloy 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, even if the change would otherwise be forbidden by the project's status permissions.
- Deleting an issue in CxAlloy will delete the corresponding Observation in Procore.
- Unpublishing an issue in CxAlloy 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 but want issue follow-up and resolution to be managed exclusively through Procore.
With the one-time copy approach, CxAlloy issues with a designated status are copied to Procore, including the issue's comments and files. After being copied, the issue's 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.
Technical Details
Ongoing Sync
With the ongoing sync approach, all CxAlloy 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 issue, and updates to the CxAlloy issue are synced back to the Procore observation.
The ongoing sync approach includes comments and files attached to issues.