Altergo Function Template

Welcome to the altergo-function-template repository! This template provides the foundational setup for creating custom functions compatible with the Altergo platform. By forking or copying this repository, you can quickly get started building and deploying your own Altergo functions.

Getting Started

To begin using this template, follow the steps below to set up your repository:

1. Fork or Copy the Repository

First, fork or copy this repository to your local machine. This allows you to customize and build your functions without affecting the original template.

2. File Structure

For the entire project, make sure to have:

• requirements.txt: This file should list all Python dependencies required for your function to run.

For each function within the project, make sure to have:

• {entrypoint}.py: This is the main function entrypoint file where you will write your custom function code. This is this file that will be run by Altergo workers. There are no restriction on the script name. You will have to manually select it when creating a function on the Altergo platform.
• model-configuration.json (optional): The configuration file if you intend to deploy this function as a model. Make sure to put the file at the entrypoint file location. Make sure to respect the file name.
• model-validation.json (optional): The validation file if you intend to deploy this function as a model. This file will be used by Altergo to verify that your blueprints are compatible before deploying and enabling the model. Make sure to put the file at the entrypoint file location. Make sure to respect the file name.

3. Setting Up the Environment for Local Testing

To test your function locally, you will need to create a {dev-parameters}.json file and start the script with the path of this file as argument.

{
    "altergoUserApiKey" : "YOUR_API_KEY", // mandatory
    "altergoFactoryApi" : "https://YOUR_COMPANY.altergo.io", // mandatory
    "altergoIotApi" : "https://iot.YOUR_COMPANY.altergo.io", // mandatory
    
    "assetId": "ASSET_ID", // usually, we deploy the function and execute it on a specific asset
    
    "customParameter1: "customParameter1Value"
}

Also, if you are using VSCode, you can specify the .vscode/launch.json as follow:

{
    // Use IntelliSense to learn about possible attributes.
    // Hover to view descriptions of existing attributes.
    // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Altergo Function : entrypoint.py",
            "type": "python",
            "request": "launch",
            "program": "${workspaceFolder}/entrypoint.py",
            "console": "internalConsole",
            "args": [
                "dev-parameters.json" // This is the file used to execute the function locally
            ]
        }
    ]
}

4. Developing Your Function

Edit the {entrypoint}.py file to implement your custom function. Here’s a basic template to get you started:

from altergo_sdk.api.altergo_api import Client
from altergo_sdk.tools.utils import extract_altergo_parameters

# Extract the Altergo parameters from the command-line arguments.
altergoArguments = extract_altergo_parameters()

# Extract the API key, factory API URL, and IoT API URL and other parameters from the parsed arguments .
# These are necessary to authenticate and establish a connection with the Altergo platform.
apiKey = altergoArguments['altergoUserApiKey']
factoryApiUrl = altergoArguments['altergoFactoryApi']
iotApiUrl = altergoArguments['altergoIotApi']
# Extract the Altergo task ID from the parsed arguments that you can use to interact with the Altergo platform. 
# If you are locally testing the function, you can need to set the id as "dev" in the dev-parameters.json file.
altergoTaskId = altergoArguments['altergoProgramTaskId']

# Extract the configuration values if this function is supposed to be used as deployable Altergo Model.
modelConfiguration = altergoArguments['configurationValues']

# Uncomment and replace 'YOUR_CUSTOM_FUNCTION_PARAMETER' with your specific custom function parameter
# if you need to pass additional data to your function.
# Example:
# yourCustomFunctionParameter = altergoArguments['YOUR_CUSTOM_FUNCTION_PARAMETER']

# Create a dictionary to store the client configuration details.
# This dictionary is used to initialize the Altergo API client.
_client = {
    "apiKey": apiKey,  # Your API key for authentication.
    "factory_api": factoryApiUrl,  # The base URL for the factory API. Usually https://YOUR_COMPANY.altergo.io
    "iot_api": iotApiUrl  # The base URL for the IoT API. Usually https://iot.YOUR_COMPANY.altergo.io
}

# Initialize the Altergo API client with the provided configuration.
# This client will be used to interact with the Altergo platform's services.
altergoClient = Client(**_client)


# YOUR MODEL LOGIC GOES HERE
assets = altergoClient.getAssets()


### Example of an output that will be displayed on the asset model page
### Please follow the format : [{name, icon, description, url}...]

task = altergoClient.getTaskById(altergoTaskId)
task.output = [{"name" : "Digital Twins", "icon": "fa-chart-line", "description": "A new digital twin has been created", "url": factoryApiUrl + "/assets"}]
altergoClient.updateTask(task)

5. Managing Dependencies

Ensure all dependencies required for your function are listed in the requirements.txt file. This allows others to quickly install necessary packages using:

pip install -r requirements.txt

6. Deploying Your Function

Once your function is ready and tested locally, follow these steps to deploy it to the Altergo platform:

1. Push the Repository Online: Ensure that your repository is pushed to an online platform, such as GitHub, GitLab, or any other Git provider. This allows the Altergo platform to access your code.

2. Create a Function on the Altergo Platform: Log in to the Altergo platform and create a new function.

3. Configure the Function: During the function creation process, configure it to target your repository. For personal repositories, authentication is required to connect the platform with your repository.

   • Authentication: Depending on the provider, you will need to authenticate Altergo to access your private repositories. Currently, GitHub is supported, with dedicated connection pipelines for authentication.

4. Deploy the Function: Once the function is configured and the repository is connected, your function is ready to be deployed. The Altergo platform will handle the execution of your function based on the code in your repository.

And that's it! Your custom function should now be live and ready to use on the Altergo platform.

Security Best Practices

• Do not commit sensitive information: Ensure that API keys and other credentials are not included in any of your commits.
• Use environment variables: Consider using environment variables to manage sensitive information securely in your development and production environments.

Contributing

If you encounter any issues or have suggestions for improving this template, feel free to open an issue or submit a pull request. Contributions are always welcome!

License

This project is licensed under the MIT License. See the LICENSE file for more details.