Ce manuel d’utilisateur fournit des instructions étape par étape pour la mise en œuvre et l’utilisation du connecteur Procore. Le connecteur Procore pour MuleSoft permet une intégration transparente entre les applications MuleSoft et la plateforme de gestion de projets de construction de Procore. Ce connecteur fournit un ensemble complet d’opérations pour la création, la gestion et l’interaction avec les projets de construction via l’API REST de Procore.

Procore est une plateforme de gestion de projets de construction de premier plan qui aide les professionnels de la construction à gérer les projets, les ressources et les finances, de la planification à la clôture. La plateforme fournit des outils pour la gestion de projet, la qualité et la sécurité, la Gestion financière et la Productivité du chantier.

• Authentification OAuth 2.0 : Connexion sécurisée à l’Procore API à l’aide du flux de code d’autorisation OAuth 2.0.

• Gestion de projet : créez et mettez à jour des projets de construction avec des détails complets sur le projet.

• Opérations spécifiques à l’entreprise : Toutes les opérations prennent en charge les contextes spécifiques à l’entreprise via l’ID d’entreprise Procore.

• Gestion avancée des erreurs : Gestion robuste des erreurs avec une journalisation détaillée et une gestion appropriée des exceptions.

• Prise en charge géographique : Prise en charge complète de la latitude, de la longitude et des informations géographiques.

• Chantiers personnalisés : prise en charge des chantiers personnalisés et des métadonnées.

• Intégration des codes de coût : gestion et copie des codes de coût standard.

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

Créer une opération de projet

L’opération Créer un projet vous permet de créer de nouveaux projets de construction dans Procore.

Paramètres

Informations de base

Informations sur le lieu

Informations sur la chronologie

Informations financières

Classification des projets

Structure organisationnelle

Contact et communication

Intégration et origine

Configuration du code de coût

Paramètres supplémentaires

Exemple d’utilisation

<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]"
/>

Demande d’échantillon

{
"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
}

Mettre à jour le fonctionnement du projet

L’opération Mettre à jour le projet vous permet de modifier des projets de construction existants dans Procore.

Paramètres

Paramètres requis

Informations de base

Informations sur le lieu

Informations sur la chronologie

Informations financières

Classification des projets

Structure organisationnelle

Contact et communication

Intégration et origine

Configuration du code de coût

Paramètres supplémentaires

Exemple d’utilisation

<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]"
/>

Demande d’échantillon

{
"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.

Types d’erreur

Le connecteur Procore offre une gestion complète des erreurs avec des types d’erreurs spécifiques :

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.

Développement

• Utiliser des propriétés sécurisées : Stockez la configuration sensible dans des propriétés sécurisées.

• Implémenter la gestion des erreurs : Mettez toujours en œuvre une gestion appropriée des erreurs pour toutes les opérations.

• Valider l’entrée : Validez tous les paramètres d’entrée avant d’effectuer des appels d’API.

• Opérations de journalisation : Consigner les tentatives d’opération à des fins de débogage et de surveillance.

• Testez minutieusement : Testez toutes les opérations avec différentes combinaisons de paramètres.

Fabrication

• Surveiller les performances : Surveillez les temps de réponse et les taux d’erreur de l’API.

• Implémenter la logique de nouvelle tentative : Implémentez une logique de nouvelle tentative pour les erreurs temporaires.

• Utiliser le regroupement de connexions : Tirez parti du regroupement de connexions pour de meilleures performances.

• Configuration sécurisée : Utilisez des propriétés sécurisées pour les données sensibles.

• Mises à jour régulières : Maintenez le connecteur à jour vers la dernière version.

Tests

• Tests unitaires : Écrire des tests unitaires pour toutes les opérations.

• Tests d’intégration : testez avec l’API Procore API réelle.

• Scénarios d’erreur : Tester les scénarios de gestion des erreurs.

• Tests de performance : Testez avec des volumes de données réalistes.

• Tests de sécurité : testez l’authentification et l’autorisation.

API Endpoints

Data Types

Glossary