How to add a Feature

The Feature Studio uses a simple text-based wizard called Code Generator (aka “codegen”) that dynamically builds framework code and configuration files for new software features based on responses provided by the developer. A GitHub GitFlow is also provided as-a-service from Pratexo that automatically publishes new features to the Pratexo Design Studio when changes are pushed to Pratexo's GitHub repositories. Following the instructions below, a new feature can be imported into the Pratexo Studio very quickly.

NOTE:  The Feature Studio is currently in BETA status and is intended to be used by Pratexo Professional Services or trained Systems Integrators. Please contact your Pratexo account manager or technical contact for assistance before attempting to build features.

Prerequisites

• Your Pratexo technical representative should inform you which GitHub repository you should use

• A GitHub account is required and should be provided to Pratexo for enrollment into the repository

• Familiarity with GitHub concepts and commands such as cloning and pushing changes

• Fully tested application, either containerized or in native Python scripts

• Knowledge of which software features can connect to (ingress) or be connected from (egress) the imported application

Pre-installations

Install the following tools and repositories on your local computer:

1. Install git to your local computer

   • https://git-scm.com/book/en/v2/Getting-Started-Installing-Git 

2. Install Docker Desktop

   • https://docs.docker.com/engine/install/ 

3. Ensure that Docker Desktop is running on your local machine

Procedure

NOTE:  In our examples, we will use a GitHub repository called template-feature-library, the exact repository you should use will be provided by your Pratexo representative.

1. Use a git client or terminal window and create a project directory for the template-feature-library.

   • i.e., mkdir featurestudio

2. Change directory into featurestudio

   • cd featurestudio

3. Clone the template-feature-library repository from GitHub

   • git clone git@github.com:pratexo/template-feature-library.git

   • Note:  This will clone a repository that has no features, but contains the tools necessary to build a feature. 

4. In the git client or terminal on your local machine navigate to the template-feature-library directory.

5. Modify the config file with your organization name (i.e., org.pratexo)

   • The value you use for the  organization name is critical as you cannot create a fearure without it and it must remain the same otherwise you will not be able to remove features if it has changed. 

6. Run the code generator utility with the following command: 

   • ./run-codegen.sh

   • A text-base wizard will appear in the terminal - if it the first time to run this command, it may take a few seconds to download dependencies.

Option 1: Generate a Containerized Python-based Analytics Feature

This option will create a framework for a developer to create a feature in the Pratexo Studio from scripted python-based applications. Python files in the ‘source’ directories will need to be replaced with the actual application files. 

The default behavior of this feature with no modifications is to read all topics from an MQTT bus and write them back under new topic names to demonstrate feature functionality.

7. Respond to the following prompts

   • Choose option #1: Pratexo: Containerized Python-based Analytics

   • Provide a name for your feature without any spaces, capitalization, leading numbers or underscores

   • Enter a version number (default is ‘1.0.0’)

   • Select a category that the feature should appear under

     1. Imported features will also be listed under a new category with the name of the organization provided earlier in the config file

   • (optional) Provide a general description of the feature - this will be listed in the feature attributes panel in the Studio

   • (optional) Provide a short description of the feature

   • (optional) Provide a longer description of the feature

   • (optional) Enter a URL referencing more detailed information about the feature

8. A new folder in the template-feature-library directory is created with the name of <your_feature_name>.

9. In the folder ./library/source/src/, you will find the Python files that need to be replaced with the actual files of the analytics application  

Option 2: Generate a Docker-kind Feature Manifest

10. Respond to the following prompts

    • Choose option #3: Pratexo: Generate a docker-kind feature manifest

    • Provide a name of your feature without spaces, capitalization, leading numbers or underscores

      1. “_docker” will be appended to this name

    • Provide a version number if anything other than 1.0.0 - hit enter

    • Enter the number of the category that this feature is most likely to fit under

    • Enter the container image location and its name

      1. example.  gcr.io/<path>/<name>

    • Enter the image version tag

      1. example: latest or 3.2.1

    • Provide a port number for the program that it should listen on

      1. example: 8181

      2. Note: If ingresses are required otherwise this step is optional

11. A new folder in the template-feature-library directory is created with the name of <your_feature_name>_docker.

Final Steps

12. Refer to the article “Feature Routing - How does it work?” to set rules for connecting to or allowing connections from the newly created feature

13. Refer to the article “Changing Attributes of Features” to modify the choices exposed to users in the Pratexo Design Studio

Upload New Features to the Pratexo Studio

NOTE: The following steps require access to Pratexo’s GitHub repository. Please contact your Pratexo representative to assist you with this process.

14. Add and commit files to the Git repository

    • git add –all

    • git commit -m “<short message describing the addition>”

    • git push

This will synchronize the changes in the local repository with the repository in GitHub and automatically start the build and seeding process to merge it as a feature in the Pratexo Design Studio

• Wait about 5-10 minutes for this process to complete

15. The newly imported feature is now available to be used in the Design Studio under the Features section in the left navigation.

Refreshing your Local Repository

If you haven't used your local repository in a while, it is likely that other changes have been pushed to the master version in GitHub that you don't have. Follow these steps to refresh your local repository with the master.

1. Be sure you are working in the template-feature-library repository, as an example
2. git fetch
3. git reset --hard origin/master

Your local repository should now match the master repository in GitHub.

Deleting Features

1. Be sure you are working in the template-feature-library repository, as an example
2. Make sure your local version of the feature directory matches master version in GitHub
   • See the "Refreshing your Local Repository" section earlier
3. If necessary, modify the config file so that the value for ORGANIZATION= matches the value for organization: in the feature's manifest.yaml file 
4. Delete the feature folder structure
   • i.e., rm -rf ./your_feature_name>/
5. Push the changes to GitHub
   • git add –all
   • git commit -m “<short message describing the addition>”
   • git push