MuleSoft - Technical Reference

Prerequisites

Before you create a Mule project with the Procore connector, ensure you have the following:

• MuleSoft Anypoint Studio 7.x or higher.
• Mule Runtime 4.9.6 or higher.
• Java 17 or higher.
• Procore developer account with API access.
• OAuth 2.0 credentials from Procore.

Project Setup

<dependency>
 <groupId>com.procore</groupId>
 <artifactId>procore-connector</artifactId>
 <version>0.0.115-SNAPSHOT</version>
 <classifier>mule-plugin</classifier>
</dependency>

# 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

HTTP Listener Configuration

Configure the HTTP listener for your Mule application:

<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

Configure the Procore connector with OAuth 2.0 authentication:

<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="${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:

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

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

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

Basic Project Creation Flow

Create a flow to handle project creation requests:

<flow name="createProjectFlow">
 <http:listener config-ref="HTTP_Listener_config" path="/create-project"/>
 
 <!-- Validate input payload -->
 <validation:is-not-null value="#[payload.company_id]" message="Company ID is
required"/>
 <validation:is-not-null value="#[payload.name]" message="Project name is required"/>
 
 <!-- Transform payload if needed -->
 <ee:transform>
 <ee:message>
 <ee:set-payload><![CDATA[%dw 2.0
output application/java
---
{
 companyId: payload.company_id,
 name: payload.name,
 address: payload.address,
 city: payload.city,
 stateCode: payload.state_code,
 countryCode: payload.country_code,
 zip: payload.zip,
 description: payload.description,
 startDate: payload.start_date,
 completionDate: payload.completion_date,
 totalValue: payload.total_value
}]]></ee:set-payload>
 </ee:message>
 </ee:transform>
 
 <!-- Call Procore API -->
 <procore:create-project config-ref="Procore_Config"
 companyId="#[payload.companyId]"
 name="#[payload.name]"
 address="#[payload.address]"
 city="#[payload.city]"
 stateCode="#[payload.stateCode]"
 countryCode="#[payload.countryCode]"
 zip="#[payload.zip]"
 description="#[payload.description]"
 startDate="#[payload.startDate]"
 completionDate="#[payload.completionDate]"
 totalValue="#[payload.totalValue]"/>
 
 <!-- Handle response -->
 <ee:transform>
 <ee:message>
 <ee:set-payload><![CDATA[%dw 2.0
output application/json
---
{
 success: true,
 projectId: payload.id,
 projectName: payload.name,
 message: "Project created successfully"
}]]></ee:set-payload>
 </ee:message>
 </ee:transform>
</flow>

Project Update Flow

Create a flow to handle project updates:

<flow name="updateProjectFlow">
 <http:listener config-ref="HTTP_Listener_config" path="/update-project"/>
 
 <!-- Validate required parameters -->
 <validation:is-not-null value="#[payload.project_id]" message="Project ID is
required"/>
 <validation:is-not-null value="#[payload.company_id]" message="Company ID is
required"/>
 
 <!-- Call Procore API -->
 <procore:update-project config-ref="Procore_Config"
 companyId="#[payload.company_id]"
 projectId="#[payload.project_id]"
 name="#[payload.name]"
 active="#[payload.active]"
 address="#[payload.address]"
 city="#[payload.city]"
 description="#[payload.description]"
 startDate="#[payload.start_date]"
 completionDate="#[payload.completion_date]"
 totalValue="#[payload.total_value]"/>
 
 <!-- Handle response -->
 <ee:transform>
 <ee:message>
 <ee:set-payload><![CDATA[%dw 2.0
output application/json
---
{
 success: true,
 projectId: payload.id,
 projectName: payload.name,
 message: "Project updated successfully"
}]]></ee:set-payload>
 </ee:message>
 </ee:transform>
</flow>

Error Handling Flow

Create a global error handler for your application:

<error-handler name="GlobalErrorHandler">
 <on-error-continue type="PROCORE:BAD_REQUEST">
 <ee:transform>
 <ee:message>
 <ee:set-payload><![CDATA[%dw 2.0
output application/json
---
{
 success: false,
 error: "Bad Request",
 message: error.description,
 details: error.detailedDescription
}]]></ee:set-payload>
 </ee:message>
 </ee:transform>
 <http:response-builder statusCode="400"/>
 </on-error-continue>
 
 <on-error-continue type="PROCORE:UNAUTHORIZED">
 <ee:transform>
 <ee:message>
 <ee:set-payload><![CDATA[%dw 2.0
output application/json
---
{
 success: false,
 error: "Unauthorized",
 message: "Invalid or expired authentication credentials"
}]]></ee:set-payload>
 </ee:message>
 </ee:transform>
 <http:response-builder statusCode="401"/>
 </on-error-continue>
 
 <on-error-continue type="PROCORE:FORBIDDEN">
 <ee:transform>
 <ee:message>
 <ee:set-payload><![CDATA[%dw 2.0
output application/json
---
{
 success: false,
 error: "Forbidden",
 message: "Insufficient permissions to access the resource"
}]]></ee:set-payload>
 </ee:message>
 </ee:transform>
 <http:response-builder statusCode="403"/>
 </on-error-continue>
 
 <on-error-continue type="PROCORE:NOT_FOUND">
 <ee:transform>
 <ee:message>
 <ee:set-payload><![CDATA[%dw 2.0
output application/json
---
{
 success: false,
 error: "Not Found",
 message: "The requested resource was not found"
}]]></ee:set-payload>
 </ee:message>
 </ee:transform>
 <http:response-builder statusCode="404"/>
 </on-error-continue>
 
 <on-error-continue type="ANY">
 <ee:transform>
 <ee:message>
 <ee:set-payload><![CDATA[%dw 2.0
output application/json
---
{
 success: false,
 error: "Internal Server Error",
 message: "An unexpected error occurred"
}]]></ee:set-payload>
 </ee:message>
 </ee:transform>
 <http:response-builder statusCode="500"/>
 </on-error-continue>
</error-handler>

Input Validation Transformation

Create a DataWeave transformation to validate and transform input data:

<ee:transform>
 <ee:message>
 <ee:set-payload><![CDATA[%dw 2.0
output application/java
---
{
 companyId: payload.company_id default "",
 name: payload.name default "",
 address: payload.address default "",
 city: payload.city default "",
 stateCode: payload.state_code default "",
 countryCode: payload.country_code default "US",
 zip: payload.zip default "",
 description: payload.description default "",
 startDate: payload.start_date default "",
 completionDate: payload.completion_date default "",
 totalValue: payload.total_value default 0.0,
 latitude: payload.latitude default "",
 longitude: payload.longitude default "",
 phone: payload.phone default "",
 projectNumber: payload.project_number default "",
 active: payload.active default true
}]]></ee:set-payload>
 </ee:message>
</ee:transform>

Response Transformation

Create a DataWeave transformation for API responses:

<ee:transform>
 <ee:message>
 <ee:set-payload><![CDATA[%dw 2.0
output application/json
---
{
 success: true,
 data: {
 id: payload.id,
 name: payload.name,
 description: payload.description,
 active: payload.active,
 address: payload.address,
 city: payload.city,
 stateCode: payload.stateCode,
 countryCode: payload.countryCode,
 zip: payload.zip,
 startDate: payload.startDate,
 completionDate: payload.completionDate,
 totalValue: payload.totalValue,
 createdAt: payload.createdAt,
 updatedAt: payload.updatedAt
 },
 message: "Operation completed successfully"
}]]></ee:set-payload>
 </ee:message>
</ee:transform>

Local Development

For local development:

1. Run the application in Anypoint Studio.
2. Use localhost endpoints for testing.
3. Configure local OAuth callback URLs.
4. Use the Procore development environment.

CloudHub Deployment

For CloudHub deployment:

1. Package your application as a JAR file.
2. Deploy the application to CloudHub through Runtime Manager.
3. Configure environment-specific properties.
4. Set up OAuth callback URLs.
5. Configure SSL certificates.

Secure Configuration

1. Use secure properties for sensitive data.
2. Never commit credentials to version control.
3. Use environment variables for production.
4. Rotate credentials regularly.

OAuth Security

1. Use HTTPS for all OAuth endpoints.
2. Validate OAuth scopes.
3. Implement proper token management.
4. Monitor authentication failures.

Input Validation

1. Validate all input parameters.
2. Sanitize user input.
3. Implement proper error handling.
4. Log security events.

Common Issues

Debugging

<logger name="com.procore.mule" level="DEBUG"/>

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.
• Validate Input: Validate all input parameters before API calls.
• Log Operations: Log operation attempts for debugging.
• 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

Procore Error Codes

Data Types

Glossary