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.

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 properties and settings for a Developer Managed Service Account (DMSA) associated with the application. See Developer Managed Service Accounts for additional information and steps for building a data connection App. A DMSA utilizes the client credentials OAuth 2.0 authorization grant type. 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. 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.


{
  "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",
          "type": "sidepanel",
          "uuid": "10e58965-49d2-4a3b-a5b1-aeeef0hn67des",
          "views": [
            "commitments.work_order_contracts.detail"
          ],
          "required": true,
          "iframe_src": "https://{{subdomain}}.domain.com/{{my_path}}?procoreCompanyId={{procore.company.id}}&procoreProjectId={{procore.project.id}}&myCustomField={{myCustomField}}",
          "description": "A sample app used for demonstration.",
          "configuration": {
            "schema": {
              "type": "object",
              "required": [
                "myCustomField"
              ],
              "properties": {
                "myCustomField": {
                  "name": "My Custom Input Field",
                  "type": "string",
                  "description": "An example custom input field that can be included as a parameter in iframe_src."
                }
              }
            }
          }
        }
      ]
    }
  }
}

Let’s dive deeper into the example above to understand the various sections that make up the 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 - 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 client_credentials.

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

  • name - a meaningful name for the iframe instance.
  • type - defines the embedded component type as either fullscreen or sidepanel.
  • uuid - a unique identifier for the instance which is automatically generated by the system. You do not need to specify a value for uuid.
  • views - defines the tools/views where a side panel application can be displayed.
  • required - a boolean value (true/false) that indicates whether the instance is required to properly configure the App in a project in Procore.
  • 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}}".
    • myCustomField - Name of a custom field defined for your App. (see below)
  • 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 myCustomField is defined as required, with the name, type, and description for the field defined in the properties attribute. Configurable fields you define can be included in the iframe_src path.

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.

  3. Enter a version number for the manifest. We recommend using ‘0.0.1’ as an initial manifest version.

    Create New Version Semantic

  4. 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.
  5. 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. Enter a new version number following the semantic versioning scheme.
  3. Make changes to the manifest as needed and click Create.
  4. Repeat Steps 1-3 for each additional manifest version you want to create.