Building app manifests

Introduction to app manifests

The app manifest serves as the framework for Uberflip apps. It allows your apps to create functionality in the Uberflip platform to integrate externally hosted components, and to implement certain app features and functions within Uberflip Hubs. For example, if you have a web app that you want to integrate with the Uberflip platform, the app manifest allows you to do things like:

• Display your app's externally hosted interface in the Uberflip web application (via iframe)
• Create navigation menu items to allow users to access your app from within Uberflip
• Create licenses to control access to your app
• Create configuration fields that accept user inputs and leverage Liquid variables to dynamically inject these values into your app's code
• Inject HTML, CSS and JavaScript into Uberflip Hubs to modify their look and feel, and add functionality

How app manifests are structured

At a high level, app manifests are JSON files that consist of one or more predefined objects. Each object represents a type of functionality (or asset) that can be created by the manifest.

The following objects are available to be included in an app manifest:

To build an app manifest, simply choose the objects that your app requires and add them to the JSON file.

Guidelines for adding objects to a manifest

• All of the objects are optional. As a result, a valid manifest can include any number of objects in any combination.
• Objects can appear in a manifest in any order (if there are dependencies within the manifest, these are evaluated when the manifest is evaluated by the Uberflip platform).
• Objects that appear in the manifest must create functionality (i.e. must not be empty), otherwise they must be omitted.
• A maximum of one instance of each object can appear in the manifest. All functionality related to a given object must be grouped within the single instance of that object. For example, you can't add a config_fields object, then a users object, and then another config_fields object.

How objects are structured

Structurally, all of the objects listed above are actually arrays, and contain one or more objects themselves. This allows a single object to create multiple separate assets belonging to the same class of functionality. For example, a users object can be an array of multiple individual objects that each create a separate user.

Although they are not explicitly labelled as such in the manifest, the name of a lower-level object within a "top-level" object's array is always the singular form of the object name. For instance, a users object (top-level, plural) is an array of one or more user objects (lower-level, singular).

Every lower-level object in such an array consists of multiple properties. These properties are specific to the object type, and are key-value pairs that are used to define the asset created by the object. For example, a user object contains a last_name property whose value defines the user's last name.

All objects have a number of required properties, and most also have some optional properties. If you choose not to use an optional property (i.e. you do not specify a value for it), you must omit it from the object. Some properties accept user-created values, while others require a value from a predefined list.

How objects interact within an app manifest

Within a manifest, some objects can interact with other objects in various ways to create linked functionality. For example, the Uberflip platform supports the concept of assigning permissions at the user group level: if an app manifest creates both a permission and a user group, it can also link the two so that the permission is automatically granted to the user group.

An object can interact with another object by referencing an asset it creates. Objects where this is possible contain a dedicated (optional) property for this purpose. In the example above, you would do this by referencing the permission asset (created by a global_permission object) in the relevant property of the user_group object to which the permission should be granted.

In addition to assets created within the same manifest, objects may also reference a variety of built-in Uberflip assets, such as system default permissions, user groups, and navigation elements.

How to define assets

All objects contain a code property, and the value of this property is used to uniquely identify the asset it creates. As with all properties, you must specify value of the code property for each object you include in your manifest. This value must be preceded by an underscore ("_"), for example:

"code": "_NEW_VALUE".

This distinguishes manifest-created assets from Uberflip system default assets, whose code values are not preceded by an underscore, for example:

"code": "SYSTEM_VALUE"

How to reference assets

To reference an asset created by another object, you use the value of that asset's code property as the value of the appropriate property in the target object. For example, a user_group object has a global_permission_codes property. This property is intended to reference the code value of a permission asset created within a global_permission object (or multiple values). For example:

"global_permission_codes": ["_EXAMPLE_PERMISSION"]

Alternatively, you can also reference an Uberflip system default asset rather than one created by your manifest. In this case, you would simply use the predefined code value of the system default asset, which you can find in the lookup tables here.

Anytime you reference an external asset within an object, remember that the value of code must:

• Begin with an underscore for all assets created in the same manifest, and
• Begin without an underscore for all Uberflip system default assets

📘

Finding code values with dot notation

Throughout this guide, anywhere a property is intended to reference an asset from another object (or a system default asset), we have indicated where you can find the appropriate code property and value. The location is given in dot notation, in this format:

top_level_object_name.lower_level_object_name.code

For example, a permission asset (that could be referenced in a user_group object) would be found in the following location:

global_permissions.global_permission.code

This notation indicates that the location is in the code property of any global_permission object (lower-level) within the global_permissions object (top-level).

Example App Manifest

Below is an example of a valid app manifest. It is adapted from the app manifest used in the app development tutorial, and illustrates various concepts described on this page.

{
	"global_permissions": [{
		"code": "_GTM",
		"name": "Google Tag Manager",
		"description": "All Google Tag Manager Permissions",
		"children": [{
				"code": "_GTM_READ_CONFIG",
				"name": "Read Configs",
				"description": "Grants permission to view Google Tag Manager configuration fields."
			},
			{
				"code": "_GTM_WRITE_CONFIG",
				"name": "Edit Configs",
				"description": "Grants permission to edit Google Tag Manager configuration fields."
			}
		]
	}],
	"account_code_blocks": [{
		"code": "_GTM_SNIPPET",
		"name": "Google Tag Manager Script",
		"description": "Full Google Tag Manager snippet",
		"content": " <!-- Global site tag (gtag.js) - Google Analytics --> <script async src='https://www.googletagmanager.com/gtag/js?id={{gtm_id}}'></script>",
		"placement_code": "BODY_BOTTOM"
	}],
	"config_fields": [{
		"name": "gtm_id",
		"code": "_GTM_ID",
		"label": "Google Tag Manager ID",
		"description": "This field requires _GTM_WRITE_CONFIG permission to be editable!",
		"ordinal": 0,
		"control_type": "textbox",
		"category": "integrations",
		"scopes": ["hub", "account"],
		"read_permission_codes": ["_GTM_READ_CONFIG"],
		"write_permission_codes": ["_GTM_WRITE_CONFIG"]
	}]
}