When Clearstory adds new capabilities to the Procore integration, the Clearstory app in Procore sometimes needs a newer version and additional permissions to support them. This article walks you through updating the app in Procore, setting its permissions to the minimum each feature needs, and turning the new features on in Clearstory.
Before you Begin
To complete these steps, you'll need a Procore company administrator with Admin permission on the company-level Admin and Directory tools.
Updating the app is required for these features:
- Status Sync (Beta): Shows live Procore statuses in your Clearstory COR (Change Order Request) Log. This includes the Procore Change Event (CE) status, the Prime Potential Change Order (PCO) number and status, and the Commitment Change Order (CO) number and status.
- Project Import: Creates Clearstory projects from your Procore projects.
- Contract Import: Creates Clearstory contracts from your Procore commitments.
Note: Updating the app doesn't update the Clearstory service user's permissions. The service user is the Procore account Clearstory uses to read your data, and its permissions control what Clearstory can see. Complete every section below.
Install or Update the Clearstory App in Procore
Note: Status Sync requires version 19.36.0 or later of the Clearstory app. New installations get the latest version automatically.
- Log in to Procore.
- Open the Select an App dropdown and select Marketplace.
- Search for Clearstory.
- Open the Clearstory app listing.
- Check the button at the top of the listing:
- Install: Clearstory isn't installed yet. Click Install, review and accept the permissions Procore asks you to grant, and confirm the installation.
- Update Available: Clearstory is installed but needs an update. Click to update, review the changes in the Review Update window, click Update, and approve the permissions Procore asks you to grant.
- Installed: Clearstory is installed and on a supported version. Continue to the next section to set the service user's permissions.
Updating keeps your existing company configuration, project settings, and project mappings in place. Your connected projects won't disconnect.
Set permissions for the Clearstory service user
When the Clearstory app is installed, Procore adds a Clearstory service user to your Company Directory. Its name starts with clearstory- and ends with @procore.com, for example clearstory-authorization_code-b7f83066@procore.com. The characters in the middle are different for each company.
You set the service user's permissions with a project permissions template, then add the service user to your projects.
Note: The Permissions tab in App Management shows the permissions Clearstory requests. You can't change tool permission levels there. Set them on the Clearstory service user using the steps below.
The Clearstory service user needs these permissions on each project you'll use with Clearstory:
| Procore tool | Permission | Used for |
|---|---|---|
| Change Events | Read Only | Change Event status |
| Prime Contracts | Admin | Prime PCO number and status, including private prime contracts |
| Commitments | Admin | Commitment CO number and status, Contract Import, including private commitments |
| Directory | Read Only | Required by the Clearstory app |
| Home | Read Only | Required by the Clearstory app |
| Webhooks API | Standard | Sends status updates to Clearstory when they change in Procore |
Why Admin on Prime Contracts and Commitments? New commitments in Procore are private by default, and private contracts are only visible to users with Admin on that tool or users added to each contract. Admin lets Clearstory read your private contracts automatically, including new ones aas they're created.
Create a permissions template for Clearstory
- In Procore, open the company-level Permissions tool.
- Select the Project Permissions Templates tab.
- Create a new Global template. Name it Clearstory so it's easy to find later.
- Set each tool to the permission level in the table above.
- Save the template.
Note: If the Clearstory service user already has a permissions template, update that template instead of creating a new one.
Apply the template to the Clearstory service user
- Open the company-level Directory tool.
- Search for clearstory to find the service user.
- Click Edit next to the service user.
- In the permissions area, select Select Default Permission Template.
- Choose the Clearstory template and click Apply.
- Check Add [service user name] to all new projects so future projects are included automatically.
Add your existing projects
- While still editing the service user, scroll to the Current Project Settings section.
- Add the projects you'll use with Clearstory:
- To add every current project, click Add All.
- To add specific projects, click Add next to each project.
- Click Save at the bottom of the page.
Clearstory can only sync statuses on projects the Clearstory service user can access.
Turn on the new features in Clearstory
After the app is updated and the service user's permissions are set, turn on the features in Clearstory and reconnect your projects.
Note: Status Sync is in Beta. Contact your Clearstory Customer Success representative to have it turned on for your company.
Turn on Status Sync for your office
- In Clearstory, go to Integrations and open your Procore configuration.
- Find the Status Sync section.
- Check the syncs you want to turn on:
- Sync Change Event status
- Sync Prime PCO status
- Sync Commitment CO status
- Save your changes.
Reconnect projects that were already mapped
Status Sync turns on for a project when the project is mapped to Procore. Projects mapped before you turned on Status Sync need to be reconnected.
- Open the project's Procore Settings.
- Click Edit.
- Clear the Procore project mapping and click Save.
- Click Edit again.
- Choose the matching Procore project and click Save.
- Confirm a green check appears at the top of the Procore Settings card for each sync you turned on.
Note: Reconnecting turns on sync going forward. It doesn't pull in Change Events, PCOs, or Commitment COs that already existed. If you have many projects to reconnect, contact Clearstory Support and we can do it for you.
For details on what Status Sync shows and how to use it, see Procore Status Sync (Beta).
After future app updates
Procore doesn't carry permission changes over to the service user when an app is updated or reinstalled, and the list of permitted projects needs to be reconfigured each time. After any future update to the Clearstory app:
- Confirm the Clearstory service user still has the Clearstory permissions template applied.
- Confirm your projects are still listed in the service user's Current Project Settings.
Troubleshooting
I can't change tool permissions in App Management. The Permissions tab in App Management shows the permissions Clearstory requests. You can't set tool permission levels there. Set them on the Clearstory service user with a project permissions template. See Set permissions for the Clearstory service user above.
Procore shows "Installed," but Status Sync isn't working. "Installed" means the app version is supported. The most common cause is the Clearstory service user's permissions. Confirm the Clearstory template is applied to the service user and your projects are added, then reconnect the project in Clearstory.
The Prime PCO or Commitment CO column is empty for some contracts. Those contracts are likely marked Private in Procore. Confirm the Clearstory service user has Admin on Prime Contracts and Commitments.
The columns are empty on a project mapped before I turned on Status Sync. Reconnect the project in Clearstory. Then make a change in Procore, or push a new COR, to confirm updates come through.
Status Sync stopped working after an app update. Procore resets the service user's permitted projects when an app is updated. See After future app updates above.
FAQs
Do I need to do anything in Procore after updating the app? Yes. Updating the app doesn't change the Clearstory service user's permissions. Apply a project permissions template to the Clearstory service user and add your projects to it.
How do I find the Clearstory service user? Search the company-level Directory for clearstory. The service user's name starts with clearstory- and ends with @procore.com.
Will updating the app disconnect my projects? No. Your company configuration, project settings, and project mappings stay in place. Projects mapped before you turned on Status Sync need to be reconnected for it to start.
Will reconnecting a project bring in past Procore statuses? Not during the Beta. Status Sync shows items that change after the project is re/connected.
Will my private contracts be visible to my trade partners? No. Giving the Clearstory service user Admin on Prime Contracts and Commitments lets Clearstory read private contracts. It doesn't change who else can see them.
Who in Procore needs to do this? A Procore company administrator with Admin permission on the company-level Admin and Directory tools.