Skip to main content

Blueprint Variables#

Definition#

Blueprint Variables allow your code to accept user input through the Shipyard UI that gets stored and made available to your code as an environment variable.

A Blueprint can contain as many variables as you want. Blueprint variables can also be re-ordered to make it easier for users to understand.

A user who creates a Vessel from your Blueprint will provide their own values on the Input tab for Blueprint Variables that you define. Those user entered values then become available at runtime.

Components#

Display Name#

A required string of letters and digits. This name will be shown to a user on the input tab.

Reference Name#

A required string of letters and digits with no whitespace or special characters other than _. This name will be translated into an environment variable with the same name, used to reference the input data in your script. Reference names must be unique (case sensitive) within a Blueprint.

Variable Type#

A required high-level choice that helps provide validation for the user input. The following are the currently available variable types:

  • Alphanumeric - Lets the user provide a string of text.
  • Integer - Lets the user provide a number.
  • Floating Point - Lets the user provide a decimal number.
  • Boolean - Lets the user select either a TRUE or FALSE value in the form of a checkbox.
  • Date - Lets the user provide a date, using a date selector, in the YYYY-MM-DD format.
  • Select - Lets a Blueprint creator define a restricted set of valid values as Select Options. These values contain both a Display Name, shown to the user, and an Internal Value, passed to the code. Requires at least one option.
  • Password - Allows the user to provide a string that gets hidden by default. Upon saving, this data will not be sent to the UI and will show as (hidden). This behavior is similar to how environment variables are handled.
caution

Regardless of which variable type is selected, the user input will always passed back to your code as a string. Your code will need to appropriately translate the input into the required data type.

Default Value#

A field that provides a mechanism for defining the default value that should be passed to the code if the user does not specify one when creating the Vessel. This field changes based on the variable type selected and is required for the Select variable type.

Required?#

Indicates whether or not the user will have to provide this value in order to build a Vessel successfully. Presents the user with an error message if the field is not filled out.

Placeholder#

An option field to show greyed out text in the input field before the user provides input. Helpful for providing example values.

Tooltip#

Text will display in a tooltip next to the variable name. This should be provided for ease of use, letting users of your Blueprint know what value should be input and what your Blueprint is going to do with that value.

Accessing Variable Values#

All of the user input provided when setting up a Vessel will be provided to your code at runtime. There are two ways to access the user input provided to a Blueprint Variable:

Pass Variable Values to Code#

You can obtain the variable's value via either the command arguments or as an environment variable by referencing the variable using ${variable_name}. The variable name will exactly match the Blueprint Variable's Reference Name.

For example, if a variable's reference name is Operator_A, then you would reference it by typing${Operator_A}.

If you reference a ${variable_name} that does not exist, the value will be returned as None.

We recommend this option, as it makes it extremely clear which variables are being passed to the script and how they are being used.

Set Variables Using Environment Variables#

In your code, you can obtain the value for the variable just like you would any other environment variable. The environment variable name will exactly match the Blueprint Variable's Reference Name. For example, if a variable's reference name is Operator_A, then its environment variable name will be Operator_A.

View our how-to guide for accessing Environment Variables.

caution

A Blueprint's environment variables and Blueprint variables are both set as environment variables that can be accessed at runtime. It's important to make sure that the naming between these two sections doesn't overlap.

danger

Make sure not to set any variables to important environment variable names like PATH or HOME unless you really know what you're doing.

Screenshots#

Viewing all variables

Editing a variable

No variables

Additional Notes#

  1. A Blueprint cannot have two variables with the same name.
  2. A Blueprint variable cannot be conditionally shown or hidden based on a user's selection.
  3. There is no built-in system to ensure that ${variable_name} exactly matches a reference name. Make sure you don't have typos!

Learn More#