Configurable Parameters

Configurable parameters define the inputs shown when someone runs an action in a Bosbec service. The selected or entered values are passed to the workflow configured for that action.

This reference covers the configurableParameters array used by service actions. It does not describe serviceSettings, which configure the service itself, or the workflow jobs that process the values.

In the Incident example, types such as bool, checkboxes, selectlanguage, attributes, and prio appear under serviceSettings. They configure service settings and are not execution parameter types. In particular, checkboxes under serviceSettings is different from the legacy checkbox type listed below.

Where parameters are configured

In a service definition, each action can have its own configurableParameters array. The Incident service example uses this structure in its dashboard actions:

{
  "type": "executeService",
  "templateName": "Message",
  "workflowId": "<workflow-id>",
  "triggerNames": "send",
  "configurableParameters": [
    {
      "title": "Write your message",
      "key": "message-text",
      "type": "Textarea",
      "required": true,
      "doNotSerialize": "true"
    },
    {
      "title": "Select recipients",
      "key": "sendtounitsjob.unitids",
      "type": "Unit",
      "multitude": "List",
      "required": true,
      "propertiesToRender": ["firstName", "lastName", "phone"]
    }
  ]
}

The action's workflowId and triggerNames identify the workflow and trigger to run. Each parameter's key identifies the value passed to that workflow. Use keys that match the workflow's expected inputs.

Common properties

Property	Purpose
`title`	Label shown for the parameter.
`toolTip`	Supporting text shown with the parameter. The spelling is `toolTip`.
`alias`	Legacy field.
`key`	Name under which the parameter value is sent to the workflow.
`required`	Marks the parameter as required in the execution form.
`doNotSerialize`	Controls whether the value is serialized with quotation marks. When enabled, set it to the string `"true"`, not the boolean `true`.
`getStepValueFromUnit`	Gets a value from the first selected unit whose matching key has a value.
`multitude`	Controls whether a resource selector accepts one value or a list. Common list value: `"List"`.
`propertiesToRender`	Selects which resource properties are displayed in a selector.
`categories`	Filters resource categories. Prefix a category with `!` to exclude it, for example `"!_system"`.

Some properties only apply to specific types. For example, multitude, propertiesToRender, and categories are used with resource selectors, not with every input type.

Parameter types

Use the type spelling from a working service definition. Existing definitions use a mixture of capitalization, such as Radiobutton, Textarea, Unit, and date.

Type	Purpose and type-specific properties
`text`	Single-line text input.
`textarea`	Multi-line text input.
`Int`	Integer input.
`date`	Date input.
`Radiobutton`	Choose one option. Define the choices in `radioOptions`.
`checkbox`	Choose from the values in `checkboxOptions`; the selected values are sent as a comma-separated string.
`Group`	Select groups. Use `multitude`, `categories`, and `propertiesToRender` to control selection and display.
`Unit`	Select units. Common display properties include `firstName`, `lastName`, and `phone`.
`UnitsInGroup`	Select units that belong to a group. Supports selector properties such as `multitude`, `categories`, and `propertiesToRender`.
`Message` / `Form`	Select a message or form resource. `propertiesToRender` and `categories` can configure the selector.
`FindUnitsByCriteria`	Selecting units using criteria. The Incident example uses `attributepreview` for attribute-based selection. See Select by attributes.
`attributepreview`	Select units by attributes and preview the number of matches.
`textareaEncryption`	Text input that returns an encryption object. Configure `encryptionObject` and `propertiesToRender`.
`UploadFileInService`	Upload a file as part of the service execution.
`information`	Displays information instead of collecting a value. Common properties include `title`, `description`, and `informationText`.
`hidden`	Adds a value without displaying an input to the user.
`tasklist`	Task-list control used by the Incident service example.
`formreplybuilder`	Form-answer filter control used by the Incident service example.

Copyable parameter examples

Each panel contains a standalone parameter object. Copy it into an action's configurableParameters array, then update the key, labels, and resource IDs to match your workflow.

Text

{
  "title": "Incident name",
  "toolTip": "Enter a name for the incident",
  "key": "ticketname",
  "type": "text",
  "doNotSerialize": "true",
  "required": true
}

Textarea

{
  "title": "Write your message",
  "toolTip": "Enter the message to send",
  "key": "message-text",
  "type": "textarea",
  "doNotSerialize": "true",
  "required": true
}

Integer

{
  "title": "Number of available spots",
  "toolTip": "Enter the number of spots",
  "key": "maxans",
  "type": "Int",
  "required": true,
  "propertiesToRender": []
}

Date

{
  "title": "Stop time (optional)",
  "toolTip": "Select a stop time",
  "alias": "Stop time",
  "key": "scheduled-stop",
  "type": "date",
  "required": false,
  "propertiesToRender": [],
  "doNotSerialize": "true"
}

Radio buttons

{
  "title": "Use opt-out?",
  "key": "optout",
  "type": "Radiobutton",
  "doNotSerialize": "true",
  "radioOptions": {
    "Yes": "yes",
    "No": "no"
  },
  "required": true
}

Checkboxes

{
  "title": "Send as",
  "key": "sendtype",
  "type": "checkbox",
  "doNotSerialize": "true",
  "checkboxOptions": [
    "app",
    "email",
    "sms"
  ],
  "required": true
}

Group selector

{
  "title": "Choose groups",
  "key": "sendjob.groupids",
  "type": "Group",
  "toolTip": "Choose one or more groups",
  "multitude": "List",
  "categories": [
    "!_system"
  ],
  "required": true,
  "propertiesToRender": [
    "name"
  ]
}

Unit selector

{
  "title": "Select recipients",
  "key": "sendtounitsjob.unitids",
  "type": "Unit",
  "multitude": "List",
  "doNotSerialize": "true",
  "toolTip": "Select one or more recipients",
  "propertiesToRender": [
    "firstName",
    "lastName",
    "phone"
  ],
  "categories": [
    "!_system"
  ],
  "required": true
}

Units in a group

{
  "title": "Select group members",
  "key": "sendtounitsjob.unitids",
  "type": "UnitsInGroup",
  "multitude": "List",
  "doNotSerialize": "true",
  "categories": [
    "!_system"
  ],
  "groupIds": [
    "<group-id>"
  ],
  "toolTip": "Select group members",
  "propertiesToRender": [
    "firstName",
    "lastName",
    "phone"
  ],
  "required": true
}

Message selector

{
  "title": "Select message",
  "key": "messageid",
  "type": "Message",
  "toolTip": "Select a message template",
  "propertiesToRender": [
    "name"
  ],
  "categories": [
    "!_system"
  ],
  "required": true
}

Form selector

{
  "title": "Select form",
  "key": "formid",
  "type": "Form",
  "toolTip": "Select a form",
  "multitude": "List",
  "doNotSerialize": "true",
  "propertiesToRender": [
    "name"
  ],
  "categories": [
    "!_system"
  ],
  "required": true
}

Find units by criteria (legacy)

{
  "title": "Select units",
  "toolTip": "Select units matching the criteria",
  "key": "findUnitsByCriteria",
  "type": "FindUnitsByCriteria",
  "criteria": "1",
  "multitude": "List",
  "propertiesToRender": [
    "realname"
  ],
  "groupingkey": "MetaData.1"
}

Select by attributes

{
  "id": "select-attribute-step",
  "title": "Select by attribute",
  "type": "attributepreview",
  "key": "findUnitsByCriteria",
  "required": true,
  "header": "Select by attribute",
  "description": "Select units and preview the number of recipients",
  "attributes": {
    "languages": {
      "internalOperator": "MustInclude",
      "header": "Languages",
      "description": ""
    },
    "skills": {
      "internalOperator": "MustInclude",
      "header": "Skills",
      "description": ""
    },
    "department": {
      "internalOperator": "MustInclude",
      "header": "Department",
      "description": ""
    }
  },
  "propertiesToRender": [
    "metadata.firstname",
    "metadata.lastname",
    "metadata.languages",
    "metadata.skills",
    "metadata.department"
  ]
}

Encrypted textarea

{
  "title": "Message with encryption",
  "key": "textareaencryption",
  "type": "textareaEncryption",
  "toolTip": "Enter a message to encrypt",
  "doNotSerialize": false,
  "required": true,
  "encryptionObject": {
    "alias": "",
    "key": "",
    "message": "",
    "encryptedMessage": "",
    "iv": ""
  },
  "propertiesToRender": [
    "encryptedMessage"
  ]
}

Upload file

{
  "title": "Upload a file",
  "alias": "Upload file",
  "key": "getfile.fileidentifier",
  "multitude": "single",
  "doNotSerialize": "true",
  "type": "UploadFileInService",
  "toolTip": "Select a file to upload",
  "required": true
}

Information

{
  "title": "Delete older codes",
  "description": "Codes older than 1 year will be removed when you click Run",
  "informationText": "",
  "type": "information"
}

Hidden value

{
  "key": "selectedactivity",
  "value": "@(unit.id)@",
  "type": "hidden",
  "doNotSerialize": "true"
}

Task list

{
  "title": "Task list",
  "alias": "Task list",
  "key": "tasklist",
  "type": "tasklist",
  "toolTip": "",
  "doNotSerialize": "true",
  "required": false,
  "propertiesToRender": []
}

Define selector options

For a simple radio-button selector, radioOptions maps the labels shown to the values passed to the workflow:

{
  "title": "Select status",
  "key": "newstatus",
  "type": "Radiobutton",
  "radioOptions": {
    "Open": "Open",
    "Pending": "Pending",
    "On Hold": "On Hold"
  },
  "required": true
}

Service definitions can also specify each option as an object with a value and an enabled setting. This lets service settings control which choices are available:

"radioOptions": {
  "write": {
    "value": "write",
    "enabled": "settings.use-message-input-write"
  },
  "template": {
    "value": "message-template",
    "enabled": "settings.use-message-input-template"
  }
}

Show fields conditionally

Use route on a selector to map a selected value to the next parameter's id. Set routeId to the id of the default next parameter. In this example, choosing a recipient type routes to the matching selector:

{
  "id": "select-recipient-type",
  "title": "Recipients",
  "type": "Radiobutton",
  "key": "recipient-type",
  "radioOptions": {
    "group": "group",
    "units": "recipient"
  },
  "route": [
    {
      "left": "metadata.recipient-type",
      "right": "group",
      "operator": "=",
      "id": "select-groups-step"
    },
    {
      "left": "metadata.recipient-type",
      "right": "recipient",
      "operator": "=",
      "id": "select-units-step"
    }
  ],
  "routeId": "select-groups-step"
}

The parameters reached by the route need matching IDs, for example select-groups-step and select-units-step. Keep the values in radioOptions, the route comparisons, and the workflow's expected values consistent.

Serialization and workflow inputs

The parameter's key determines the input name; doNotSerialize affects how the selected or entered value is serialized. When enabling it, use the string "true" as the normal representation, rather than the boolean true.

When adding or changing a parameter, verify all three parts together:

The execution form displays the expected input and enforces required values.
The parameter sends its value under the expected key when the service action runs.
The workflow trigger receives that value in the format expected by the jobs that use it.

Values selected from resources, such as groups, units, messages, and forms, may be IDs or lists of IDs. Check the relevant workflow input and the type's multitude setting before changing a selector from a single value to a list.