Developing Components

This doc will guide you on how to create and build new Components for IA

1. Component Repository Setup

The first step in building your component is to build your component repository on github.

Start from the component template repository here and follow all the instructions in the README file to get started with your component repo.

Your repository name should be of the format <component_prefix>-<component_id>, where component_prefix may only include alphanumeric characters and underscores. It must begin with a letter and cannot have '_' as the last character. Similarly, your component_id should only include letters and underscore. For example, if you are building a component for Predictive Maintenance, your repository name can be pm-PredictiveMaintenance.

We are required to name the GitHub repository in this specific format because it enables us to integrate multiple components into the IA system. Each component repository includes predefined action services, as detailed in step 2. Without a unique prefix for these action services, the component cannot be added, as the IA system will attempt to register services with identical names, resulting in conflicts.

2. Building Component Action Handlers

Component action handlers are JS services that contain all the logic for initializing and executing component artifacts. You will need to complete the handlers for your component in the component repo you made in the first step.

The component action handlers are as follows:

Component Action Service	Caller	Description
`<component_prefix>_setup.js`	iasystemcreator@clearblade.com	This service is called when a component is created through the UI, and only called if no other instances of that component exist yet in the system. It is called as a developer and creates new ClearBlade resources if required. Most of the resources will be a part of the IPM itself, but you will need to use this in the event you want to use secrets to create external dbs, bucket sets, etc., or to setup any other external entities.
`<component_prefix>_install.js`	collectionHandler@clearblade.com	This service is called every time a component is created through the UI. It can interacts with IPM/IA resources to create entities such as collection rows, publish messages to IA services, add data to IA collections, etc.
`<component_prefix>_update.js`	collectionHandler@clearblade.com	This service is called in the event a user updates an existing instance of a component through the UI. It interacts with IPM/IA resources to update any entities such as collection rows, etc.
`<component_prefix>_delete.js`	collectionHandler@clearblade.com	This service is called everytime an existing instance of a component is deleted through the UI. It should delete any entities created by the corresponding `_install` call.
`<component_prefix>_teardown.js`	iasystemcreator@clearblade.com	This service is called if a component is deleted through the UI, and if after deletion no other instances of that component would be present in the system. It is called as a developer and should clean up anything that was created by the corresponding `_setup` call.

Each of these action services receives data from the IA table item services. The data provided to these services is as follows:

CODE

{
   entity_id: string;                          // Id of entity on which this component is enabled
   component_id: string;                       // Component ID 
   mfe_settings: Record<string, unknown>       // Data set from the MFE UI
}

For further reference, you can view the component handler services for ClearBlade’s ai-components here

3. Building Component MFE

The Component MFE is the UI that gets rendered when you configure your component from Intelligent Assets. You will need to complete all MFE elements for your component in the component repo you created.

Follow this README to learn about building UI for components

And for further reference, you can view the MFE for ClearBlade’s ai-components here

4. Adding Components to Master list

Lastly, a ClearBlade developer must go the components collection in the asset-monitor-management system and add a row with the component details you provide to them:

id - Should match the component id you used in your component repo
name - Should match the component name you used in your component repo
type - ai_internal_v1 for internal and external for external components.
owner - Owner of the component
description - Description of the component
ui_injection_id - You can skip this.
min_ia_version - This is the IA version on which this MFE was tested.
repo_url - The url to the components repository you created from the template
mfe_url - The url to your MFE (e.g. https://cdn.jsdelivr.net/gh/ParentRepo/tst-TestRepo@main/dist/tst_TestRepo.js)

Admins will now be able to enable your components from the sidecar and end users can start configuring them in IA.