Building Procore Side Panel Applications

Note: This article covers topics consistent with the App Manifest v4.1 format and the form-based app creation UI experience. 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

Procore has expanded the capabilities of the Procore platform to include a context-aware side panel experience in addition to the full screen embedded experience. Developers can now build applications that display in a side panel iframe located on the right side of the Procore user interface. Procore users click a dock icon to launch the side panel experience. Side panel applications operate in the context of specific tools/views in Procore. Developers use the application manifest to define the specific tools and views their side panel application supports. Company administrators install side panel applications and create application configurations using the same installation flow as full screen embedded applications.

This article provides details on the following steps for creating a new side panel application:

• Create a New Application
• Add a Side Panel Component
  • Specify Component Type and Application URL
  • Define Parameter Interpolation
  • Specify Supported Side Panel Views
  • Save the New Component
• Define Setup Instructions and Post-Installation Notes
• Promote Updated Sandbox Manifest to Production
• Save Manifest and Create Version
• Test and Validate in Development Sandbox
• Using postMessage to Retrieve Procore Context

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 Side Panel Component

The first step in configuring your new side panel application is to add a component. Note that only fullscreen embedded and side panel applications require that components be defined. If you are building a data connection application based on developer managed service accounts (DMSA), you do not need to add a component in the Configuration Builder. See Understanding App Types for additional information on application types and components. Follow these steps to add a new side panel component.

1. Specify Component Type, Description, and Application URL

• Navigate to the Configuration Buidler on the Manage App page, expand the Components section and click Add Component.
• Using the drop-down, select Side Panel for the component Type.
• Enter a Description for the component. This is a custom description used solely as an identifier.

• In the URL field, specify the base web address for your application. (e.g., https://example.com/1234/12).

  

2. Define Parameter Interpolation

URL Parameter Interpolation is a method used in web development to insert variable data into a URL. In the context of a Procore integration application, it is used to add specific values to the URL that can then be used to request specific data from the application server. This technique is often used in HTTP GET requests, where data is passed as parameters in the URL itself.

Interpolation comes into play when these parameter values are dynamic - that is, they change based on user input or some other variable. Developers can use interpolation to insert these variable values into the URL. The Procore platform supports URL parameter interpolation for different sections of the URL, which you define when adding a component. You can interpolate values for the URL subdomain, path parameters, and query parameters. For example:

Subdomain

https://{{subdomain}}.domain.com

Path Parameters

https://example.domain.com/{{my_path1}}/{{my_path2}}

Query Parameters

?companyId={{procore.company.id}}&companyName={{procore.company.name}}&projectId={{procore.project.id}}&projectName={{procore.project.name}}&customField={{CustomField}}

The Procore platform provides the following built-in variables for use as query parameters.

• procore.company.id - ID of the company where the App is installed.
• procore.company.name - Name of the company where the App is installed.
• procore.project.id - ID of the project in which the App has been configured.
• procore.project.name - Name of the project in which the App has been configured.

When included as URL parameters for your embedded (full screen or side panel) application, these values can be used to determine which company and project a user is working in. The procore.project.id variable is commonly used in scenarios where data for the same Procore project lives in an external system and allows the embedded application to access the externally mapped/synced project.

You can also define your own custom field variables for use as query parameters. Custom field variables can be specified as required or optional. Values for custom parameters are set by the user during installation allowing you further personalize your application. Custom parameters are extremely flexible and can be used for any number of purposes. Some common uses for custom parameters include entering an ID number for a specific device in a drone/site camera application, specifying a membership or subscription ID for an application, or defining the locale in which an application will be used.

• Add one or more custom URL Parameters to the component by clicking Add Parameter.

  

• Define the Name, Key, and Description for the custom parameter.

• Specify whether the parameter is required at time of installation.

  

• Click Save Parameter.

3. Specify Supported Side Panel Views

You can specify which tools, resources, and actions your application works with and from which page(s) it will be accessible. As some tools comprise more than one resource (e.g., commitments), this approach is both granular and flexible. For example, you might want your app to display only on the list page, but not on the detail page.

• Use the Side Panel Views drop-down list to select one or more side panel Views for your application.

  

The following sections list the currently supported Side Panel Views that can be defined in the application manifest.

Commitments

Commitments Beta

Contracts

Prime Contracts

Change Events

Budget

Submittal Logs

Project Directory

Observations

RFIs

Inspections

Correspondence

Schedule

Incidents

4. Save the New Component

• Once you have successfully created a new side panel component and defined the Type, Description, URL, Parameter(s), and View(s), click Save Component.

  

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.

Save Manifest and Create Version

After completing the steps above, you’re ready to save your application configuration and set your first version number.

1. Click Save at the top of the page.
2. The Create Version window appears. Enter a version number using the following syntax: x.x.x. Note: Your version number can only contain integers, and must consist of three (3) integers separated by a ‘.’. For example, ‘1.1.1’. Each new version you create must be a higher number than the previous version.

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.

Using postMessage to Retrieve Procore Context

The Procore Side Panel feature supports the MessageEvent interface and Window.postMessage() method to determine the Procore context in which a side panel application instance is running. The information retrieved from a message event sent from the parent window includes the following data fields.

• Company ID = event.data.context.company_id
• Project ID = event.data.context.project_id
• Resource ID = event.data.context.id
• View = event.data.context.view

To access context data using the MessageEvent interface, add an event listener to your page and the postMessage method to initialize communication with the parent window. Here is some example code that demonstrates retrieving context data from the message event object. Note the use of conditional statements with the postMessage method to account for Multiple Procore Regions. Be sure to account for all regions where your application needs to retrieve Procore context. Be aware that as new Procore regions become available, your postMessage code must be updated to support these new regions.

window.addEventListener('message', (event) => {

  const obj = event.data;
  if (obj.type === “setup”) {
    const company_id = obj.context.company_id;
    const project_id = obj.context.project_id;
    const view = obj.context.view;
    const resource_id = obj.context.id;
  }});

if (document.referrer === "https://app.procore.com/") { window.parent.postMessage({ type: 'initialize' }, "https://app.procore.com/"); }
if (document.referrer === "https://us02.procore.com/") { window.parent.postMessage({ type: 'initialize' }, "https://us02.procore.com/"); }
if (document.referrer === "https://uk01.procore.com/") { window.parent.postMessage({ type: 'initialize' }, "https://uk01.procore.com/"); }

In the example above we have set the value for the targetOrigin parameter of the postMessage method to https://example.com/my-side-panel-app. The targetOrigin parameter in this method specifies the origin of the window that should receive the message. It is important that you always provide a specific, fully-qualified URI in the targetOrigin parameter to ensure the best security. For additional information, see the postMessage() method documentation.

Additional postMessage Events

Aside from the “setup” message event that is fired when your app is first started, there are additional events fired at different life cycles of the side panel app. All of these events are fired as a postMessage from Procore to your app’s window. You can listen to “message” events and filter for the data “type”.

window.addEventListener('message', (event) => {
  const obj = event.data;
  if (obj.type === “sidepanel:app:visible”) {
    // do something for when app is visible
  }
  if (obj.type === “sidepanel:app:hidden”) {
    // do something for when app is hidden, but still running
  }
  if (obj.type === “sidepanel:app:destroy”) {
    // do something for when app is about to be removed from the DOM
  }
});