This user manual provides step-by-step instructions for implementing and using the Procore connector. The Procore connector for MuleSoft enables seamless integration between MuleSoft applications and Procore’s construction project management platform. This connector provides a comprehensive set of operations for creating, managing, and interacting with construction projects through Procore’s REST API.

Procore is a leading construction project management platform that helps construction professionals manage projects, resources, and financials from planning to closeout. The platform provides tools for project management, quality and safety, financial management, and field productivity.

• OAuth 2.0 Authentication: Secure connection to Procore API using OAuth 2.0 authorization code flow.

• Project Management: Create and update construction projects with comprehensive project details.

• Company-Specific Operations: All operations support company-specific contexts through Procore Company ID.

• Advanced Error Handling: Robust error handling with detailed logging and proper exception management.

• Geographic Support: Full support for latitude, longitude, and geographic information.

• Custom Fields: Support for custom fields and metadata.

• Cost Code Integration: Standard cost code management and copying.

Prerequisites

Before you can install the Procore Connector, ensure you have the following:

• MuleSoft Anypoint Studio 7.x or higher installed.

• Mule Runtime 4.9.6 or higher.

• Java 17 or higher.

• Procore developer account with API access.

• OAuth 2.0 credentials from Procore.

Install the Connector

Add Maven Dependency

Add the Procore connector dependency to your project’s pom.xml:

Configure Properties

Create a properties file (src/main/resources/properties/dev.properties) with your configuration:

HTTP Listener Configuration

http.listener.host=0.0.0.0
http.listener.port=8081

Procore OAuth Configuration

procore.config.oauth.consumer_key=your-consumer-key
procore.config.oauth.consumer_secret=your-consumer-secret
procore.config.oauth.callback_path=/mule/callback
procore.config.oauth.authorize_path=/authorize-procore
procore.config.oauth.external_callback_path=http://localhost:8081/mule/callback

Basic Configuration

The Procore Connector requires configuration for both the HTTP listener and OAuth authentication.

HTTP Listener Configuration

<http:listener-config name="HTTP_Listener_config" doc:name="HTTP Listener config">
<http:listener-connection host="${http.listener.host}" port="${http.listener.port}"
/>
</http:listener-config>

Procore Connector Configuration

<procore:config name="Procore_Config" doc:name="Procore Config" doc:id="8c4f73ce-b817-
4f65-8eae-c6d04dbd53b4">
<procore:connection >
<procore:oauth-authorization-code
consumerKey="${procore.config.oauth.consumer_key}"
consumerSecret="${procore.config.oauth.consumer_secret}"
/>
<procore:oauth-callback-config
listenerConfig="HTTP_Listener_config"
callbackPath="${procore.config.oauth.callback_path}"
authorizePath="${procore.config.oauth.authorize_path}"
externalCallbackUrl="${procore.config.oauth.external_callback_path}"
/>
</procore:connection>
</procore:config>

Environment-Specific Configuration

Create separate property files for different environments:

Development Environment

http.listener.host=0.0.0.0
http.listener.port=8081
procore.config.oauth.external_callback_path=http://localhost:8081/mule/callback

Staging Environment

http.listener.host=0.0.0.0
http.listener.port=8081
procore.config.oauth.external_callback_path=https://staging.yourdomain.com/mule/callback

Production Environment

http.listener.host=0.0.0.0
http.listener.port=8081
procore.config.oauth.external_callback_path=https://yourdomain.com/mule/callback

Create Project Operation

The Create Project operation allows you to create new construction projects in Procore.

Parameters

Basic Information

Location Information

Timeline Information

Financial Information

Project Classification

Organizational Structure

Contact and Communication

Integration and Origin

Cost Code Configuration

Additional Settings

Example Usage

<procore:create-project
doc:name="Create Project"
doc:id="a381945f-95c0-480e-87ed-01528b64e818"
config-ref="Procore_Config"
companyId="#[payload.company_id]"
name="#[payload.name]"
address="#[payload.address]"
city="#[payload.city]"
stateCode="#[payload.state_code]"
countryCode="#[payload.country_code]"
zip="#[payload.zip]"
latitude="#[payload.latitude]"
longitude="#[payload.longitude]"
startDate="#[payload.start_date]"
completionDate="#[payload.completion_date]"
warrantyStartDate="#[payload.warranty_start_date]"
warrantyEndDate="#[payload.warranty_end_date]"
code="#[payload.code]"
description="#[payload.description]"
totalValue="#[payload.total_value]"
estimatedValue="#[payload.estimated_value]"
estimatedStartDate="#[payload.estimated_start_date]"
estimatedCompletionDate="#[payload.estimated_completion_date]"
squareFeet="#[payload.square_feet]"
phone="#[payload.phone]"
projectNumber="#[payload.project_number]"
storeNumber="#[payload.store_number]"
accountingProjectNumber="#[payload.accounting_project_number]"
locale="#[payload.locale]"
timeZone="#[payload.time_zone]"
officeId="#[payload.office_id]"
parentJobId="#[payload.parent_job_id]"
programId="#[payload.program_id]"
projectStageId="#[payload.project_stage_id]"
projectBidTypeId="#[payload.project_bid_type_id]"
projectTypeId="#[payload.project_type_id]"
projectOwnerTypeId="#[payload.project_owner_type_id]"
projectRegionId="#[payload.project_region_id]"
projectTemplateId="#[payload.project_template_id]"
imageId="#[payload.image_id]"
flag="#[payload.flag]"
publicNotes="#[payload.public_notes]"
departmentIds="#[payload.department_ids]"
originId="#[payload.origin_id]"
originData="#[payload.origin_data]"
designatedMarketArea="#[payload.designated_market_area]"
sector="#[payload.sector]"
workScope="#[payload.work_scope]"
deliveryMethod="#[payload.delivery_method]"
active="#[payload.active]"
erpIntegrated="#[payload.erp_integrated]"
enableCopyOfStandardCostCodes="#[payload.enable_copy_of_standard_cost_codes]"
originCode="#[payload.origin_code]"
overrideStartDate="#[payload.override_start_date]"
overrideStartDateCheck="#[payload.override_start_date_check]"
overrideEndDate="#[payload.override_end_date]"
overrideEndDateCheck="#[payload.override_end_date_check]"
/>

Sample Request

{
"company_id": "562949953437078",
"name": "MuleTest Cloud 9 - 31",
"address": "123 Main St",
"city": "Anytown",
"code": "P123",
"country_code": "US",
"description": "This is mule test project",
"start_date": "2025-01-01",
"completion_date": "2025-12-31",
"total_value": "1000000",
"warranty_start_date": "2025-01-01",
"warranty_end_date": "2026-01-01",
"flag": "1",
"phone": "123-456-7890",
"project_number": "P3423",
"public_notes": "Public Notes",
"project_stage_id": "3",
"square_feet": "1000",
"state_code": "CA",
"time_zone": "US/Pacific",
"zip": "12345",
"parent_job_id": "562949955019589",
"program_id": "562949953512759",
"project_bid_type_id": "562949953465028",
"project_type_id": "562949953482050",
"project_owner_type_id": "562949953439322",
"project_region_id": "562949953468817",
"office_id": "562949953440611",
"override_start_date": "2025-01-01",
"override_start_date_check": true,
"override_end_date": "2026-12-31",
"override_end_date_check": true,
"department_ids": [
"562949953494810",
"562949953495650"
],
"estimated_value": "1000000",
"estimated_start_date": "2025-01-01",
"estimated_completion_date": "2025-12-31",
"store_number": "123",
"accounting_project_number": "123",
"designated_market_area": "Market Area",
"erp_integrated": false,
"latitude": "37.7749",
"longitude": "-124.5924746",
"locale": "en",
"enable_copy_of_standard_cost_codes": false,
"sector": "assembly",
"work_scope": "new_construction",
"delivery_method": "construction_manager_as_agent_owners_rep",
"active": true
}

Update Project Operation

The Update Project operation allows you to modify existing construction projects in Procore.

Parameters

Required Parameters

Basic Information

Location Information

Timeline Information

Financial Information

Project Classification

Organizational Structure

Contact and Communication

Integration and Origin

Cost Code Configuration

Additional Settings

Example Usage

<procore:update-project doc:name="Update Project"
doc:id="3e28c0b7-77af-4a97-a809-a4a6a63d7bd7"
config-ref="Procore_Config"
companyId="#[payload.company_id]"
name="#[payload.name]"
active="false"
address="#[payload.address]"
city="#[payload.city]"
countryCode="#[payload.country_code]"
description="#[payload.description]"
startDate="#[payload.start_date]"
completionDate="#[payload.completion_date]"
totalValue="#[payload.total_value]"
warrantyStartDate="#[payload.warranty_start_date]"
warrantyEndDate="#[payload.warranty_end_date]"
flag="#[payload.flag]"
locale="#[payload.locale]"
phone="#[payload.phone]"
fax="#[payload.fax]"
publicNotes="#[payload.public_notes]"
projectStageId="#[payload.project_stage_id]"
squareFeet="#[payload.square_feet]"
stateCode="#[payload.state_code]"
timeZone="#[payload.time_zone]"
zip="#[payload.zip]"
parentJobId="#[payload.parent_job_id]"
projectBidTypeId="#[payload.project_bid_type_id]"
projectOwnerTypeId="#[payload.project_owner_type_id]"
projectRegionId="#[payload.project_region_id]"
originId="#[payload.origin_id]"
originData="#[payload.origin_data]"
originCode="#[payload.origin_code]"
sector="#[payload.sector]"
workScope="#[payload.work_scope]"
deliveryMethod="#[payload.delivery_method]"
projectTemplateId="#[payload.project_template_id]"
projectNumber="#[payload.project_number]"
programId="#[payload.program_id]"
storeNumber="#[payload.store_number]"
accountingProjectNumber="#[payload.accounting_project_number]"
designatedMarketArea="#[payload.designated_market_area]"
estimatedValue="#[payload.estimated_value]"
estimatedStartDate="#[payload.estimated_start_date]"
estimatedCompletionDate="#[payload.estimated_completion_date]"
projectTypeId="#[payload.project_type_id]"
imageId="#[payload.image_id]"
officeId="#[payload.office_id]"
projectId="#[payload.project_id]"
county="#[payload.county]"
standardCostCodeListId="#[payload.standard_cost_code_list_id]"
departmentIds="#[payload.department_ids]"
/>

Sample Request

{
"company_id": "562949953437078",
"project_id": "562949955035825",
"active": true,
"address": "123 Main St Updated",
"city": "Anytown Updated",
"country_code": "US",
"county": "Santa Barbara County updated",
"description": "This is mule test project updated",
"erp_integrated": true,
"standard_cost_code_list_id": "562949953436338",
"start_date": "2025-02-01",
"completion_date": "2025-12-30",
"total_value": 100001,
"warranty_start_date": "2025-02-01",
"warranty_end_date": "2026-01-30",
"fax": "0161 999 8888",
"flag": "1",
"locale": "en",
"name": "MuleTest9 - 17 Updated",
"office_id": 562949953582263,
"phone": "123-456-7890",
"project_number": "P3424",
"public_notes": "Public Notes Updated",
"project_stage_id": 562949953421313,
"square_feet": 1001,
"state_code": "AZ",
"time_zone": "US/Mountain",
"zip": "54321",
"parent_job_id": 562949955019589,
"program_id": 562949953520454,
"project_bid_type_id": 562949953465027,
"project_type_id": 562949953482049,
"project_owner_type_id": 562949953439321,
"project_region_id": 562949953470887,
"project_template_id": null,
"department_ids": [
562949953495657,
562949953495655
],
"estimated_value": 1000001,
"estimated_start_date": "2025-02-01",
"estimated_completion_date": "2025-12-30",
"store_number": "1234",
"accounting_project_number": "1234",
"designated_market_area": "Southeast",
"sector": "auto_service",
"work_scope": "renovation_alteration",
"delivery_method": "integrated_project_delivery"
}

OAuth 2.0 Setup

The Procore Connector uses OAuth 2.0 authorization code flow for secure authentication.

Step 1: Create Procore OAuth Application

Follow these steps using the Procore Developer documentation to create your OAuth application:

1. Open the Creating an App article in the Procore Developer documentation.

2. Follow the step-by-step guide to create a new OAuth application.

3. During the setup process, configure the following:

   • Application Name: Enter a descriptive name for your application.

   • Redirect URI: Enter your callback URL. For example, http://localhost:8081/mule/callback.

   • Scopes: Select all required scopes. For example, read:projects and write:projects.

4. Save the application and note your Client ID and Client Secret.

Step 2: Configure OAuth in MuleSoft

<procore:config name="Procore_Config" doc:name="Procore Config">
procore:connection
<procore:oauth-authorization-code
consumerKey="${procore.config.oauth.consumer_key}"
consumerSecret="${procore.config.oauth.consumer_secret}"/>
<procore:oauth-callback-config
listenerConfig="HTTP_Listener_config"
callbackPath="/mule/callback"
authorizePath="/authorize-procore"
externalCallbackUrl="http://localhost:8081/mule/callback" />
</procore:connection>
</procore:config>

Step 3: Authorization Flow

1. Start your MuleSoft application.

2. Go to http://localhost:8081/authorize-procore.
   You will be redirected to the Procore authorization page.

3. Log in with your Procore credentials and authorize the application.
   You will be redirected back to your callback URL. The connector will automatically handle the token exchange and storage.

Error Types

The Procore Connector provides comprehensive error handling with specific error types:

Common Issues

Authentication Problems

• UNAUTHORIZED Error: Check that your OAuth consumer key and secret are correct.

• ACCESS_TOKEN_MISSING: Verify that the OAuth flow completed successfully.

• OAUTH_STATE_MISSING: Ensure that the OAuth callback configuration is correct.

• Scope Issues: Make sure your Procore application has the required scopes.

API Errors

• BAD_REQUEST Error: Verify that all required parameters are provided and that their data types are correct.

• INVALID_REQUEST Error: Check the request's format and structure.

• FORBIDDEN Error: Ensure that your Procore user has the required permissions.

• TOO_MANY_REQUESTS Error: Implement retry logic with exponential backoff.

Resource Errors

• NOT_FOUND Error: Verify that the project or company ID exists and is accessible.

• CONFLICT Error: Check the current state of the resource before performing update operations.

• UNPROCESSABLE_ENTITY Error: Review business logic validation rules.

Connection Issues

• CONNECTIVITY Error: Check your network connectivity and firewall settings.

• SERVICE_UNAVAILABLE Error: The Procore service may be temporarily down.

• REQUEST_TIMEOUT Error: Increase the timeout settings in your configuration.

• GATEWAY_TIMEOUT Error: Check your proxy or load balancer configuration.

Debugging

Enable Debug Logging

Add the following logger configuration to enable debug logging:

Common Debug Information

• Request/Response Logs: Log API request and response details.

• Token Information: Log token refresh events and OAuth state.

• Parameter Validation: Log parameter validation results.

• Error Details: Log detailed error information with Procore error types.

• Connection Events: Log connection creation and failure events.

Support

• Procore API Documentation: developers.procore.com.

• MuleSoft Documentation: docs.mulesoft.com.

• Community Forums: Procore Developer Community.

• Support Tickets: Contact Procore Developer Support.

Development

• Use Secure Properties: Store sensitive configuration in secure properties.

• Implement Error Handling: Always implement proper error handling for all operations.

• Validate Input: Validate all input parameters before making API calls.

• Log Operations: Log operation attempts for debugging and monitoring.

• Test Thoroughly: Test all operations with various parameter combinations.

Production

• Monitor Performance: Monitor API response times and error rates.

• Implement Retry Logic: Implement retry logic for transient errors.

• Use Connection Pooling: Leverage connection pooling for better performance.

• Secure Configuration: Use secure properties for sensitive data.

• Regular Updates: Keep the connector updated to the latest version.

Testing

• Unit Tests: Write unit tests for all operations.

• Integration Tests: Test with the actual Procore API.

• Error Scenarios: Test error handling scenarios.

• Performance Tests: Test with realistic data volumes.

• Security Tests: Test authentication and authorization.

API Endpoints

Data Types

Glossary