App Templates Overview
Only Marketplace power users can create Templated Apps.
An App Template provides a way for users to create a reusable piece of code that other users use to create a App with some provided variables to help the Template run.
As a Template author/editor, you are in charge of writing the code that runs for the users of your Template. Each Template works just like a App (for the supported types). For example, just like you create a Python App with a file containing your code, some optional environment variables, and the command to execute your code, you create a Template (selecting the Python type) and provide all of those same configuration values.
Additionally, you provide input variables that your Template will use to do its job. Variable specifications are defined for Templates, and the users of the Template provide the values in a App.
Template Types
Currently, you can use the following languages to create App Templates:
Python
Node
Bash
A Templated App is an App that allows you to execute code that has been provided for you in a Template. A Template is a special construct in Alli Marketplace that authorized users can create to do things for you.
Let's say your friendly neighborhood Data Innovation coworker knows how to write Python and you don't. They can write some Python to do something to make your job easier. Then, they create a Template that you can use to run the code on Alli Marketplace. The Template creator provided you with options for input to make running the code simple and easy.
Creating a Templated App
To create a Templated App, navigate to the “Manage” page within any client
Select to “Add Template”
Next, select the code language you’re using for your app, in this example we’re adding a Python App Template
You should see the following page which allows you to set a name, description, which python packages are required to run your code, and more
Be cognizant of future use and changes. Your users will thank you.
For additional details on what each section means, click here: App Process & Development Deep Dive
Template Metadata
The first section for defining a Template contains inputs for the Name, Description, and Status of the Template.
Name is the name of the Template. Try to be descriptive and not use jargon unless it is a common abbreviation or the like. This is going to be the main thing users will see when select Templates for a App.
The description is a short description of the Template. You should always fill out this field to provide more context and help for users.
Status determines whether or not a Template is enabled. Only Enabled Templates will be available for creating Apps. More importantly, if a Template is disabled, any App that is derived from that Template will be de-activated until you are able to update the App and re-activate it.
Template "App" Configuration
The second section for defining a Template is going to be the same configuration required for a App of the corresponding type. For instance, if you select a Bash template, then this section of configuration will exactly match how you configure a Bash App.
See the articles regarding those App types for more information about this section.
Template Variables
The third section for defining a Template is the Template's Variables. For a Template editor, you specify variables that your code "relies" on.
These are not variables that are in your code. Instead, they are variables that are going to be present in the system as environment variables that your Template can and should use while running.
The user who creates a App from your Template are going to provide the actual values for those variables you define in the Template. Those values then become available at execution time.
As you can see, each variable has a name, description, type, default value or options, and a required option.
The variable's name is a required string of letters, digits, and the underscore character. No white space is allowed. This name is going to be used by the Template editor to obtain the variable's value during execution. This is covered later.
Variable names must be unique (case insensitive) within a Template.
The variable's description is an optional value that will display alongside the variable value input on the App edit page. This should be provided so that users of your Template know what values should be input and what your Template is going to do with that value.
The variable's type is a high-level choice and validation for the variable's value. For instance, if your code allows only a specific set of operators, those options should be in a select type. If your Template accepts as a parameter a bid multiplier, then set the variable's type to Floating Point makes sense to disallow the user from providing "abcd" as input.
The Default Value / Options field provides a mechanism for defining the default value a variable should have if the user does not specify one in an App.
The Boolean type. This type allows for a true or false value. These are the only two options and all Boolean variables are required to have one of these values. When the value is provided to your executing Template, the value will be either the "TRUE" or "FALSE" string literal.
The Date type. This type allows for providing a date input. Alli Marketplace provides a special input to provide valid dates. When the value is provided to your executing Template, the value is a string literal in the format "MM/DD/YYYY". If there is no date value, then the empty string "" is provided.
The Select type. This type allows you to define a set of valid values for your Template. When the user is editing an App, only those values that you define here will be available to the user. When the value is provided to your executing Template, the string literal of the value the user has selected will be provided.
All other types. These types allow for an arbitrary input of literals according the their types. The provided value to your executing Template will be a string representation of the input value.
Obtaining Template Variable Values at Runtime
When a Template is executing, it is done via the same Execution mechanism that Apps execute already. To be clear, a Template does not execute by itself or independent of an App. Apps must be created from Template, and that App gets executed. But, the code you provide in Template is really what is running.
All of the variables that are defined in your Template are provided at runtime via environment variables.
The format for the environment variable's name is Alli Marketplace_TMPLVAR_<VARIABLE_NAME>
E.g. if a variable's name is operator_a, then its environment variable name will be Alli Marketplace_TMPLVAR_OPERATOR_A. Note that the variable name is upper case. This occurs for all variable names.
You can obtain the value for the variable like you would any other environment variable, but, this is not encouraged. Instead, you should de-reference the variable value in the other Template fields.
For instance, you can obtain the variable's value via the command arguments by using the following command:
some_script,--op-a,${Alli Marketplace_TMPLVAR_OPERATOR_A}
To dereference the variable's value, wrap the variable's name as such: ${<formatted_name>}
Final Thoughts
It is essential to plan ahead and think about how your Template is going to be used. This will help you decide on input values and variable names that make sense to the user and to your Template.
Because the end user of your Template is going to be creating an App from the Template, and setting variable values, providing thought-out values here will make for a better experience for the user.
Remember that each time Template variables are updated, all Apps that depend on the Template are also inherently updated. If, for instance, you change a Template variable name from account to account_id, then all dependent Apps are not going to have an account_id variable set in their config. This means executions for that App will likely start failing.
Once your app is set up, click Save. If your app is published, your app will now be available for Marketplace users to use!