Building Procore Data Connection Applications with DMSA

Note: This article covers topics consistent with the App Manifest v4.1 format. For information on the App Manifest v3.x (legacy) format, see App Manifest v3.x Legacy Format and Migrating an App Manifest from v3.x to v4.1.

Overview

The following sections provide step-by-step instructions for creating a new data connection app manifest that utilizes a Devloper Managed Service Account (DMSA). This article provides details on the following steps for creating a new data connection application:

• Create a New Application
• Specify Tool Permissions Using Permission Builder
• Define Setup Instructions and Post-Installation Notes
• Save Manifest and Create Version
• Promote Updated Sandbox Manifest to Production

Create a New Application

1. Open your browser, navigate to the Developer Portal landing page and click Sign In.

2. Click Sign In with your Procore Account and log in using your Procore account credentials.

   

3. Navigate to the My Apps page and click Create a New App. The Create New App dialog displays.

   

4. Enter an App Name. This will be the name you use to refer to your app internally within your organization.
5. Click Create App. A development sandbox is generated for your new app. You will receive an email when your sandbox is ready.

Add a New Data Connector Component

Data connector components define how your app syncs data with Procore. Data connector components enable you to create, update, and read data from Procore to the connected platform through a Client ID and Client Secret. Select between User Level Authentication, Service Account Authentication, or both based on your app’s functionality and security requirements.

1. Navigate to the Configuration Builder and expand the Data Connector Components section.
2. Click Add Components.
3. Choose a Component Type:
   • User Level Authentication - The integration will interact on behalf of a user and limit the API response body based on their Procore permissions (OAuth 2.0 authorization code).
   • Service Account Authentication - The integration will use a (DMSA) service account (OAuth 2.0 Client Credentials).

4. Selecting the Service Account Authentication component type displays a permissions builder where you can define the company level and project level tool permissions required to install and use your integration. Refer to the User Permissions Matrix for additional information.

   

5. On the Company tab, define the required permission levels (Read Only, Standard, or Admin) for each Company level tool that is accessed by your app.
6. Repeat the previous step on the Project tab to define Project level tool permissions.
7. Click Save Component. Your data connector component is updated with the permissions you defined in the permissions builder.

Define Setup Instructions and Post-Installation Notes

You can define additional setup instructions and post-installation notes to help Procore users successfully install and set up your application within a Procore project. Setup instructions and post-installtion notes are a great way to let your users know that there may be addtional steps required for them to properly install and set up your application. For example, Procore users installing your application may need to go through a signup process, establish an account, or configure some settings on your platform before completing the application setup. Instructions are displayed to the user once an application is installed, and are accessible later from within the App Management feature in the Procore Admin tool.

1. Expand the Instructions and Post-Installation Notes section.
2. In the Instructions URL field, enter the web address for your company support site, or web-based installation steps for your application.
3. In the Instructions Page Name field, enter the label you want to use for the hyperlink text for the Instructions URL you defined in step 2.
4. In the Post-Installation Notes field, provide a textual description of any post-installation steps required to properly complete the setup of your application.

Create Intitial App Manifest Version

After completing the steps above, you’re ready to save your app configuration in the App Manifest and set the initial version number.

1. In the Configuration Builder, click Create Version.
2. Enter a version number using the following syntax: x.x.x. For example, ‘1.1.1’. Each new version you create must be a higher number than the previous version.
3. Click Create. The new version is saved with a status of Ready for Testing.

[As you make ongoing changes to the app configuration during development, you can save these changes as new versions using the Save Version button.]

Test and Validate in Development Sandbox

We recommend testing and validating each version of your application in the development sandbox environment. See Installing an Application in the Development Sandbox for additional information.

Promote Updated Sandbox Manifest to Production

After you have successfully tested and validated your updated manifest in the development sandbox environment, you can promote it to the production environment. See Promoting a Sandbox Manifest to Production for additional information.