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.
"label": "Post installation instruction page"
"name": "My Sample App",
"description": "A sample app used for demonstration.",
"name": "My Custom Input Field",
"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
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
uuid- a unique identifier automatically generated by the system. You do not need to specify a value for
grant_type- defines the OAuth 2.0 authorization grant type for the App. Can be set to either
authorization_codeif 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
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
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
description- a short summary of the
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.
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
propertiesattribute is used to define the details of each configurable field, both required and optional.
Variables such as these can be included in your
iframe_src definition by using curly-brace syntax as shown below.
Referring to our example, we see that
customInputField is included in the
required attribute, while the
description for the field
is defined in the
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.
- Log in to the Developer Portal, go to My Apps, then select the App you want to create a manifest for.
- 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.
- 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.
- In the 'Manage Manifests' section, click Create New Version. The editor displays the content from your last manifest version.
- 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).
- Repeat Steps 1 and 2 for each additional manifest version you want to create.