Creating an App Manifest

In order to deploy an App on the Procore platform, you must create a manifest for your App on the Developer Portal. The manifest defines the various components that make up your App and specifies additional instructions that users can follow after they install it. The following sections cover App component types as well as manifest format and structure. You will need to understand these concepts in order to create a proper App manifest.

Understanding App Component Types

The Procore platform currently supports two App component types that you define in the App manifest.

Data connection components are used in Apps that read or write data to/from Procore using the available Procore API resources. Since this type of App requires authentication with the Procore API, the data connection component is used to define the OAuth 2.0 authorization grant type for the App (i.e., authorization_code or implicit). For additional information on OAuth 2.0 authorization grant types, see Choosing an OAuth 2.0 Grant Type. It is important to note that an App can only have one data connection component.

Embedded components are used in Apps that launch in an iframe within the Procore user interface as an embedded experience. Embedded components are used to define the various attributes of an embedded experience App including the App name, the iframe source URL, and any custom fields required for the installation and configuration steps. Currently, Apps designed for the embedded experience can only contain one embedded component instance. If an embedded experience App also requires authentication with the Procore API, then the App manifest also needs to include a data connection component.

App Manifest Format and Structure

The manifest format and structure adheres to the JSON schema. Below is an example App manifest that helps to describe the various sections of the manifest.

{ "schema_version": "3", "app_manifest": { "id": "3c86a740-6aa4-484f-9c67-b0fdef2h7d9" }, "post_installation_instruction": { "page": { "url": "https://example.domain.com/install-page.html", "label": "Post installation instruction page" }, "notes": "these-are-post-installation-setup-notes" }, "components": { "oauth": { "instances": [ { "uid": "f2d0a86d600cdf3cdea581fee47e796e277138d3de1528ddbbbfbd9bdf086457", "uuid": "f553a5d6-26e5-4eb0-b0a7-130f2f77jj90", "grant_type": "authorization_code" } ] }, "iframe": { "instances": [ { "name": "My Sample App", "uuid": "10e58965-49d2-4a3b-a5b1-aeeef0hn67des", "required": true, "iframe_src": "https://{{subdomain}}.domain.com/{{my_path}}?procoreCompanyId={{procore.company.id}}&procoreProjectId={{procore.project.id}}", "description": "A sample app used for demonstration.", "configuration": { "schema": { "type": "object", "required": [ "customInputField" ], "properties": { "customInputField": { "name": "My Custom Input Field", "type": "string", "description": "An example custom input field." } } } } } ] } } }

Let’s dive deeper into the example above to understand the various sections that make up the manifest.

schema_version - denotes the manifest schema version which is automatically generated by the system. You do not need to explicitly define this field in your manifest.

app_manifest - includes a single id field which is automatically generated using App information from the Developer Portal. You do not need to explicitly define this field in your manifest.

post_installation_instruction - (optional) defines specific instructions that must be carried out by the Procore user tasked with installing and setting up the App for use by their organization. This information is displayed to the user at the time of installation, and later via the App Management page in the Procore Web user interface. Use the notes attribute to provide a textual description of any post-installation steps required to properly complete the setup of the App. Use the page:url attribute to specify a link to an external website or downloadable PDF that provides additional information about setting up the App. Use the page:label attribute to specify the label associated with the URL.

components - specifies the various components that make up the App. Data connection components are defined by the oauth attribute. The details of each oauth instance are specified using the following parameters:

  • uid - a unique identifier automatically generated by the system. You do not need to specify a value for uid.
  • uuid - a unique identifier automatically generated by the system. You do not need to specify a value for uuid.
  • grant_type - defines the OAuth 2.0 authorization grant type for the App. Can be set to either authorization_code or implicit. Use authorization_code if your App uses the OAuth 2.0 Authorization Code Grant flow (as in the example above). These Apps store the client secret in a safe and secure (i.e., server-side) location and do not expose it to end users. See Choosing an OAuth 2.0 Grant Type and OAuth 2.0 Authorization Code Grant Flow for additional information. Use implicit if your App uses the OAuth 2.0 Implicit Grant flow. These Apps, such as single-page javascript browser applications, do not utilize or require a client secret. See OAuth 2.0 Implicit Grant Flow for additional information.

Embedded components are defined by the iframe attribute. The details of an iframe instance are specified using the following parameters:

  • uuid - a unique identifier for the instance which is automatically generated by the system. You do not need to specify a value for uuid.
  • required - a boolean value (true/false) that indicates whether the instance is required to properly configure the App in a project in Procore.
  • name - a meaningful name for the iframe instance.
  • description - a short summary of the iframe instance.
  • iframe_src - defines the URL for your embedded App including any path/query parameters that are required for your App to function properly. In the example above, we see the following live-interpolated variables included to further define the behavior of the App.
    • 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 the App has been configured for.
    • procore.project.name - Name of the project the App has been configured for.

    Variables such as these can be included in your iframe_src definition to pass parameters or to define a part of the path by using curly-brace syntax as shown below.
    https://{{subdomain}}.domain.com/{{my_path}}?procoreCompanyId={{procore.company.id}}&procoreProjectId={{procore.project.id}}

    Configurable fields are URI encoded before being interpolated for security. As a result, values assigned to these variables should not contain special characters. For example: "iframe_src": "https://my-domain.com/{{my_path}}" where my_path is set to resource/id will point to https://my-domain.com/resource%2fid rather than https://my-domain.com/resource/id, resulting in a 404 error. This situation can be avoided by breaking the configurable field into two configurable fields. For example:
    "iframe_src": "https://my-domain.com/{{resource}}/{{id}}"

  • configuration - defines the various properties, or configurable fields, Procore company administrators use to configure your App in a Procore project.
    • schema - specifies which properties are considered mandatory when creating an App configuration in a project using the required attribute. The properties attribute is used to define the details of each configurable field, both required and optional.

    Referring to our example, we see that customInputField is included in the required attribute, while the name, type, and description for the field is defined in the properties attribute.

Creating the Initial Sandbox Manifest Version

App manifests are first created in the context of your development sandbox. You can create any number of sandbox manifest versions for development and test purposes. After you have successfully validated your manifest in the sandbox environment, you can promote it to the production environment. The following steps outline the process of creating the initial version of your App manifest.

  1. Log in to the Developer Portal, go to My Apps, then select the App you want to create a manifest for.
  2. Scroll down to the ‘Manage Manifests’ section, verify that the ‘Sandbox’ tab is selected, then click Create New Version. The manifest editor displays a template to help you get started with the required structure and format for your manifest. In addition, there are 'helpers' for creating Data Connection and Embedded component code snippets that you can paste into your manifest. The editor provides built-in validation so that you are notified when the format of your manifest does not conform to the required structure.
  3. After you finish constructing your manifest in the editor, click Create.

Creating New Manifest Versions

After you have created the initial sandbox version of your App manifest, you can iterate through your development/test cycle and create subsequent versions as needed to address changes in your App. Complete the following steps to create additional manifest versions.

  1. In the 'Manage Manifests' section, click Create New Version. The editor displays the content from your last manifest version.
  2. Make changes to the manifest as needed and click Create. Your new manifest version is saved and the version number is incremented by one (1).
  3. Repeat Steps 1 and 2 for each additional manifest version you want to create.