Service requests
- Synopsis
- Full Details
In briefA service request — a self service button on screen — is a form you publish so that someone can start automation without touching the workflow. Submitting it fires one or more events, one after another, in the order you set. Each button has versions and is deployed per environment, like a workflow, and the portal groups buttons by category.
WhereYou build them under Design › Self Service Config, on the Self Service Configuration page; Organize Self-Service Buttons on its toolbar arranges the portal page. People submit them under Operations › Self Service — the portal.
WhenUse one when someone outside the automation team needs to start a known task on demand:
- a business user requesting a file restore, a report, or a re-run;
- an operator starting a routine task with a few choices filled in, such as a region or a date;
- a task of several steps whose events must run in a set order.
Use something else when nobody needs to ask: a schedule belongs in a workflow's frequency, and a reaction to a failure in a notification group.
How
- On Self Service Configuration, select New Self Service Button, then add its events in
the order they must run; each
${…}placeholder you write adds an input. - Save, which creates a version, then deploy it to each environment.
- Check that requesters hold the permissions the portal checks, then submit it once yourself.
The full steps are in Create a service request.
- Events are checked as the requester, not as the person who built the button.
- A button missing from the portal is usually not deployed to that environment, or its deployment is inactive or outside its effective window. A Hidden rule that is true also removes it.
- Hidden and Disabled rules are checked again on submission. A rule that can't be evaluated usually leaves the button usable, with a warning.
- Arranging the portal page or filing a button in a category needs no redeploy.
- The configuration grid's Active column and a button's Deploy modal show only the environments your role may view deployments in; No access means it may view none.
- A Pinned deployment must name a version the button has; one that names a missing version is not shown in Self Service, and its card says so.
- An input's default must be one requesters can submit, where the button's events place it. The input editor and the save refuse one that is not, and Copy leaves it out.
- One failing event doesn't stop the others. After a partial failure, don't submit again: the events that worked would run twice.
- If no answer comes back in time, check the event log before submitting again.
- An input no event references is removed from the button, so delete a placeholder only when you mean to drop its input.
- Collect a requester's secret with a Password input, not a Text input; an encrypted property can
be used only as the value of
$PROPERTY:SET/$PROPERTY:ADD.
The end-user side is the self-service portal.
Task walkthrough: Create a service request. This page is the full configuration and troubleshooting reference.
In OpCon Continuum, a service request is a form a Builder publishes so that a business user can trigger automation without touching the workflow — for example, "Request a file restore" or "Run an on-demand report." Submitting the form fires one or more events.
In the interface a service request is a self service button, and the page you author them on is Self Service Configuration — reached from Design → Self Service Config. Global search lists the same objects under Self Service Buttons. The web address is unchanged, so an existing link or bookmark still resolves; a link straight to one button opens the grid with that button's dialog already open.
What a service request contains
| Part | Notes |
|---|---|
| Name | 1–255 characters, following the platform naming rules — a name like Restart Instance (EU) or START/STOP VM is valid. |
| Inputs | The form fields the user fills in. |
| Events | The actions fired on submission, in order. |
| Documentation / Confirmation Message | Guidance for the requester. The documentation is shown at the top of the request form under Notes; the confirmation message is shown as a note above the form's fields. |
| Tags | For organizing and for filtering in the portal. Through the API, a request names its tags by identifier, and the identifier's letter case does not matter. |
| Category | The container it is filed in — see Categories. One per button, optional. |
| Hidden / Disabled | Two rules deciding whether the button appears in the portal and whether it can be submitted — see Hidden and disabled. |
| Versions | Each save creates a new version. Every save after the first asks for an optional Change Description — at most 500 characters, trimmed. Saving a new button asks nothing, so its first version is labelled Initial version. |
| Deployments | Which environments the request is available in, and at which version. |
| Transformations | Per-environment overrides applied to the request (see the Deployments and Transformations tab). |
- Configuration Grid
- Categories and Layout
- Hidden and Disabled
- Input Types
- Events
- Variables
- Deployments and Transformations
Configuration Grid
The configuration grid
Self Service Configuration lists every self service button in one grid. Selecting a row opens the button for editing; each row's action menu holds Edit, Copy and Delete, and selecting rows with their check boxes enables a bulk Delete. Edit, the menu's first item, opens the same editor as selecting the row. If you cannot edit buttons in the button's workspace, either way opens it read-only.
| Column | Shows |
|---|---|
| Name | The button's name. This column carries the grid's search box rather than a sort control; every other column sorts. |
| Active | One badge per environment the button is live in, with the version deployed there — limited to the environments you may see its deployments in (see below). |
| Category | The category it is filed in, blank when it has none. |
| Tags | Its tags. Beyond three, the rest are summarized as a count. |
| Workspace | The workspace it belongs to. |
| Last Updated | When it was last saved. |
Category and Last Updated are ordered by the server, so they sort the whole catalog. The rest sort the page you are looking at — search or filter a large catalog down first.
A deployment that is outside its effective window is left out of the Active column rather than reported as inactive.
What the Active column shows depends on your role
A button's deployments are their own permission, Service Request Deployments View, separate from the permission to see the button. The Active column follows that permission, environment by environment:
| The cell shows | Because |
|---|---|
| Badges | The environments the button is live in that your role may view deployments in, for the button's workspace. A role granted in one environment sees that environment's badge only. |
| Nothing | The button is not live in any environment your role may view deployments in — either it is deployed nowhere, or only where your role does not reach. |
| No access | Your role holds Service Request Deployments View nowhere, so no deployment is shown. |
Sorting on Active counts only the badges you can see, and a No access row counts as none.
The button's own dialog follows the same rule. Its Deployed: summary lists only those environments, and Manage Deployment opens the Deploy modal with a card only for each environment where your role may view the button's deployments. A role that may create deployments in an environment but not view them there does not see that environment, so it cannot deploy there from the modal. If the deployments cannot be loaded, Deployed: reads Could not load deployments instead of None.
Earlier builds checked only that your role held the permission somewhere, and then showed every environment's deployments, so a role granted in one environment saw them all.
Organize Self-Service Buttons opens the page that arranges the portal — the order of the category sections, each category's band colour, the order of the buttons inside each section, and which category each button is in. See Arranging the portal page. It is disabled, with a tooltip saying so, for anyone without permission to edit categories.
Categories and Layout
Categories
A category is a container a self service button is filed in, and it is how a set of buttons that a user works through as one task stays together. Categories are tenant-wide and a button belongs to at most one.
| Category setting | How it works |
|---|---|
| Name | 1–255 characters, unique per tenant regardless of case, following the platform naming rules. Short names such as IT are the point, so the usual three-character minimum does not apply. |
| Where it is set | The button's dialog. The picker searches existing categories and offers New Category for a name it doesn't find, so a category can be created without leaving the button you are filing. A button can also be dragged into another category on Organize Self-Service Buttons, which has its own New Category button. |
| Clearing it | Choose None. |
| Band colour | One of ten named colours, or none. Set on the Organize Self-Service Buttons page rather than in the button's dialog — see Arranging the portal page. |
| Position | Where the category's section sits on the portal page. Also set on Organize Self-Service Buttons. |
The portal groups by category. A requester sees one section per category that has at least one
button they can see — each headed Category: followed by the category's name — in the order set on
Organize Self-Service Buttons, with the buttons that are in no category gathered into a General
section pinned last. A category with no visible button draws no section at all — including one that
is empty only because every button in it is hidden by a rule.
Both levels are ordered by a saved position, then by name. Sections go by the category's saved position, buttons by their saved position within the section. A new category is placed after the existing ones, and a new button after the buttons already in its category, or in the uncategorised section when it has none, so creating one never moves it ahead of an order somebody saved. Where two share a position — as rows created by earlier builds do until somebody arranges them — the name decides and the row id breaks a remaining tie, so those read alphabetically and stay in the same order between visits. A category that carries a band colour draws its cards on a band of that colour; one with no colour, and the uncategorised section, draw a grey band.
The uncategorised section cannot answer to a name one of your own categories already has, or two sections would read identically. It takes Uncategorised instead, then No Category, then that wording numbered. Nothing reserves General, so this is decided per tenant from the categories you actually have.
A category is not part of the versioned configuration. Filing a button, refiling it, or renaming a category therefore needs no redeploy — unlike a change to the button's inputs or events. Saving the button from the dialog still mints a version, as every save does; it is only the category itself that sits outside versioning.
Deleting a category never deletes a button. Every button filed in it becomes uncategorised instead. Deleting also requires permission to edit self service buttons across the whole tenant, not just in one workspace, because the detach touches buttons in every workspace — see Roles and permissions.
A button whose category has been deleted while its dialog was open shows Category unavailable rather than an empty picker, so the value isn't silently dropped on the next save.
Arranging the portal page
Organize Self-Service Buttons, on the Self Service Configuration toolbar, is where the requester's page is arranged. It holds four things at once and saves them as one layout:
- the order of the category sections,
- each category's band colour,
- the order of the buttons inside each section,
- the category each button is in.
The page draws the sections and cards the way the portal draws them, so what you arrange is what a requester sees.
Moving things
A drag handle sits next to each section's Category: heading and on the top-left corner of each
card. Drag a heading's handle to move a whole section; drag a card's handle to move a button. The
handle is the only thing that starts a drag — selecting the card itself opens its preview instead.
By keyboard, Space lifts the item, the arrow keys move it, Space drops it and Escape
cancels.
Drag a card into another section to change its category, including an empty one and the section for uncategorised buttons. Moving a button needs permission to edit self service buttons in the button's workspace; a card you cannot move can still be reordered within its own section. If the save finds you cannot move one, it is refused and nothing is written: You can't move Reset Password to another category. Moving a button requires permission to edit Self Service buttons in its workspace. A move is part of the layout, like a reorder: it mints no version and needs no redeploy. A button you move and then move back leaves nothing to save.
A move is not undone by a button dialog that was already open. If a button is moved here while someone has its dialog open, saving the dialog without changing its Category keeps the button in the category it was moved to, and the rest of the save goes through. Earlier builds put the button back in its old category. Choosing a different category in the dialog still moves it.
The General section for uncategorised buttons sits last, and has no handle and no colour picker — there is no category row to store a position or a colour on. It is always shown to someone who can edit the layout, so a button can be moved back into it.
New Category above the sections opens Add a New Category: type a unique name and Save. The category is created at once, before the layout is saved, and its section appears first; drag it where you want it. A name already in use is refused with A category with this name already exists. The button is shown only to someone who can create categories. Discarding your unsaved moves does not remove a category created this way.
Band colour
The colour picker at the right of each section's heading (its tooltip reads Choose a category color) offers None plus five named colours — Secondary, Success, Warning, Error and Info — as a four-column grid of swatches. Arrow keys move between them, Enter or Space picks one and Escape closes without a change.
A category that already has one of the earlier colours — Accent, Sapphire, Flame, Warning yellow or Teal — keeps it, and its band still shows it. The picker adds that one colour to the grid for that category, so you can keep it or move to one of the five; once you move away, it is no longer offered. The categories API accepts these ten colours and refuses any other name.
Narrowing what you see
Four controls narrow the page. None of them change the arrangement — a card they hide keeps its place in the order, and a save still carries it.
| Control | Effect |
|---|---|
| Environment | Shows the page as a requester in that environment sees it: the buttons deployed and active there, with their hidden and disabled rules evaluated, so a hidden button drops out. Leave it empty and you see the saved configuration for every button instead, with no rule evaluated. |
| Workspace | Limits the cards to one workspace. |
| Search Button Name | A picker over the buttons in view. Choosing a name scrolls to that card and highlights it rather than filtering the page. |
| Tag | A multi-select list of the tags the cards in view carry; each choice shows as a chip. Choose several and a card matching any of them is shown. |
The environment here is independent of the one selected in the header, and switching either picker never discards moves you have not saved. A section whose cards are all narrowed away still shows, with a line saying no button in it matches the current view.
Previewing a button
Selecting a card opens the form the portal would render for it: the documentation, the confirmation message and the input fields, all disabled, with no way to submit. With no environment picked it says it is showing the saved configuration.
Saving
Save writes the whole layout in one go, and it is presentation only: it mints no version, needs no redeploy, touches no deployment and leaves each button's Last Updated alone.
The layout is one object covering every live category and button in the tenant, so a save must list all of them. A role that cannot view every self service button therefore cannot save an arrangement — the save is refused rather than writing a partial order. Reordering is a category-administrator job; see Roles and permissions.
Leaving the page with unsaved moves asks first, and offers to discard them or keep editing.
If somebody else changed a category or a button between your opening the page and saving it, the save is refused and you are offered Reload. Reloading brings in the latest arrangement and discards your unsaved moves, so a concurrent change is never silently overwritten. A failed reload leaves your moves in place to try again.
Hidden and Disabled
Hidden and disabled
Hidden and Disabled decide whether a button appears in the portal and whether it can be submitted. Each is a switch coupled to an expression, and the portal acts on the answer.
Authoring a rule
The two halves are one control over one stored value:
- Switch off stores
false. The field is emptied and disabled — the switch is the decision, so a disabled field still showing text would claim an expression survives a save that writesfalse. - Switch on enables the field and requires it. Save stays disabled while a switch is on with nothing typed, and the field says "Enter an expression, or turn the switch off".
The expression is the same language properties use, written as a bare condition —
[[MAINTENANCE_WINDOW]] == "true" — with no [[= ]] wrapper needed. A rule is capped at 1,000
characters.
| On the field | What it does |
|---|---|
| The property picker beside it | Inserts a property token. Scoped to global properties and the clock, which is all the server resolves a rule against — there is no job, schedule or agent in context, so a token from one of those scopes could only ever evaluate to an error. |
| Test | Runs the rule as the portal will and reports the answer under the field — True, False, or the reason it could not be evaluated. Nothing is saved, and the result is retired as soon as you change the text it describes. |
Testing a rule reads the tenant's global properties, so it needs view on properties as well as edit on service requests. The outcome is one bit, but a bit is enough to recover a property's value by repeated comparison, so reading the store is gated as its own permission here, exactly as it is everywhere else.
How a rule is evaluated
| Part of the evaluation | How it works |
|---|---|
| When | Every time the portal loads the button list, and again when a request form opens. |
| Against what | The tenant's global properties and the server clock, in UTC. Each rule is resolved strictly: there is no fallback in which a failed expression renders as its own text. |
| Per environment | Over the transformed configuration, so a transformation rule that overrides hideRule or disableRule for one environment takes effect there. |
| The literals | true, false, empty and unset are answered directly, with no property lookup — so a button that was never given a rule costs nothing to evaluate. |
| Encrypted properties are refused | A rule naming an encrypted property evaluates to an error rather than comparing against the decrypted value. A rule's author can read the outcome off the button they are editing, which would make the rule a one-bit oracle over every secret in the tenant. |
Three outcomes, not two. A rule answers true, false, or error — a syntax problem, an
unknown property name, a result that is neither True nor False, an encrypted property, or a lookup
that failed. An error fails open: the button stays visible and stays submittable.
Rule evaluation is bounded, so one tenant's rule cannot spend the portal's time without limit. A rule that asks for more work than its budget allows — typically one reading a very large property, or building a very large string — is refused.
When that happens to a Disable rule, the submission is refused: the rule never said
"enabled", so the request reports that its availability could not be checked. Every other error
still fails open, as above. Keep a rule's work small — compare against short properties, and keep
text operations off large values.
What the portal does with the answer
| Outcome | In the portal |
|---|---|
| Hide rule true | The button is dropped from the catalog. Its tags do not appear as filters and searching for it finds nothing. A deep link to its form lands on the same not-found state a deleted button would. When every deployed button is hidden, the catalog shows its ordinary empty state. |
| Disable rule true | The card is shown but inert — no selection, no keyboard activation, greyed, with the tooltip "This request is not available right now." If it is reached by a direct link, its request dialog opens read-only with an alert naming the button, and Submit is disabled. |
| Either rule in error | The button stays usable, with a warning icon in the card header and a warning in the request dialog: "This request could not be checked. Contact your administrator." The card header's icon carries the same text. |
Neither the rule text nor the evaluator's message ever reaches a portal user. The expression and the property names it reads are design information, and submitting a request needs no design permission — so the portal's copy is deliberately generic, and the message that names the expression is returned only to Test.
The request dialog re-reads the deployed list on every open, so the rule a portal user is held to is at most one open old, and Submit is held disabled while that read is in flight or has failed rather than acting on a stale answer. The rules are then evaluated again on the server when the submission arrives, so a button hidden or disabled since the dialog opened is refused and nothing is sent:
- Hidden — the submission is refused as "This service request is not available in this environment", the same answer as for a button that is not deployed there.
- Disabled — it is refused as "This service request is disabled and cannot be submitted right now".
What changed from the switches
An earlier build reduced each rule to a plain on/off switch, because there was no way to evaluate an expression. Three things follow:
- A stored expression opens as itself again. The warning that saving would flatten it is gone, along with the flattening. Restoring an older version of a button puts its expression back unchanged.
- The literal
truea switch wrote is not a special case — it is simply the expression that is always on, and it opens as a switch on withtruein the field. - The configuration grid has no Hidden or Disabled column. Rule state is authored and tested in the button dialog and takes effect in the portal; the grid reports which environments a button is live in and nothing about its rules.
Input Types
Input types
Eight types are offered in the input editor:
| Type | Notes |
|---|---|
| Text, Password, Number, Date, Choice | The ordinary form fields. |
| Text Collection | The user builds a list of text entries, submitted as one delimited string. |
| Workflow Selection, Job Selection | A type-ahead picker over real workflows or jobs — see below. |
Workflow Instance Selection and Job Instance Selection are not offered. Both remain valid in stored configuration, so a request that already uses one still loads and still saves; on the request form such an input renders as free text.
Each input can be required and have type-specific validation (min/max, length, pattern, date range), and a default value — see Default values. Choice options can be reordered in the builder so they appear in the order you want.
Default values
A default is the value the request form starts with, so a requester can submit it as it is or change it. The input editor sets one for seven types:
| Type | Field | Notes |
|---|---|---|
| Text | Default Value | Enter the starting value. |
| Number | Default Value | Enter the starting number. Saved as a number. |
| Date | Default Date | Select the starting date. A default stored as a full date and time shows its date, which is the part the request form reads. |
| Choice | Default Choice | Select the starting option. One of the input's options; None means no default. Removing the chosen option clears the default. |
| Text Collection | Default Entries | Add each entry separately. Each entry is added with Enter, the add button, or by leaving the field, and shows as a chip you can remove. The entries are saved joined on the input's delimiter, and changing the delimiter rejoins them. A refused entry's message is checked again when you change the delimiter or a rule, so it clears once the entry is acceptable. |
| Workflow Selection | Default Workflow | Select the starting workflow. The default is the workflow's name, the value the request form submits. |
| Job Selection | Default Job | Select the starting job. A job of the input's chosen workflow, by name. Until a workflow is chosen the field is unavailable, with Select a workflow first. A stored job that is not in the workflow stays listed, with This job is not in the selected workflow. Select another job or clear the field. If the workflow's jobs cannot be read, the field becomes a text box: Enter the job name exactly. |
A default must be one a requester can submit, and the editor will not save the input until it is, showing the reason on the field. It is checked in two ways:
- Against the input's own rules, the same ones the request form applies — length, pattern, minimum and maximum, date bounds, invalid characters, duplicates and the delimiter. A Text Collection entry the rules refuse is named, with Requesters cannot submit this default. Remove the entry and add each value separately.
- Where the button's events place the input. A default holding a comma is refused when an
event puts the input in a field that cannot carry one: The default contains a comma, which the
event template uses as its field separator. Remove the comma. A Text Collection default that
fills a field with its own separator, such as
tags, must be joined on that separator: The default fills<field>, which separates its values with<separator>, so its entries arrive as one value. Set the delimiter to<separator>. See Fields that need a specific delimiter.
A Date input under Minimum is today takes no default: A default date cannot be used with "Minimum is today": it stops being valid once that day passes. Clear the default. Under Maximum is today, a date later than today is only a warning — Requesters cannot submit this default today. — because it becomes valid on its day.
Leaving the field empty means no default, even on a required input. Changing an input's type clears its default. A Password input has no default field; a default already stored on one, or on an instance-selection input, is kept unchanged when you edit it.
Saving the button checks the defaults too
The same check runs when the button is saved, so a default that reaches the platform some other
way is refused as well. The save is refused with a message that starts with the input's name —
<input name>: followed by the reason above — and stores nothing.
A save checks only the inputs it changes: an input it adds, one whose type, default or rules it changes, and one that an added or edited event now places somewhere new. A button that already holds a default requesters cannot submit can still be renamed, retagged or filed in a category; the default is checked when you edit that input. Restore judges the version it restores against that version, so a version saved before this check stays restorable.
Copy leaves out a default requesters cannot submit. The Copy dialog names the inputs
first — Requesters could not submit the default of these inputs, so the copy will not have one:
<input names>. — and the copy is made without those defaults. If the dialog had not named
them, a message after the copy does: Copied. Requesters could not submit the default of these
inputs, so the copy has no default for them: <input names>.
What a validation pattern may be
A pattern you write on a Text or Text Collection input is applied in the browser of every person who opens the request. It is not handed to the browser's own regular-expression engine: it is compiled and matched by the platform, in time proportional to the value's length however the pattern is written. The practical effect is that a pattern can no longer hang a requester's form — but the input editor refuses a few things, and will not save the input until the pattern is fixed:
| Refused | Why |
|---|---|
| A pattern longer than 200 characters | That is the longest pattern the portal applies |
Backreferences (\1) and lookaround ((?=…), (?!…)) | Their meaning cannot be matched this way |
The legacy escapes \8, \a, \c1 | Easy to misread, and they mean different things in different engines |
A {n,m} count above 1000, or a pattern that compiles to more than 1000 states | The size bound a counted repeat is held to |
Everything whose meaning is plain set membership is supported: literals, escapes, character classes,
., ^, $, \b, \B, groups, alternation, and every quantifier. A pattern that is accepted
means exactly what it would mean to the browser.
Two limits apply when the pattern is matched rather than saved: a value longer than 5000 characters does not match, and a match that would be unusually expensive is abandoned and the value refused. An ordinary pattern on an ordinary value is nowhere near either.
These rules are applied by the input editor, not when the request is saved, so a service request stored with a pattern they refuse still saves, copies and restores as before. The portal does not apply that pattern at all rather than applying it unsafely, so it restricts nothing. Open the input and replace the pattern with one the rules accept.
Placeholder and help text are no longer editable. The two fields have been removed from the input editor for every type. A value already stored is preserved on save and still renders on the request form — there is simply no longer a way to write a new one.
Choice
A Choice input renders on the request form as a searchable list: the requester can type into the field to narrow a long set of options rather than scrolling the whole list. An optional Choice carries a clear control for emptying it once a value is picked; a required one does not, since it has to hold a value to submit. There is no longer a None entry inside the option list itself — an optional Choice is cleared with that control instead.
Typing into the field only narrows the list; the input takes a value only when you pick an option. Type to narrow the list, then pick one. To empty an optional Choice, use its clear control rather than deleting the text.
Text Collection
A Text Collection input lets the user build a list of text entries, shown as removable chips,
and submits them as a single delimited string. The separator is configurable per input and
defaults to a colon (:).
Each entry is validated on its own against the input's min/max length, pattern, and an optional set of invalid characters. An entry can't contain the delimiter, and you can optionally disallow duplicate entries.
An entry can't start or end with part of a delimiter of more than one character, because it
would fuse with the delimiter beside it: with ::, the entries a: and b join to a:::b,
which splits back as a and :b. The request form, the input editor's Default Entries and
submission all refuse such an entry — Entries cannot start or end with part of the delimiter
"<delimiter>". A single-character delimiter is not affected.
Why the default is a colon, not a comma
An event template separates its own fields with commas and has no escape character, so a comma-joined list is indistinguishable from several template fields. The request form therefore refuses any entry containing a comma unless the input's delimiter is itself a comma. The input editor shows the delimiter as editable text seeded with the default, so the effective value is visible rather than implied.
A comma is still a legal choice, for one case: an input that fills the last field of its event, which rejoins the comma-separated tail. The editor warns when the delimiter is a comma.
A delimiter that contains a comma without being exactly a comma, such as ,;, is judged where
the button's events place the input, by the rules submission applies:
- A field that refuses it blocks the save. The editor will not save the input, and names each
field that refuses the list, with the fix: Requesters cannot submit a list with more than one
entry:
<field>cannot carry a comma, so use a delimiter with no comma in it. A field with its own separator is named the same way, with the separator it needs. - The last field of an event takes it, such as a console message, so the input saves. An event that fires a stored command line rather than named fields takes it nowhere (see The requester's values are checked field by field).
- An input no event uses yet saves, with a warning: No event uses this input yet. A delimiter with a comma in it only works in the last field of an event, such as a console message.
Fields that need a specific delimiter
A few event fields carry several values inside one template field and are split back apart on a character the event contract fixes:
| Field | Separator it needs |
|---|---|
tags ($JOB:TAGADD / TAGDEL, $JOBMASTER:TAGADD / TAGDEL) | , or ; |
dates ($CALENDAR:ADD / DEL) | ; |
properties ($JOB:ADD / ADDHLD, $SCHEDULE:BUILD / BUILDHLD) | ; |
A list input feeding one of these must use that character — for tags, either one. If it doesn't,
the submission is refused with a message naming the character the field needs — because the mismatch is otherwise
accepted downstream as a single fused value and nothing reports it. The colon default therefore
governs single-valued fields, which is where a wrong separator was actually being noticed.
This holds wherever the input sits in the field. tags is the last field of its event and takes
every value after it, so in $JOB:TAGADD,CURRENT,SCHED,MYJOB,urgent,${tags} the input comes after a
tag the author typed and still fills tags: it must be joined with a comma or a semicolon, and a
colon-joined list is refused. Earlier builds did not check an input placed after other values in such a field,
so alpha:beta was created as one tag named alpha:beta.
The delimiter is applied when the stored value is split back into entries, so a value that already
contains it breaks apart. A default of 08:30 under a \d{2}:\d{2} pattern arrives as 08 and
30 and is refused — and re-entering 08:30 is refused too, because an entry can't contain the
delimiter. Times, Windows paths and host:port values all collide with the colon; choose something
else for those.
The same applies to a list stored under the old comma default: it arrives as one entry and is refused. A requester fixes it by removing the entry and re-entering the values, which rejoin on the colon. A stored default value does not self-heal that way — re-entering doesn't write it back, so every requester meets the same refusal until the default is fixed. Open the input in the input editor: Default Entries shows the stored list as one entry with the request form's message, and the input will not save until you remove it and add each value separately — see Default values.
Workflow Selection and Job Selection
Both types put a type-ahead picker on the request form in place of the text box they used to fall back to. The requester types to narrow the list, and the value submitted is the name — which is what an event template expects.
| Type | What the requester picks | Configured with |
|---|---|---|
| Workflow Selection | Any workflow they are allowed to read | Nothing extra |
| Job Selection | A job from one workflow, de-duplicated and sorted by name | The workflow, chosen by the author in the input editor |
Job Selection needs a workflow. The input editor requires one before it will save the input. The API does not, because the type shipped before the setting existed: rejecting a stored input that lacks one would have frozen its whole button, so those load and save as before and render as free text on the form.
When a picker falls back to free text
Both pickers read workflows from the design side, which is a separate permission from using the portal — so a requester can legitimately be allowed to submit the request and not allowed to read the list behind one of its fields. A picker with no options can never satisfy a required input, which would leave Submit permanently unavailable and the whole button unusable. So when the list cannot be produced and the requester cannot do anything about it, the input falls back to the free-text box the type used before it had a picker:
| Situation | Result |
|---|---|
| The requester may not read workflows | Free text |
| The workflow the author chose has been deleted | Free text |
| Job Selection with no workflow configured, or a workflow with no jobs | Free text |
| A temporary failure — a server error, a dropped connection | The picker stays, with an explanation; retrying can still succeed |
A fallback caused by the list itself being unreachable says so on the field, so the change is not silent.
Date
A Date input can be bounded by a fixed minimum and maximum date, or by today:
- Minimum is today and Maximum is today are check boxes under the matching date field. Each one disables and clears the fixed date beside it, so a bound is either a fixed date or today, not both.
- "Today" is evaluated when the requester's entry is validated, at local midnight — so a request that may not be back-dated stays correct every day without being edited.
A crossed pair of fixed dates is refused by the input editor, which names the problem on the field: a minimum after its maximum leaves no answerable day, and a required input in that state makes the whole button unsubmittable. The API still accepts one, because a crossed pair is ordinary stored data from before the check existed — refusing it there would freeze every button holding one, and would make such a version impossible to Copy or Restore, neither of which goes through the input editor.
Text formatting
A Text input can reshape the submitted value at submit time. The input editor offers these settings, under Format Settings, on Text inputs only; a Password input given them through the API is formatted the same way.
- Strip Characters — remove specified characters from the value before it's submitted.
- Padding — pad the value to a fixed Padding Length with a chosen Padding Character, on the Left or the Right. Padding is all-or-nothing: direction, character, and length are set together. The length is capped at 5000, which is also the longest event template a button stores — a larger value is refused when you save, and a request already storing one is refused at submit rather than having the padding allocated.
Events
Events and variable substitution
Each event has a type, structured parameters, and an order. A parameter can include placeholders that are replaced when the request is submitted — either with the requester's form values or with facts about the requester themselves.
An event is built in the standard event form — the same editor the job editor, a workflow's
completion events and
Vision use — so you fill in the chosen type's own fields rather than writing
a command line. The button's inputs and the SM. system variables are offered as ${…} inserts, and
global property tokens are offered alongside them. Every event on the
button is checked, including ones you did not change, and Save is refused until all of them
pass, with each problem reported on the event it belongs to.
The requester's values are checked field by field
What the button stores is its parameters, and what it fires is named fields. The command line is derived from the parameters rather than being the thing you edit.
This is what makes the submission checks exact. The requester's values used to be substituted into a stored template string, so the platform had to work out what each value meant from its position among the commas — and it authorized, counted tokens and checked for secrets by command-line slot. Each value is now authorized, counted and secret-checked as the field it actually fills.
An event saved before this change keeps firing its stored line, unchanged, so nothing a button already does moves. It converts to named fields the next time you edit that event. An event you leave alone is sent back exactly as it was loaded, so it keeps firing what it fired before.
A Text Collection input joined on the default colon may fill a single-value field, and fires as one value. It is still refused when it is joined with commas into a field that cannot hold more than one, or when it fills a field that reads its own sub-separator on a different delimiter — in both cases the values would be read as separate fields.
A Password input may be used in any event. The flag masks the box on the form; it does not restrict where the value may go. Every field a password input fills is redacted in the copy of the event the platform stores; the event itself runs with the value.
The events run in the order you arranged them
A request's events are submitted sequentially, in order — one finishes before the next starts.
Arrange them so that anything an event depends on has already happened.
That is what makes a chain safe to author:
$PROPERTY:SET,RUN_REGION,${Region}
$JOB:ADD,[[$DATE]],DAILY,EXTRACT,RUN_REGION=[[OI.RUN_REGION]]
Earlier builds sent the events as a batch that ran several at once, so the $JOB:ADD above could be
carried out before the $PROPERTY:SET it depends on and add the job with the previous value.
Ordering is now the contract.
One event failing does not stop the others. The remaining events still run, and the result names which ones failed. That is deliberate, but it means a chain's later events may run after an earlier one failed, so do not rely on a failure part-way through stopping the rest.
A request that is authorized against a property an earlier event writes is checked against every value that property might hold — including the value it had before the request started, since a write can fail and the request carries on. A write whose value cannot be worked out in advance refuses any later event that reads that property, rather than letting it through unchecked.
What a requester needs permission for
The events are checked as the requester, not as the Builder who saved the button. A requester needs:
| Permission | Where it must apply | Without it |
|---|---|---|
| Self Service Portal View | Anywhere to open the page, and the button's workspace, in this environment, to see a button | Held nowhere, the Self Service page does not open. Not held for a button's workspace in this environment, that button is not listed. |
| Self Service Portal Execute | The button's workspace, in this environment | The submission is refused as "This service request is not available in this environment". |
The permission each event type requires — $JOB:ADD needs Job Instances Create, for example | The workspace of the object the event names, in this environment, once the form values are filled in | The submission is refused with permission.denied. |
| Properties View | Each property the events name in a [[…]] token, in that property's workspace | The submission is refused with permission.denied. |
One refused event refuses the whole submission, and nothing is sent. The portal shows Request Failed with the text permission.denied and does not say which permission is missing, so a requester who sees it needs an administrator to compare their roles with the button's events.
The page lists the buttons deployed to the environment whose workspace the requester holds Self Service Portal View in, for that environment. A button in a workspace they can view but not submit in is still listed; it opens normally and is refused on submit.
What the requester sees when it does not simply succeed
| Outcome | What the portal shows |
|---|---|
| Every event accepted | Success |
| Some events failed | How many failed, each failed event's type and error, and that the other events ran — so submitting again would run those a second time. No retry is offered. |
| No answer came back in time | Request Outcome Unknown, and a prompt to check the event log before submitting again. Some events may already have run. No retry is offered. |
The last two deliberately do not invite a retry. An earlier build said Please try again on a partial failure, which is the one thing a requester should not do: the events that worked would run twice.
A submission the platform could not even start — because there was not enough time left to get an answer — is reported as such ("This request took too long to prepare, so none of its events were sent."), with nothing sent, so it is safe to submit again.
A submission is bounded in size, independently of what was stored
Whatever the stored request says, the submit path refuses a submission that would build something too large, before it builds it:
| Bound | What is refused |
|---|---|
| 16,384 characters per submitted value | A single value longer than an event line can carry |
| 16,384 characters per built event line | A value that would push the line past the limit as it is assembled, including the template's own tail |
| 100 events per submission | A request that would submit more |
These are checked independently of the stored configuration, so a request saved before the save-time caps cannot get a large value or an over-long line through by having been stored earlier.
Variables
Input variables
Write an input placeholder as ${Name}. The name is any text that does not contain a brace, so
spaces, dots, slashes and punctuation are all fine:
${Start or Stop}
${Resource Group Name}
${TargetPath}
Writing one is what creates the input: the configuration dialog detects every ${…} across your
events and adds a matching input definition — type Text, required — for any it does not
already have. The reverse is also true: an input no event references is removed. The dialog
matches a placeholder to an input by the input's id, which is what the event form inserts. At
submit, a placeholder is matched by id first and then by the input's name, ignoring case.
${input.Name} is a legacy spelling that names the same input as ${Name}. Nothing produces it any
more, but it is still resolved so that configurations written before it was retired keep working.
A name with a space in it — ${Start or Stop}, as a Classic button would have written it —
was not detected as a placeholder. Because an input no event references is removed, simply
opening such a button in the configuration dialog silently deleted all of its inputs. Any name
is now detected, so opening a button removes nothing. A button whose inputs went missing needs them
re-added once; it will not happen again.
System variables
Four placeholders are filled in from the user who submits the request, not from the form. The event form offers them as inserts beside your own input variables.
| Placeholder | Resolves to |
|---|---|
${SM.USER.EMAIL} | The requester's email address. |
${SM.USER.NAME} | The requester's display name, or their email address when they have none. |
${SM.USER.LOGIN} | The requester's email address. Sign-in here is by email and there is no separate login name, so the two are the same value. |
${SM.USER.COMMENTS} | The empty string. Nothing on a user record holds free-text notes for it to read. |
Any name beginning SM. is treated as a system variable, never as an input — so no input is
auto-created for one, and an input you happen to name SM.Something can never be reached from a
template. A name under that prefix which is not one of the four above is refused at submit, with
a message listing the four, rather than being replaced with nothing — which would name a job or set
a property with an empty value.
${SM.USER.COMMENTS} resolving to nothing is a value, not a failure — it substitutes as empty.
${SM.USER.EMAIL} and ${SM.USER.LOGIN} are refused if the requester has no email address on
record.
When a placeholder cannot be resolved
Every placeholder must resolve, or the submission is refused — it is never replaced with blank
and never sent as literal text. A $PROPERTY:SET event that shipped the characters ${TargetPath}
as the property's value would be worse than an error.
The submission is also refused when:
| Situation | Why |
|---|---|
| A placeholder names no input on this request | Submitting would send the placeholder text as the value. |
| A required input was left empty | |
| A resolved value contains a comma | An event template separates its fields with commas and cannot escape one, so a comma would shift every later field. This applies to a system variable too: a display name like Dimick, Ryan is refused. The exception is the event's last field when it takes the rest of the line — tags, or the Message of $CONSOLE:DISPLAY — where an input's commas are kept. A system variable is refused even there: in tags, which splits on commas and semicolons, a display name holding either would become several tags; in the message, the Message field takes a comma only as typed text. |
| A Text Collection value's delimiter would not survive the target field's own separator | See Fields that need a specific delimiter. |
A resolved value reads an encrypted property, or still contains a [[ or {{ after resolving | A requester's input must not be a route to a secret, and a token that survives resolution here would be expanded later under the platform's own trust rather than the requester's. |
The built event line carries more [[…]] / {{…}} tokens than the template wrote | See A token the author did not write. |
A suffixed date token such as [[$DATE_EU]] lands in a field read as a date | Those fields render in the built-in format, so a suffixed name has no format to use. See Date and time tokens. |
A token the author did not write
A requester's input is substituted into the template, and a value can assemble a token the author
never wrote — by supplying the [ that completes an opener, or by two adjacent placeholders each
contributing half of one. Text formatting on the input can do it too: Strip Characters turning
[ [OI.RATE]] into [[OI.RATE]], or left-padding a value with [.
Each built line's token openers are therefore counted against what its own template wrote. A line
with more is refused. Nobody authored that token, so nothing has decided it may be read — and
the author's own tokens are unaffected, including a template that deliberately builds one around an
input, as [[OI.${Region}]] does.
Property tokens are a separate mechanism
${…} is the portal's own substitution and it happens at submit, from the form. An event
parameter can also carry a [[…]] property token, and that is
resolved later — by the platform, when the event is carried out. The two do not compete: use
${…} for what the requester types and [[…]] for what the tenant already knows.
$JOB:ADD,[[$DATE]],DAILY,${Job Name}
Earlier builds carried a service request's [[…]] tokens through as literal text, so the line above
was refused for an invalid date. Both now resolve.
A token whose value carries a time of day works in a date field too: $JOB:ADD,[[$NOW]],DAILY,${Job Name}
uses the date [[$NOW]] renders, because an event's schedule date takes the date and ignores the
time after it.
Earlier builds saved such a button and then refused it on submit with field 'scheduleDate' has an
invalid date. See
A date field accepts a date with a time of day.
The rules for the [[…]] half are the platform's, not the portal's, and they are strict: a
token that does not resolve fails that event rather than leaving the text in place, and only
global properties and the clock are in scope — a submitted event has no job for a JI, SI or
MI token to read. See An event raised from outside a
job.
A Password input is the requester's secret, handled by the redaction rules
on the Events tab. An encrypted property is the tenant's, and a
[[…]] token naming one may appear only as the value of $PROPERTY:SET / $PROPERTY:ADD,
written as a single bare reference, into a target that is itself encrypted. Anywhere else the event
is refused.
Editing an event imported from Classic
A button brought over from Classic stores its event as a type plus a raw template, with no structured fields behind it. Opening it in Edit Event fills the form by decoding that template.
Two limits are worth knowing:
- The template is decoded only when the event type it starts with is one the form knows.
- A template with values past the last field the form defines is not decoded either.
In both cases the form opens empty with a message, and you re-enter the event in the form. Nothing changes until you save.
Until you edit it, such an event fires exactly the template it was imported with — see The requester's values are checked field by field.
An event whose type the platform knows but will never fire — one that is not supported, or not
built yet — is flagged with a warning rather than refused, on every save. There is nothing you
could change to make it fire, and it is inert either way, so refusing it would only block saving a
button you did not author. An event whose type the platform does not recognise at all is still
refused, and so is one of the types only an agent raises — $JOB:TRACK, $JOB:QUEUED and
$JOB:QUESTATE.
Deployments and Transformations
Deployments
Like workflows, a service request is deployed to an environment with a version strategy:
| Field | Notes |
|---|---|
| Target Environment | The environment the service request is deployed to. |
| Version | Latest, or a committed version (Version N, newest first) to pin the deployment to. |
| Pinned version | The version a Pinned deployment runs, chosen in Version. |
| Effective Date / Expiration Date | Optional active window. |
Active (isActive) | Whether the deployment is active. The deploy dialog has no field for it. |
A Pinned deployment must name a version the service request has. Self Service does not show a deployment pinned to a version that does not exist, so saving one is refused with a message naming the versions there are, such as available versions are 1-5. Through the API the same check is made when an inactive deployment is made active again, and when a deployment is rolled back to an earlier entry that is active and Pinned; and the pinned version, like the version a rollback names, must be a whole number from 1 to 2147483647.
A deployment that already names a missing version, such as one saved before these checks, shows a warning on its card: Version 7 does not exist, so this button is hidden in Self Service. Edit the deployment and choose a version from 1 to 5. Edit it and pick a version that exists.
Transformations
A transformation rule overrides a value in the request for a specific environment or deployment — e.g. swap a dev value for a production value so the same request behaves correctly in each environment. Rules are applied when the portal serves the request. The deployment dialog authors every rule as a replace; other transform types are available only through the API.
A rule must not change the request's events. A request whose events a rule has changed cannot be submitted in that environment: the portal refuses it with "This service request's events were changed by a transformation rule in this environment, so it cannot be submitted. Ask an administrator to remove the rule."
Rules on a service-request deployment are listed, added, edited, and removed in the deployment dialog, which lists every rule the deployment has, however many. Earlier builds listed only the first 100.
Rules are edited in place, in rows, and saved with the deployment. Adding a rule adds a row to the deployment dialog rather than opening a second dialog on top of it. Nothing is written until you save the deployment, and the save applies your additions, edits and deletions together.
Each row asks for:
| Field | Required | Notes |
|---|---|---|
| Name | Yes | Unique within your tenant. |
| Target Path | Yes | The value to override, as a JSONPath — it must begin with $ or .. |
| Replacement Value | Yes | What to put there. |
| Description | No |
A row that is missing any of the required fields, or whose target path isn't shaped like a path,
stops Save for the whole deployment until you fix or remove it. So does a target path whose
filter can never match — a quoted value or regex holding a line break, )] or )', an @
followed by a space, ., ), [ or one of root, parent, property, path, or a type check
such as @string(); a single-quoted value that starts with (, or ends with ) anywhere but at the end of the filter; a missing closing
quote or /; or a filter written as [?@…] — with the same messages as an
Advanced transformation rule. The platform
checks the same filters, and the path's syntax, when the rule is saved. A row you have not edited
since it was loaded is not checked; a saved path that can never match shows a warning under the
row instead, and does not stop Save.
A new row starts blank, and its errors show only after you have edited a field and moved on, or once you select Save. Save stays available: selecting it with an incomplete row shows every error, with A transformation rule has an invalid field. Fix it, or remove the rule., and saves nothing. Earlier builds disabled Save and showed a new row's errors from the moment it was added.
One transform type doesn't apply here. RENAME_KEY is refused on a service-request deployment,
because a request's configuration has no job structure for a key rename to act on. A rule belongs to
one deployment, so a rule can't be reached or edited through a different deployment's dialog.
A deployment that has been deleted reports that specifically rather than as a generic not-found — so a dialog that can't load its rules tells you whether the deployment is gone or the identifier is simply wrong.
- Workflow Selection and Job Selection offer a real picker; Workflow Instance and Job Instance selection are not offered and render as text fields. A picker also falls back to a text field when the requester cannot read the list behind it — see When a picker falls back to free text.
- Hidden and Disabled are acted on by the portal and checked again when a submission arrives: a hidden button is not in the catalog and a disabled one cannot be submitted. A rule that cannot be evaluated fails open — see Hidden and disabled.
- A request not appearing in an environment usually means it isn't deployed there, or its deployment is inactive or outside its effective window — check the deployment, as with workflows.
- Collect a secret the requester supplies with a Password input: every field it fills is
redacted in the copy of the event the platform stores. An encrypted property can be used in an
event only as the value of
$PROPERTY:SET/$PROPERTY:ADD.
Related topics