What are Applications?

Applications are the way to customize the Vertesia platform for your projects. By creating an application you can:

1. Contribute UI applications focused on the business model of your organization / project.
2. Contribute custom tools.
3. Contribute content types to your project.

Applications are installed at project level.

Creating an application

Applications are created by registering the application manifest in Vertesia Studio > Settings > Applications page.

Each application must have an unique name in kebab case. We recommend prefixing the name of your application using your organization name: vertesia-review-center, foo-contracts etc.

Application manifest

An application manifest is implementing the following interface:

interface AppManifestData {
    /**
     * The name of the app, used as the id in the system.
     * Must be in kebab case (e.g. my-app).
     */
    name: string;

    /**
     * Whether the app is private to the owner account.
     * If true the account property must be defined.
     */
    private: boolean;

    title: string;
    description: string;
    publisher: string;

    /**
     * A svg icon for the app.
     */
    icon?: string;

    status: "beta" | "stable" | "deprecated";

    ui?: {
        /**
         * The source URL of the app. The src can be a template which contain
         * a variable named `buildId` which will be replaced with the current build id.
         * For example: `/plugins/vertesia-review-center-${buildId}`
         */
        src: string;
        
        /**
         * The isolation strategy. If not specified it defaults to shadow 
         * - shadow - use Shadow DOM to fully isolate the plugin from the host.
         * - css - use CSS processing (like prefixing or other isolation techniques). Lighter but plugins may conflict with the host
         */
        isolation?: "shadow" | "css";
    },

    /**
     * A list of tool collections endpoints to be used by this app.
     * A tools collection endpoint is an URL which may end with a `?import` query string.
     * If the `?import` query string is used the tool will be imported as a javascript module and not executed through a POST on the collections endpoint.
     */
    tool_collections?: string[];
}

Applications can be private or public. Private applications can only be installed in projects of the same organization which the one who defined the application. The application will not be visible oin other organizations. Public applications are visible in all the organizations.

In order to use an application you need to install it on a project.

Installing an application on a project

Open the Installations tab in the applications settings page to see the list of the installed applications in the current project or to install a new application.

After installing the application you must define the users or groups that can access the application. This can be done using the Manage permissions button.

Contributing UI applications.

To contribute a custom UI application you need to provide in the application manifest the ui property which specify the URL to the application javascript bundle as the src property and the type of isolation which is shadow by default (meaning that the application will be isolated in a shadow DOM).

Installed Applications that contribute an UI application are visible on the Vertesia Studio UI landing page for users who have the permission to access the application.

To learn how to develop an UI Application plugin go to UI Plugin section.

Contributing custom tools.

Custom tools can be contributed by registering a remote tools server into the tool_collections property. You can contribute as many tools server as you need.

Note that only thew users that can access the application can use these tools.

To learn how to write a tools server go to Custom Tools section.

Example:

{
  "name": "my-tools",
  ...
  "tool_collections": ["https://my-tools-server.com/endpoint"]
}

Contributing content types.

Work is in progress for this feature.