Enumerations in applications

This guide explains the enum feature and how to use it in the pronghorn.json file for Itential Platform applications.

Terminology and concepts

Enum is short for “enumerations,” meaning “specifically listed.” An enum specifies a list of constant values assigned to a type. A constant is an identifier (name) for a value that cannot change during the execution of a script or command.

Essentially, an enum is a special “class” representing a group of constants. Once an enum is defined in configuration, you can constrain input to the set of values in that enumeration.

Define workflow tasks using enums

Enums represent a fixed number of possible values. Use an enum when there is a definite number of fixed values for a variable — similar to Boolean values of true or false.

To create an enum input for a task:

Use the enum keyword as the type.
Use enum for values that are not going to change, such as months, days of the week, colors, or shirt sizes.

Create an enumerals array containing all valid values. In the example below, the enumerals array contains the days of the week.

Example

The WhatDay task:

1 "methods": [
2   {
3     "name": "WhatDay",
4     "description": "Day of the week picker.",
5     "summary": "Day of the week picker.",
6     "deprecated": false,
7     "roles": [
8       "admin"
9     ],
10     "input": [
11       {
12         "name": "theDay",
13         "type": "enum",
14         "enumerals": ["sunday", "monday", "tuesday", "wednesday", "thursday", "friday", "saturday"],
15         "description": "Pick a day of the week."
16       }
17     ],
18     "output": {
19       "name": "hoursDaylight",
20       "description": "The numerical value of how many hours of daylight the selected day has.",
21       "type": "string"
22     },
23     "task": true
24   }
25 ]

You can create enumeration values that appear as a selection when filling a user input field. You can also lock enum values to ensure that only the values you have defined are accepted.

Use enumerations in Workflow Builder

Once a task is created:

Open Workflow Builder

Navigate to Workflow Builder.

Add the task to the canvas

Add the task to the canvas — for example, the WhatDay task.

Configure the task

Double-click the task to configure it. Change the field type from job to static. A pre-populated dropdown list containing the days of the week will appear.

WhatDay task configuration showing enum dropdown

Itential application schema

The following JSON schema can be used as a reference for building valid pronghorn.json files, specifically the enum property:

1 {
2   "$schema": "http://json-schema.org/draft-06/schema#",
3   "type": "object",
4   "properties": {
5     "id": {
6       "type": "string",
7       "description": "Unique name of Pronghorn module. Most likely matches name in package.json.",
8       "pattern": "^(@[a-zA-Z0-9][-._a-zA-Z0-9]*/)?[a-zA-Z0-9][-._a-zA-Z0-9]*$"
9     },
10     "title": {
11       "type": "string",
12       "description": "Application's web API (REST or JSON RPC) namespace.",
13       "pattern": "^[a-zA-Z0-9][-_a-zA-Z0-9]*$"
14     },
15     "displayName": {
16       "type": "string",
17       "description": "Name displayed for application in Workflow Builder's application drop-down."
18     },
19     "export": {
20       "type": "string",
21       "description": "Application's JavaScript namespace. Must match value of module.export assignment.",
22       "pattern": "^[a-zA-Z0-9][-_a-zA-Z0-9]*$"
23     },
24     "type": {
25       "enum": [
26         "Application",
27         "Broker",
28         "Adapter"
29       ]
30     },
31     "summary": {
32       "type": "string",
33       "description": "A summary of functions this application provides."
34     },
35     "src": {
36       "type": "string",
37       "description": "File reference to package's main JavaScript module, relative to directory where pronghorn.json and package.json files are stored.",
38       "pattern": "^[a-zA-Z0-9][.-_a-zA-Z0-9]*.(js|bin)$"
39     },
40     "encrypted": {
41       "type": "boolean",
42       "description": "When true, Pronghorn expects an encrypted main JavaScript module with a .bin filename extension."
43     },
44     "roles": {
45       "type": "array",
46       "minItems": 1,
47       "items": {
48         "type": "string",
49         "description": "The allowed set of user roles the application's methods and views can specify.",
50         "pattern": "^[a-z-A-Z0-9][.-_a-z-A-Z0-9]*$"
51       }
52     },
53     "methods": {
54       "type": "array",
55       "items": {
56         "type": "object",
57         "description": "Object describing an application's method and its API.",
58         "properties": {
59           "name": {
60             "type": "string",
61             "description": "Method's name. Must match prototype function name defined in JavaScript source.",
62             "pattern": "^[a-z][a-zA-Z0-9]*$"
63           },
64           "display_name": {
65             "type": "string",
66             "description": "Text displayed in a workflow task's properties dialog."
67           },
68           "deprecated": {
69             "type": "boolean",
70             "description": "If true, method is deprecated.",
71             "default": false
72           },
73           "summary": {
74             "type": "string",
75             "description": "A brief explanation of the method.",
76             "maxLength": 50
77           },
78           "description": {
79             "type": "string",
80             "description": "Explain the method's purpose: what it does, what problem it solves, and why it was created."
81           },
82           "input": {
83             "type": "array",
84             "items": {
85               "type": "object",
86               "description": "Object describing a parameter.",
87               "properties": {
88                 "name": {
89                   "type": "string",
90                   "description": "Parameter's name. Must match parameter's name defined in JavaScript source.",
91                   "pattern": "^[a-zA-Z0-9][.-_a-zA-Z0-9]*$"
92                 },
93                 "type": {
94                   "enum": [
95                     "object",
96                     "array",
97                     "boolean",
98                     "number",
99                     "string",
100                     "enum",
101                     "*"
102                   ]
103                 },
104                 "enumerals": {
105                   "type": "array",
106                   "description": "Only used when type is enum.",
107                   "items": {
108                     "type": "string",
109                     "description": "An allowed value"
110                   }
111                 },
112                 "description": {
113                   "type": "string",
114                   "description": "Describe the parameter's purpose."
115                 },
116                 "info": {
117                   "type": "string",
118                   "description": "A tooltip. Include references to other APIs that return the parameter."
119                 },
120                 "required": {
121                   "type": "boolean",
122                   "description": "When true, parameter is mandatory.",
123                   "default": true
124                 }
125               },
126               "required": [
127                 "name",
128                 "type",
129                 "description"
130               ]
131             }
132           },
133           "output": {
134             "type": "object",
135             "description": "Describes the returned data.",
136             "properties": {
137               "name": {
138                 "type": "string",
139                 "description": "The outgoing variable name when method is called by a workflow job.",
140                 "pattern": "^[a-z-A-Z0-9][.-_a-z-A-Z0-9]*$"
141               },
142               "type": {
143                 "enum": [
144                   "object",
145                   "array",
146                   "boolean",
147                   "number",
148                   "string",
149                   "enum",
150                   "*"
151                 ]
152               },
153               "enumerals": {
154                 "type": "array",
155                 "items": {
156                   "type": "string",
157                   "description": "An allowed value"
158                 }
159               },
160               "description": {
161                 "type": "string",
162                 "description": "Returned value's description."
163               }
164             },
165             "required": [
166               "name",
167               "type",
168               "description"
169             ]
170           },
171           "task": {
172             "type": "boolean",
173             "default": false,
174             "description": "When true, method can be called by a workflow job."
175           },
176           "route": {
177             "type": "object",
178             "description": "When defined, enables a web API for the method.",
179             "properties": {
180               "path": {
181                 "type": "string",
182                 "description": "Final part of URL appended after namespace.",
183                 "pattern": "^(/[a-zA-Z0-9%][.-_a-zA-Z0-9%]*)+(/[:][.a-zA-Z0-9%][-_a-zA-Z0-9%]*)*$"
184               },
185               "verb": {
186                 "enum": [
187                   "POST",
188                   "GET",
189                   "DELETE",
190                   "PUT"
191                 ],
192                 "description": "HTTP request type."
193               }
194             }
195           },
196           "roles": {
197             "type": "array",
198             "minItems": 1,
199             "items": {
200               "type": "string",
201               "description": "The allowed set of user roles for this method.",
202               "pattern": "^[a-z-A-Z0-9][.-_a-z-A-Z0-9]*$"
203             }
204           }
205         },
206         "required": [
207           "name",
208           "summary",
209           "description",
210           "input",
211           "output",
212           "roles"
213         ]
214       }
215     },
216     "views": {
217       "type": "array",
218       "items": {
219         "type": "object",
220         "description": "Object describing an application's views.",
221         "properties": {
222           "path": {
223             "type": "string",
224             "description": "Final part of URL appended after namespace.",
225             "pattern": "(^/$)|(^(/([-a-zA-Z0-9@:%._+~#=]{2,256}))+$)"
226           },
227           "deprecated": {
228             "type": "boolean",
229             "description": "If true, view is deprecated.",
230             "default": false
231           },
232           "title": {
233             "type": "string",
234             "description": "Application name when type is view.",
235             "maxLength": 50
236           },
237           "template": {
238             "type": "string",
239             "description": "Relative file reference to the view's HTML file.",
240             "pattern": "^[a-zA-Z]([._-]|[a-zA-Z0-9])*(/[a-zA-Z]([._-]|[a-zA-Z0-9])*)*[.](jade|html)$"
241           },
242           "roles": {
243             "type": "array",
244             "minItems": 1,
245             "items": {
246               "type": "string",
247               "description": "The allowed set of user roles for this view.",
248               "pattern": "^[a-z-A-Z0-9][.-_a-z-A-Z0-9]*$"
249             }
250           },
251           "type": {
252             "enum": [
253               "task",
254               "view",
255               "dialog"
256             ],
257             "description": "Manual workflow tasks are type task. Applications are type view. Modal application views are type dialog."
258           },
259           "variables": {
260             "type": "object",
261             "description": "A skeleton object holding the view's parameters and return data.",
262             "properties": {
263               "incoming": {
264                 "type": "object",
265                 "description": "A skeleton object holding the view's parameters."
266               },
267               "outgoing": {
268                 "type": "object",
269                 "description": "A skeleton object holding the view's returned data."
270               }
271             },
272             "required": [
273               "incoming",
274               "outgoing"
275             ]
276           }
277         },
278         "required": [
279           "path",
280           "template",
281           "roles",
282           "type"
283         ]
284       }
285     }
286   },
287   "required": [
288     "id",
289     "type",
290     "encrypted",
291     "roles"
292   ]
293 }