Platform Assets

Platform assets are Maven artifacts classified by a nature element which serve the purpose to setup a tribefire instance in an incremental and reproducible way. Depending on the nature, the assets can range from data to code.

General

You may think of platform assets as puzzle pieces that let you add and remove functionality using a central platform asset repository. This functionality doesn't only include tribefire-built apps and components, but also the tribefire platform itself. The assets that make up the platform are called tribefire assets.

Using platform assets allows you to easily create and enrich your tribefire instance. Moreover, you keep track of changes in tribefire elements as each asset is versioned.

You can use platform assets to store:

• tribefire elements, such as entity types, models, accesses, and others as manipulation files
• environment configuration files
• custom code as cartridges

With platform assets, you can package single tribefire elements as well as whole sets of models, experts, their configurations, cartridges with custom code, apps built on tribefire, and even the platform itself.

You can store platform assets in any Maven-compatible repository.

Setup

During setup, an asset is resolved along with its transitive dependencies. Downloading and setting up your tribefire to work with particular assets is done using a command line tool called Jinni.

For more information on setting up platform assets, see Setting Up Environment for Platform Assets.

Asset Natures

Each asset is defined by a specific type, a so called PlatformAssetNature. The nature is used to identify the asset and map specific processing logic to the asset during a setup process. Natures can be grouped into several groups each, depending on their functional behavior.

Computing Assets

Computing assets extend the platform with additional functionality or data in a programmatic way.

• MasterCartridge
• CustomCartridge
• PluginPriming
• ScriptPriming
• Plugin

Data Assets

Data assets incrementally initialize persistence data. This can happen in a standardized way via recorded manipulations or computing assets.

• ManipulationPriming
• ModelPriming
• PluginPriming
• ScriptPriming
• ResourcePriming

Environment Configuration Assets

Environment configuration assets do not bring additional functionality. They are used to define runtime environments, to configure those environments and and to map assets to them.

• RuntimeProperties
• ContainerProjection
• TomcatRuntime
• MarkdownDocumentationConfig

Structural Assets

Structural assets do not bring additional functionality. They are used to enable the possibility to structure dependencies within your project setup.

• AssetAggregator
• ContainerProjection

Experience Assets

This type of nature is used to describe experience assets like frontend applications. Currently, experience assets are treated as web contexts.

• WebContext

AssetAggregator

While bringing no actual functionality with it, the AssetAggregator aggregates a number of other assets of any type. With the help of an AssetAggregator those assets can be easily integrated with just one dependency to the aggregator. That makes especially sense when those assets are commonly reused in different projects and that very combination.

Example: tribefire-standard-aggregator

ContainerProjection

While bringing no actual functionality with it, the ContainerProjection aggregates other assets like an AssetAggregator and further maps (projects) its direct assets dependencies to a specific container which stands for a separately scalable runtime instance of tribefire. This projection makes only sense for certain asset types and is otherwise ignored:

• CustomCartridge
• RuntimeProperties
• WebContext
• Plugin

The following nature properties can be customized:

Example: demo-container

TomcatRuntime

The nature TomcatRuntime defines the asset containing a preconfigured tomcat runtime. Such an asset has a runtime.zip artifact part that contains a templated standard tomcat base structure. While setting up a tomcat environment via Jinni's request setup-local-tomcat-platform, a template mechanism injects further custom configuration like port settings given by the command line options in the respective configuration files (e.g. server.xml or web.xml).

Currently the asset of this nature is injected from the outside or taken by default. In future it should also be possible to find it in the asset dependencies to persist its parameterization.

Example: tomcat-runtime

MarkdownDocumentationConfig

An asset of type MarkdownDocumentationConfig determines the look and feel of Tribefire documentation portal. This asset contains a greeting.md where you can write a welcom message, and an mdoc-doc-metadata.yml file that determines the appearance of the documentaion portal, such as what entry points to show and what to include in the top navigation menus.

MarkdownDocumentation

An asset of type MarkdownDocumentation identifies a documentation asset. Such an asset has a documentation.zip artifact part that contains list of markdown files which contribute to the documentation of the platform. Optionally, a separate file defines the menu structure of the provided documentation files. Documentation assets within a project setup result in an web context and can therefore be called offline and online.

(Please note that the development for MarkdownDocumentation assets is currently ongoing and may therefore change in terms of structural aspects until its released in the first version. For now, the reference mentions above explains the basic structure where content markdown files are placed for now.)

Example: tutorials-doc

RuntimeProperties

RuntimeProperties assets contribute to the setup by bringing environment configuration settings in form of environment variables. Such an asset has a runtime.properties artifact part that stores java properties. When resolving the dependencies, assets with the RuntimeProperties nature are collected and its environment variables are projected into one condensed tribefire.properties.

Example: services-url-runtime

CustomCartridge

An asset of type CustomCartridge is a so called computing assets. Such an asset has a war artifact part which contains a web application that extends the platform with additional functionality by binding denotation types from expert models to expert implementations to make them available for deployment and execution in tribefire.

Example: tribefire-simple-cartridge

MasterCartridge

The nature MasterCartridge defines the core component tribefire-services. There is an own nature for that as core components, especially the master cartridge, often requires special handling in specific environments (e.g. cloud).

Example: tribefire-services

ManipulationPriming

An asset of type ManipulationPriming is a data asset that incrementally adds information in a normalized way to a collaborative smood persistence. Due to the normalization of the manipulation model which is expressed in the GMML grammar it is possible to concatenate, compare and validate manipulation event histories which is very helpful when working concurrently on projects.

Such an asset can have the following optional artifact parts:

• data.man containing general data events
• model.man containing data events that concern model skeletons in the cortex database

Both parts hold manipulations (change events) expressed in the GMML grammar. The files can be maintained manually or can be recorded when running tribefire and doing changes to a collaborative smood persistence by programmatic or user experience ways.

The following nature properties can be customized:

PluginPriming

An asset of type PluginPriming is a data and a computing asset that incrementally adds information in a programmatic way to a collaborative smood persistence. Such an asset contains a plugin.zip artifact part which contains the relevant Java classes that implement the PersistenceInitializer interface. The content of the plugin.zip is identically organized as a plugin.

The following nature properties can be customized:

ResourcePriming

An asset of type ResourcePriming has a resources folder that contains resources (.png, .jpg, .pdf, or any binary representation of data). Jinni processes such assets as follows:

1. checks the files inside this resources folder
2. calculates specification- and meta-data and persist this information in a respective data.man file for the access this asset contributes to
3. copies the resources as they are into the resources folder of the respective access. The resources folder is inside the storage folder.

   For example, in the Demo catrridge, the tribefire-demo-wb-resources is the ResourcePriming asset. It contains a group of images in its resources folder. After being processed by Jinni, the images are copied into the TribefireInstallationDirectory/storage/databases/access.demo.wb/resources/tribefire.extension.demo.tribefire-demo-wb-resources/, and the calculated specifications and metadta are presisted in GMML format in TribefireInstallationDirectory/storage/databases/access.demo.wb/data/tribefire.extension.demo_tribefire-demo-wb-resources\#2.0/data.man.

Assets of type ResourcePriming should be referenced in Wire contracts.

In the Demo catrridge example, you can see that the tribefire-demo-wb-resources is referenced in the DemoWorkbenchInitializerResourceContract interface.

ScriptPriming

An asset of type ScriptPriming is a data and computing asset that incrementally adds information in a scripted programmatic way to a collaborative smood persistence. The groovy scripting language is used to do the programmatic update on the persistence.

Such an asset can have the following optional artifact parts:

• data.groovy containing the script that concerns general data changes
• model.groovy containing the script that concerns model skeletons in the cortex database

Both parts hold script in the groovy language which can access the prepared $context variable which complies to the PersistenceInitializationContext interface

The following nature properties can be customized:

ModelPriming

An asset of type ModelPriming is a data asset that incrementally adds information for a model given by java interfaces to the cortex collaborative smood persistence. Priming models is one central aspect in tribefire as models are the concept which everything else is built around. Such an asset has a jar artifact part containing the model interface classes.

When being processed by jinni the model classes from the jar are analyzed and converted into a GmMetaModel representation which is then converted into a GMML grammar representation. In the end the effective part during initialization of the database is the same like for ManipulationPriming.

Plugin

An asset of type Plugin is a computing asset that can inject basic functionality on which tribefire fundamentally builds (eg. database driver, messaging implementations). Such an asset has a plugin.zip artifact part which contains the following file structure:

• lib
  • abc.jaa
  • xyz.jar
• model
  • a-model.jar
  • b-model.jar

The jars in the lib folder are used to makeup the classloader of the plugin. That classloader will have the tribefire application classloader as its parent. Those jars should not contain classes that are to be shared with tribefire's frameworking otherwise ClassCastExceptions will be the consequence.

The jars in the model folder are used to inject them into tribefire's application classloader to be shared between tribfire and the plugin. Normally you name here models that are needed for the plugins denotations types.

Plugins are only actually effective if at other places denotation instances for the relevant plugin are announced to the system.

WebContext

An asset of type WebContext holds a web application archive which can be from a server-side standpoint plain static download content or server-side functionality such as servlets. The static content could be of course dynamic content when being interpreted in a web browser. That would be especially the case when it represent a javascript application. Such an asset has a war artifact part which represents the web application archive.

Collaborative Smood Persistence

The CollaborativeSmoodAccess is a central component of the tribefire platform. It is an object oriented database that supports the full capability of the QueryModel and is designed as an event-source database that allows to build data in an agile and collaborative way. In such an event-source database the history of the creation and manipulation of data is being used as actual persistence. Based on this technique there are several possibilities to incrementally shape different end-states by building upon the reusable contributions from others.

In tribefire this technique allows to build up central system access such as the reflective cortex access or workbenches.

You can contribute to a collaborative smood persistence with the following data assets:

• ManipulationPriming
• PluginPriming
• ScriptPriming
• ModelPriming

For more information, see SMOOD.

Asset Deprecation

Assets can be deprecated by adding the com.braintribe.model.meta.data.prompt.Deprecated metadata on the asset nature in the asset.man file:

AssetAggregator = com.braintribe.model.asset.natures.AssetAggregator
Deprecated = com.braintribe.model.meta.data.prompt.Deprecated

$deprecated = Deprecated()
$deprecated.message = 'Use tribefire.setup.classic:standard-setup#2.1 instead'

$nature = AssetAggregator()
$nature.metaData + $deprecated

If the metadata is added and the asset is part of a setup, Jinni will print out emphasized DEPRECATED markers in the dependency tree. It will further list deprecation messages separately after the dependency tree, if a message was assigned to the Deprecated metadata. This feature is for information purposes only and has no further implications on the setup.

Platform Setup Access

To support ease of management, we introduced the Platform Setup access, which allows you to manage your assets.

To open the Platform Setup access:

1. In Control Center, click the cogwheel icon in the top-right corner and select Switch to -> Platform Setup.

Asset Dependency Rules

Platform assets use maven POM files to manage asset dependencies. POM files are normally used to manage build dependencies for Java archives (.jar, .war, .ear, etc. ). Each dependency may address either one (manage/build) or both demands. Assets with certain natures use the Maven POM to manage asset as well as build dependencies, for example:

• Plugin
• PluginPriming
• ModelPriming
• CustomCartridge

In the cases of the dependencies above, special care must be taken to address the different dependency purposes by qualifying the dependency declaration with:

• tag processing instructions
• Maven type
• classifier elements

Below is the description of the three possible cases.

Build Only Dependencies

Such dependencies are not taken into account while resolving the platform setup but while resolving build dependencies.

<dependency>
    <groupId>tribefire.cortex</groupId>
    <artifactId>platform-model</artifactId>
    <version>${V.tribefire.cortex}</version>
</dependency>

Asset Only Dependencies

Such dependencies are taken into account while resolving the platform setup but not while resolving build dependencies.

<dependency>
    <groupId>tribefire.cortex</groupId>
    <artifactId>platform-model</artifactId>
    <version>${V.tribefire.cortex}</version>
    <classifier>asset</classifier>
    <type>man</type>
    <?tag asset?>    
</dependency>

Mixed Dependencies

Such dependencies are taken into account while resolving the platform setup and while resolving build dependencies.

<dependency>
    <groupId>tribefire.cortex</groupId>
    <artifactId>platform-model</artifactId>
    <version>${V.tribefire.cortex}</version>
    <?tag asset?>    
</dependency>

Asset Management

In order to provide a convenient and easy way to manage your assets, the Platform Setup Access has been introduced. It provides a set of operations which is described in the following sections.

Trunk Assets

The trunk asset contains all the manipulations you make to a given access (so, for example everything you do in Control Center).

Trunk assets have the ManipulationPriming nature and represent data that was recorded in CollaborativeSmoodAccess instances since your last setup, merge or close operation.

For more information on SMOOD accesses, see Smart Memory Object-oriented Database.

A trunk asset is created when the first manipulation (like creating or changing a model, creating or changing an access, etc. ) is made in the respective access. Trunk assets contain transient data which you should deploy to a repository in order to persist them. Manipulations made in Control Center are stored in the trunk asset of the cortex access.

Once a trunk asset is created, you can close the trunk asset effectively creating a new artifact.

By clicking the arrow next to the Commit button, you open the Advanced Commit dialog box where you can select what you want to do with the asset.

For more information on Control Center options, see the Control Center Integration section of this document.

Any new manipulation creates a new trunk asset if none exists already.

When you close an asset, it is saved and appears in the All Assets section of the Platform Setup access.

Merge

Merging allows you to append the manipulations that were recorded in a trunk asset to another asset with a ManipulationPriming nature or the trunk asset's predecessor. Note there must exist exactly one ManipulationPriming predecessor in the dependency chain. Only trunk assets can be merged.

The trunk asset itself will disappear after a successful merge. The asset to which it was merged will be marked as having unsaved changes which means that a transfer operation (install/deploy) is needed to finally persist the changes.

• Merge Programmatically

  Execute the request com.braintribe.model.platformsetup.api.request.MergeTrunkAsset via one of the endpoints (e.g. webRPC or REST).

• Merge via UI

  You can find all current trunk assets by clicking on the Trunk Assets node in the Platform Setup access. Select the asset to be merged and execute the action Merge.

Close

Closing a trunk asset means that the trunk asset is getting a fully qualified identification by specifying a groupId, a name and version for it. The trunk asset will disappear after a successful close operation and will reoccur on further manipulations being made.

• Close Programmatically

  Execute the request com.braintribe.model.platformsetup.api.request.CloseTrunkAsset via one of the endpoints (e.g. webRPC or REST).

• Close via UI

  You can find all current trunk assets by clicking on the Trunk Assets node in the Platform Setup access. Select the asset to be merged and execute the action Close. A pop-up opens where the you must define the following values:

  • Group id: The group id which also defines the directory path in your repository (e.g. my.group.id)
  • Asset name: A lowercase dashed name (e.g. my-asset-name)
  • Version: The version of the asset (default is 1.0)

Add Dependencies

Adding and qualifying a dependency allows you to build up an ordered aggregation of assets and making it context sensitive. This also allows to incrementally extend the platform.

It's important to note that dependencies are transitively processed before the actual asset is being processed.

The action of adding an asset dependency enables you to further qualify the condition under which the dependency should be processed. You can either use a custom selector and/or a number of predefined and conjuncted selector shortcuts:

• global setup candidate

• design time only

• runtime only

• restricting to stages (e.g. dev, test, prod)

• restricting to tags that support custom filtering

• Add Dependencies Programmatically

  Execute the request com.braintribe.model.platformsetup.api.request.AddAssetDependencies via one of the endpoints (e.g. webRPC or REST).

• Add Dependencies via UI

  In the Platform Setup access, click the All Assets node. Select the asset want to add a dependency to and execute the action Add Dependencies. A pop-up opens where you select the assets to be added as dependencies and further qualify them with the qualification settings.

Install

Installing an asset means to transfer it as an artifact to the configured local maven repository in order to locally persist it and make it available for further setups. The asset will be installed with its current resolvedRevision which won't be increased in this operation.

Only non-trunk assets can be installed.

• Install Programmatically

  Execute the request com.braintribe.model.platformsetup.api.request.TransferAsset via one of the endpoints (e.g. webRPC or REST).

• Install via UI

  In the Platform Setup access, click the All Assets node. Select the asset to be installed and execute the action Install.

Deploy

Deploying an asset means to transfer it as an artifact to a Maven-compatible repository to persist it and make it available for further setups. The asset will be deployed with its increased resolvedRevision.

You can deploy the assets of the following natures:

• ManipulationPriming
• AssetAggregator
• ContainerProjection
• RuntimeProperties

Only non-trunk assets can be deployed.

• Deploy Programmatically

  Execute the request com.braintribe.model.platformsetup.api.request.TransferAsset via one of the endpoints (e.g. webRPC or REST).

• Deploy via UI

  In the Platform Setup access, click the All Assets node. Select the asset to be installed and execute the action Deploy.

Combined Operations

You can use several combined operations to increase the convenience of operations belonging together.

Merge and Transfer

After an asset was successfully merged, it can be transfered to the repository. This action is a combination of the Merge and Install actions.

• Merge and Transfer Programatically

  Execute the [com.braintribe.model.platformsetup.api.request.MergeTrunkAsset] request via one of the endpoints (e.g. webRPC or REST).

• Merge and Transfer via User Interface

  Open the Control Center:

  In the right upper corner of the tribefire-control-center click on the cogwheel and choose the item Switch to > Platform Setup. This will open the access where you can manage assets.

  You can find all current trunk assets by clicking on Trunk Assets in the workbench. Select the asset to be merged and execute action Merge and Transfer.

  Either check the merge to predecessor box or select the target asset to where the manipulations should be merged into.

  A pop-up opens where the transfer operation can be specified. Supported transfer operations: * Deploy * Install

Close and Transfer

After an asset was successfully closed, it can be directly installed to the repository. This action is a combination of the Close and Install actions.

• Close and Transfer via UI

  In the Platform Setup access, click the Trunk Assets node. Select the asset to be merged and execute action Close and Transfer. A pop-up opens where the transfer operation can be specified. The following transfer operations are supported:

  • Deploy
  • Install

Platform Asset Services

There exist services providing further information, convenience tooling and features around Platform Assets.

GetAssets

Request: GetAssets (com.braintribe.model.platformsetup.api.request)

Description: Returns a AssetCollection based on the provided filter criteria of this request.

Filter Criteria:

Asset Nature Values

Following natures are supported:

• AssetAggregator
• ContainerProjection
• MarkdownDocumentation
• MarkdownDocumentationConfig
• ModelPriming
• PlatformLibrary
• RuntimeProperties
• LicensePriming
• TribefireModule
• PrimingModule
• ManipulationPriming
• ScriptPriming
• ResourcePriming
• TribefireWebPlatform

Sample Requests

Get assets of natures TribefireModule and ModelPriming

http://localhost:8080/tribefire-services/api/v1/setup/com.braintribe.model.platformsetup.api.request.GetAssets?nature=TribefireModule&nature=ModelPriming&sessionId=...

Get assets having group id tribefire.cortex.assets

http://localhost:8080/tribefire-services/api/v1/setup/com.braintribe.model.platformsetup.api.request.GetAssets?groupId=tribefire.cortex.assets&sessionId=...

Get assets having term explor in its name

http://localhost:8080/tribefire-services/api/v1/setup/com.braintribe.model.platformsetup.api.request.GetAssets?name=*explor*&sessionId=...