Building Procore Full Screen Applications

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

With the Procore platform, developers have the capability to develop and deploy embedded Apps that display directly within the Procore user interface. This embedded functionality benefits the end user by enabling streamlined and more efficient workflows. With an embedded App, the user does not need to constantly switch between Procore and another application, resulting in a more unified and improved user experience. The behavior and settings for embedded applications are defined in the App manifest.

This article provides details on the following steps for building a full screen (embedded) application:

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.

    Dev Portal Login Panel

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

    Create a New App

  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 Full Screen Component

The first step in configuring your new full screen embedded application is to add a component. Note that only full screen 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 full screen component.

1. Specify Component Type, Description, and Application URL

  • Navigate to the Configuration Builder on the Manage App page, expand the Components section and click Add Component.
  • Using the drop-down, select Full Screen 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).

    Component Type and App URL

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.

    Component Add Param

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

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

    Component Add Param Field

  • Click Save Parameter.

3. Save the New Component

  • Once you have successfully created a new full screen component and defined the component Type, application URL, and URL Parameter(s), click Save Component.

    Component Save

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.

Post Install Steps

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.