App Manifest v3.x Legacy Format

Background

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

Example v3.x 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."
                }
              }
            }
          }
        }
      ]
    }
  }
}

Manifest v3.x Objects and Attributes

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.
  • 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 client_credentials if your App uses a Developer Managed Service Account to specify required tool permissions and permitted projects. See Using the OAuth 2.0 Client Credentials Grant Type and Developer Managed Service Accounts for additional information.

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.