Procore Integration - CxAlloy Issues Sync
In this article
- Video Walkthrough
- Requirements and Permissions
- Quick Start
- Configuration
- CxAlloy Assets as Procore Locations
- Additional Integration Options
- Limitations
- App Permissions
- Default Values
- Proxy Users and Change Attribution
Video Walkthrough
CxAlloy projects can enable Procore integration to connect to a Procore project and continually sync issues and their updates from CxAlloy to Procore and vice versa.
Requirements and Permissions
The "CxAlloy Issues Sync" app must be installed from the Procore Marketplace to the appropriate Procore Company by a Procore Company admin.
Quick Start
Enabling the Procore Integration requires installing an app from the Procore Marketplace:
In Procore
- 1
-
Install the CxAlloy Issues Sync app from the Procore Marketplace in the Procore Company that contains the Procore project to be integrated with.
NOTE
Be sure to install the "CxAlloy Issues Sync" app, not the "CxAlloy TQ Sync (Legacy)" app.If the user is not a Procore Company admin, click "Request App" to send notification to company admins requesting the app's installation. Additional info about requesting an app is available on the Procore support site: https://support.procore.com/products/online/user-guide/company-level/admin/tutorials/manage-app-install-requests
During installation, it is possible to review the app's requested permissions and add permitted projects.
- 2
-
Add the Procore project to the app's list of Permitted Projects.
If the project was not added to the app's list of Permitted Projects during installation, it can be added from the app's Permissions.
- Navigate to Apps > App Management
- Click the View button to the left of CxAlloy Issues Sync in the Installed Apps list
- Switch to the app's the Permissions tab
- Find the desired project in the Select Projects dropdown on the right and press Add
- 3
-
Get the Procore Company ID.
The ID of the Procore company the Procore project belongs to is required during the integration's setup in CxAlloy; it can be obtained from the url by copying the value that comes before "/company".
In CxAlloy
Once the app is installed in Procore, the integration can be enabled and configured in CxAlloy.
- 1
-
Connect to Procore.
- Navigate to the desired CxAlloy project
- Click the Project dropdown in the top left and select Settings
- Switch to the Procore Integration tab from the lefthand sidebar
- Click Connect to Procore
Enter the Procore Company ID and click Next. CxAlloy will verify that the provided ID is valid and that the app is installed for that company.
- 2
-
Configure and enable the integration. See the Configuration section for details on configuration options.
After stepping through the configuration, click Enable to activate the integration. Syncing will begin immediately at 5-minute intervals.
Configuration
The integration setup is broken down into three steps: Procore Settings, Map CxAlloy to Procore, and Map Procore to CxAlloy.
Procore Settings
Select the desired Procore project from the dropdown. Users may choose to sync Design issues, Construction issues, or both; selecting at least one phase is required. Syncing issue assignments is optional.
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, but it will not create users or contacts 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.
Procore does not have direct equivalents for role or company assignments. If an issue is assigned to a company or role in CxAlloy, the assignment will be ignored.
If this option is not enabled, observations and issues will need to be assigned independently in each system.
Map CxAlloy to Procore
Choose how values in CxAlloy will be mapped to their corresponding fields in Procore. All observations in Procore must have an Observation Type. Issues synced from CxAlloy will map to the chosen type in
Map Procore to CxAlloy
Choose how values in Procore will be mapped to their corresponding fields in CxAlloy.
Users may map multiple CxAlloy statuses to the same Procore status. It is also possible to map multiple Procore statuses to the same CxAlloy status.
CxAlloy supports the customization of a project's issue statuses, issue priorities, and disciplines. If these settings are modified at any point, the integration should be reconfigured accordingly.
Edit Field Mapping
Field mapping can be modified at any time from the Procore Integration page. Scroll down to the Field Mapping subsection and press the pencil icon to open the Edit Mapping modal. Mapping from both CxAlloy to Procore and from Procore to CxAlloy will need to be reconfirmed.
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.
If the newly assigned asset no longer exists in CxAlloy, the change is ignored.
Additional Integration Options
Once the integration is enabled, its current configuraiton can be viewed from the Procore Integration tab on the project's Settings page. The action bar at the top includes buttons to Change Project, View Logs, and Reset Integration.
- Change Project - Updates the Procore project that the integration is connected to
- View Logs - Sync activity can be reviewed in the integration logs; if any errors are generated, email support@cxalloy.com
- Reset Integration - Disables the integration entirely; syncing will cease immediately, but information that has already synced will be retained
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 due to limitations in the Procore API.
- When conflicts between simultaneous changes in both CxAlloy and Procore occur, the "winner" is determined by which change is received last.
Multiple CxAlloy projects can be integrated with the same Procore project, with each CxAlloy project separately tracking the Procore observations it creates. However, the “proxy assets” under the “Locations” tree in Procore will be shared and managed by all of the linked CxAlloy projects.
App Permissions
The CxAlloy Issues Sync app has been designed to have only the minimum permissions necessary.
Project Admin - Admin
Required 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
Required to sync assignments, allowing 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
Required for the app to create, update, and delete observations.
The integration only creates new observations and updates those observations it has created. It will not modify observations that originate in Procore, and it will not copy or sync observations that originate in Procore.
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 and Change Attribution
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.
- 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.