Defining an Activity

This page describes the details of defining an Activity.

Activity Definition

The definition of an Activity involves defining the inputs, outputs, description and other parameters, and the files that are to be considered part of the activity package. The sections below describe each of these aspects in detail.

Inputs

The logic of an activity is setup with sample inputs on an Excel workbook. When the activity is actually run, the sample inputs are replaced with actual inputs. For this to work, the cells / ranges on the workbook whose values need to be replaced with actual inputs must be specified. Also, the user interface for the activity is created based on the input definitions.

Each input must have a unique name that clearly indicates what the input represents. As far as possible, the name of an input should not be changed once an activity is published. Changing the name will break the "Run Again" functionality and checklist input mappings.

The Type of an input controls how the input maps to a cell / range in the workbook. It must be specified as a Single Cell, a Table or Multiple Files.

Single Cell

The input maps to a single cell on the workbook. This cell must be selected in the Range box for the input. When the activity is run, the actual input value will be placed in this cell. {.img-responsive} Once the cell is selected, the type of value within the cell is inferred and shown under Value Type. There is also a Blank check box next to the Value Type field. Value Type can be specified as one of the following

Text: A text value is expected for the input and a text box will be shown in the user interface where the user can enter text. If Blank is checked, the user will be allowed to run the activity without entering any value for this input. The cell will get an empty string as the value in this case. If Blank is not checked, user must enter a value.
Number: A numeric value is expected for the input. A text box will be shown in the user interface. If Blank is checked, the user will be allowed to run the activity without entering any value for this input. The cell will get a #N/A value in this case. If Blank is not checked, some numeric value must be provided.
Date: A date is expected for the input. A popup calendar will be shown in the user interface for date selection. The cell will get a numeric value that represents the selected date as per Excel's representation. If Blank is checked, the user will be allowed to run the activity without selecting a date. The cell will get a #N/A value in this case. If Blank is not checked, a date must be selected.
Boolean: A boolean value (TRUE / FALSE) is expected for the input. A checkbox will be shown in the user interface. The checkbox can take one of three states - checked, unchecked, or unspecified. If Blank is checked, the user will be allowed to run the activity without either checking or unchecking the checkbox. The cell will get a #N/A value in this case. If Blank is not checked, the checkbox must be checked or unchecked.
FilePath: A file is expected to be uploaded to run the activity. A file upload button will be shown in the user interface. The uploaded file will be placed in a temporary folder and the cell will get this temporary path as the value. If Blank is checked, the user will be allowed to run the activity without uploading a file. The cell will get a #N/A value in this case. If Blank is not checked, user must upload a file.
Condition: A SQL like expression that evaluates to true or false is expected for the input. An editor that allows the user to create the expression graphically will be shown in the user interface. To configure this interface, the Picker field must be specified as the name of a Picker Definition in the same module as this activity. The cell will get the expression chosen as a text value.
StaticFolder: Deprecated. A path to a shared folder accessible from the server where the activity will run is expected for the input. Since this path cannot be provided by the end user, this was supposed to be used with the Preset Values feature. This input is not shown in the user interface and its value must come from a Preset Value. The StaticPath.SK function provides a simpler alternative to this feature and should be used instead of this.
FileId: The id for a file in a database table intended to store files is expected for the input. Since the user is unlikely to be able to provide this id, this is only likely to be useful in conjunction with a linked activity that produces such an id as an output. The cell will get the id as a text value and it can be used with the LoadFile.SK function.
ActivityRunId: The run id of an activity. This is not currently supported.

Right above the Name field, there is a drop down which describes the source of the value for the input. This can be specified as one of the following.

OldStyle: Inputs defined before version 2.12 without Allow Default Value checked have this style. An OldStyle input of Value Type text or boolean may be left blank and the cell will receive an empty string or FALSE as the value respectively. Inputs of any other Value Type must be specified by the user. For newly created activities, this option is no longer available. Old activities will continue to work without any change of behaviour.
Required: This is the default style since version 2.12. It indicates that the value is expected to be specified by the user. Unless the Blank field is checked, the user must provide a value.
Optional: An unchecked checkbox will be shown in the user interface with a message stating that this input is optional and showing the default value that will be used if the user does not specify a value explictly. The user can provide a value explictly by checking the checkbox. The value or formula in the cell determines the default value. Inputs defined before version 2.12 with Allow Default Value checked have this style. This style is also available for new activities.
Suggested: The input has a suggested value that can be determined by evaluating the value or formula in the cell. If the cell has a formula, it can depend on other inputs prior to this input. It must not depend on subsequent inputs. This rule is not validated, but will result in incorrect behaviour if not adhered to. The user interface will display the suggested value and the user can override this value if desired.
Display: The input has a calculated value that is determined by evaluating the value or formula in the cell. The user cannot override the value. It is shown as read-only. If the cell has a formula, it can depend on other inputs prior to this input. It must not depend on subsequent inputs. This rule is not validated, but will result in incorrect behaviour if not adhered to. This is useful for displaying the result of a simple calculation to the user while running the activity.
Hidden: This is similar to Display but the input is not displayed at all. It can be useful when used with custom picker queries or to serve as the source for a condition picker.

Table

The range containing the table must be selected in the Range field. If the range has headers, the headers should also be selected. There are options for specifying how many rows from the top of the selected range and how many columns at the left of the selected range are headers. However only 0 or 1 are currently supported. If a range has row headers in its first column, the size of the range is fixed and the user cannot create additional rows at the time of running the activity. If there are no row headers, the option to allow the user to choose the number of rows in the input is available through the "User can add or remove rows" checkbox (checked by default).

The right side of the table input specification contains details about each column in the table. The Value Type, Blank, Picker and Sql Name fields work in the same way as described for Single Cell inputs. The Input field also works in the same way except that Optional is not available. The formulas for Suggested, Display or Hidden columns can depend on cells in previous columns or on previous inputs but must not depend on subsequent columns or inputs. Also, each column should have a formula that is exactly one column wide. Multi column FillDown or other array formulas that span more than one column are not supported.

If the table has only one column and a picker is specified, there is an option to display the UI as a list of checkboxes for each option generated by the picker. This should only be used when the number of options the picker might generate can reasonably fit on a single web page.

Multiple Files

The range containing one or more file paths should be selected in the Range field. The range must have exactly one column and the selection should not include any header above the file paths. The user will get the option of uploading multiple files for such an input. The "User can add or remove rows" checkbox controls whether the number of files to be uploaded can be variable. Each uploaded file will be placed in a temporary folder and the paths to these temporary file will be placed in the selected range.

Pickers

For single cell inputs and for the columns of a table input, there is a picker field which can be used to provide a list of suggestions in the user interface. Currently this functionality is only available for Text and Condition fields but it will be extended to Date and Number fields also in future.

For Text inputs, the picker can be provided in the following ways

List: A static (hard-coded) list of suggestions can be provided. The user will be required to pick a value from one of these suggestions and any other value will not be accepted. To accept other values, the first value in the list can be specified as *
Database: The list of suggestions can be sourced from a database. A table and a column from that table can be provided along with an optional categorization column. Unique values from the specified column are shown as suggestions. If a categorization column is provided and the picker is used in conjunction with the "Checkbox List" feature, the checkboxes will be shown in two levels with the first level as unique categories and the second level as the actual suggestions from the specified column. In future, the categorization will be displayed in the normal drop-down list of suggestions as well as with the checkbox list. It is also possible to provide a custom SQL query to generate the list of suggestions. Further, the custom SQL query can depend on the values of other inputs of the activity. To use this functionality, SQL parameters can be used in the SQL query. The values of these parameters will come from other inputs whose Sql Name is set to the parameter name. It is recommended that the query should only use inputs that come before the current input, so that the user can fill in the inputs in a sequence.
Workbook: The list of suggestions can be generated by some logic in the workbook itself. This logic could depend on other inputs and could make database calls, read files, make Http API requests etc. The end result of the logic should be a range containing the suggestions and this range can be selected for the workbook picker.

For Condition inputs, the picker can be provided as the name of a picker created in the same Module as the current activity. Currently, there is no UI to create such a picker and it must be created manually as json in the sk.PickerDefinitions table. This type of picker specifies the list of columns available to define a condition and a list of suggestions for each column.