Procore Integration — Complete Guide

This guide covers installing and configuring the Peptalk app in Procore for both single-project (one token per project) and multi-project groups (one token per project group), plus how project group API tokens work in the codebase.

---

1. Environment Overview

Environment	URL	Purpose
Developer Portal	developers.procore.com	Build and manage the app's manifest and retrieve version keys.
Sandbox	sandbox.procore.com	Testing environment with full administrative permissions.
Production	app.procore.com	Live environment.

Logins are shared across all three; administrative access for app management is typically in Sandbox.

---

2. Single Project / Single Token Installation

Use this when one Procore project maps to one Peptalk project.

Step 1: Create the Project

1. Portfolio → Create Project.
2. Fill Project Name, Total Value, Start/Completion Dates, set status Active.
3. Save; you are redirected to Project Home.

Step 2: Install the Custom App

1. Company Admin → App Management → Install App → Install Custom App.
2. In the Developer Portal, copy the Sandbox App Version Key (testing) or Production App Version Key (live).
3. Paste the key in the Procore modal and click Install.

Step 3: Configure Project & Single Token

1. Find Peptalk → View → Configurations.
2. Create Configuration.
3. Select the project from Step 1.
4. API Token: Open the Peptalk project page (not a project group) → View Procore Report → copy the single-project API Token → paste into the configuration.
5. Create.

Step 4: Verify

1. Refresh the Procore project.
2. Apps (top right) → Peptalk. The app loads in an iframe with that project’s dashboard.

---

3. Multi-Project Group / Grouped Project Token Installation

Use this for executive or multi-site overviews: several projects in one group, one Project Group Token, with a Switch Project dropdown in the iframe.

Step 1: Install the Developer App Version

If the feature is on a development backend:

1. Go to the Procore Developer Portal.
2. Copy the Sandbox App Version Key for the Development version (mapped to your Dev URL).
3. App Management → Install Custom App → paste the key.

Step 2: Get the Project Group Token

1. In Peptalk, open the Project Group.
2. Click Open Procore (or the report link) to see the Project Group Token.
3. Copy the token.

Step 3: Create the Configuration

1. App Management → find the Dev app → View → Configurations.
2. + Create Configuration.
3. Title: e.g. Project Group Demo.
4. Targeting: Select the project that will be the entry point for the group.
5. Token: Paste the Project Group Token from Step 2.
6. Create.

Step 4: Launch and Test

1. In Procore, open the project you configured.
2. Apps → select the development version of the app.
3. Confirm data loads and the Switch Project control lets you move between projects in the group.

---

4. Project Groups: Token Generation & Access Flow

Generating the API Token for a Project Group

• Where: Admin → Project Groups (/admin/project_groups).
• How:
  1. Open Project Groups in Active Admin.
  2. Select one or more groups (checkboxes).
  3. Batch action: “Generate API tokens”.
  4. Submit.
  5. Groups with no token get a new token.
  6. Groups that already have a token are skipped.
• Tokens are created only from Project Groups admin via this batch action.

Token Storage

• Stored in the same api_tokens system as project/company/user tokens.
• Each project group has at most one API token.
• The group’s database password (e.g. for Metabase) is not the Procore API token.

Accessing Procore with a Project Group Token

Entry (one URL per group):

• URL: https://<host>/integrations/procore/iframe?api_token=<project_group_token>
• In the app: Project Groups → Open Procore for a group opens that URL.
• Result: Project list for that group (no project selected yet).

Choosing a project:

• User clicks View Dashboard for one project.
• URL: https://<host>/integrations/procore/iframe?api_token=<project_group_token>&project_id=<id>
• Result: Dashboard for that project (same metrics as single-project view).

While on the dashboard:

• All links keep the same token and project_id.
• Switch project returns to the project list (same token, no project_id).

Summary: Group token → project list → choose project → dashboard → “Switch project” → list again. Data is per project; the group token only defines which projects can be chosen.

Comparison: Single Project vs Project Group

Aspect	Single project (“View Procore Report”)	Project group (“Open Procore”)
Token	Project’s API token	Project group’s API token
URL	...?api_token=<project_token>	...?api_token=<group_token>; then &project_id=<id>
First screen	That project’s dashboard	Project list; user picks project
Switching	N/A	“Switch project” → back to list
Use case	One project’s Procore data	One URL for any project in the group

---

5. Project Group API Token: Why No Migration

ProjectGroup does not have an api_token or api_token_id column. The link is the same as for Project:

• api_tokens has: resource_type, resource_id, api_token_type, token.
• Project: row with resource_type = 'Project', resource_id = project.id.
• ProjectGroup: row with resource_type = 'ProjectGroup', resource_id = project_group.id.

Both Project and ProjectGroup use a polymorphic association:

• has_one :api_token, as: :resource
• So project_group.api_token means: find ApiToken where resource_type='ProjectGroup' and resource_id = project_group.id.

No migration was needed: api_tokens already has resource_type, resource_id, and api_token_type (string). We only added a new enum value in app/models/api_token.rb:

enum api_token_type: {
  company: 'company',
  project: 'project',
  project_group: 'project_group',   # added
  user: 'user'
}

So we can create and identify project group tokens without new columns or migrations.

---

Quick Reference

• Single project: Projects admin → View Procore Report → use that project’s token in Procore configuration.
• Project group: Project Groups admin → Generate API tokens (batch) → Open Procore → use group token in Procore configuration; use Switch project in the iframe to change project.

---

← Back to Documentation