Create a service request
- Synopsis
- Full Details
In briefA service request is a button on the self-service portal that runs automation for a business user. You build it under Design › Self Service Config: its inputs, and the events that run, in order, when someone submits it. Then you deploy it to each environment where it should appear, the same way as a workflow.
- Writing a
${…}placeholder in an event creates its input, and an input no event references is removed. - The events run one after another, with the requester's permissions. One failing does not stop the rest.
- Filing a button in a category, or arranging the portal page, needs no redeploy.
- A text collection's delimiter must suit the event field it fills, or the submission is refused.
- A comma in a submitted value is refused, including in a system variable such as
${SM.USER.NAME}. - A requester missing any permission the events need has the whole submission refused, and nothing is sent.
A service request lets a business user trigger automation from a simple form. No workflow knowledge is needed. You design the form fields and the events that fire when it's submitted, then deploy it to an environment so it appears in the self-service portal.
Business users need routine automation run for them, but giving them workflow access is risky and running every request by hand is slow and interrupt-driven for the automation team.
What you'll set up
- Inputs: the fields the user fills in (text, password, number, date, a choice field, or a text collection — a list of entries the user adds one at a time), each optionally required and validated.
- Events: what happens on submit. Event parameters can include the user's answers using
${Field Name}placeholders, and facts about the requester using${SM.USER.EMAIL}and its siblings. - Documentation and a Confirmation Message to guide the user: the documentation is shown at the top of the request form under Notes, and the confirmation message as a note above the form's fields.
- Tags for organizing and for filtering in the portal.
- A category to file the button in, so a set of buttons a user works through as one task stays together. The portal groups by category, so this is what the requester's page is arranged into; buttons you leave uncategorised are gathered into a General section at the end. Where the sections sit, what colour each one is and how the buttons inside them are ordered are set separately, on Organize Self-Service Buttons, where a button can also be dragged into another category — see Arranging the portal page.
Set up the request
To create a service request, complete the following steps:
-
Go to Design → Self Service Config and select New Self Service Button, then give it a name. Everything below happens in the one dialog that opens.
-
Choose a category, a workspace and any tags. The category picker searches what already exists and offers New Category for a name it doesn't find, so you can create one without leaving the button.
-
Add events: select Add New Event, choose the event type and fill in its parameters, using
${Field Name}to pass the user's answers. The name is any text without a brace, so${Resource Group Name}is fine. Writing a placeholder is what creates the input — the dialog adds a required text input for any${…}it doesn't already have, and removes an input no event references.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. What the button stores is these parameters, and the command line is derived from them — which is what lets each requester value be authorized and checked as the field it actually fills. See The requester's values are checked field by field.
The event form also offers four system variables as inserts. Those fill in from whoever submits the request rather than from the form:
${SM.USER.EMAIL},${SM.USER.NAME},${SM.USER.LOGIN}(the email again — sign-in is by email) and${SM.USER.COMMENTS}(always empty). Any otherSM.-prefixed name is refused when the request is submitted.A text collection needs the right delimiter for the field it fillsA text collection joins its entries into one string, using a colon (
:) unless you change it. Match it to the event field the input fills, or the requester's submission is refused:tagsneeds a comma or a semicolon,datesandpropertiesneed a semicolon — these fields hold several values in one slot and are split back apart on that character.- Any other field: leave the colon, and pick something else only if your values could contain
one. Times, Windows paths and
host:portvalues all do. - Don't use a comma unless the input fills the event's last field. An event separates its own fields with commas and can't escape one, so a comma-joined list arrives as several fields.
Full rules, including what happens to a list stored under the old comma default, are in Service requests.
The events run in the order you put them inEach event finishes before the next one starts, so you can chain them — set a property, then add a job that reads it. Earlier builds ran a request's events several at a time, which made a chain like that unreliable; arranging them is now the whole contract. One event failing does not stop the rest, so don't rely on a failure part-way through holding the others back. See The events run in the order you arranged them.
-
Set up the inputs under User Inputs. You don't add them yourself — each
${…}placeholder in an event adds one — so edit each to set its type, whether it's required, and any validation.- A Workflow Selection or Job Selection input gives the requester a picker rather than a text box. Job Selection needs you to choose the workflow its jobs come from.
- A Date input can be bounded by today rather than a fixed date — Minimum is today and Maximum is today.
- Give an input a starting value with its Default Value (Default Date, Default Choice, Default Entries, Default Workflow or Default Job, by type). The editor won't save a default requesters couldn't submit: one the input's own rules refuse, or one holding a comma where an event places the input in a field that can't carry one. Saving the button checks the same, and Copy leaves such a default out. See Default values.
-
Add Documentation and a Confirmation Message if helpful.
-
Save, then deploy it to an environment. Each save creates a version. The first save asks nothing and its version is labelled Initial version; each later save offers an optional change description.
Deploy it
Deploy the request to each environment where it should be available, choosing Latest or a specific Version to pin it to (and optional effective/expiration dates), the same model as workflows. Use a transformation to override a value per environment (for example, point a request at the production system in PROD).
Transformation rules are added as rows in the deployment dialog itself. Each needs a name, a
Target Path (a JSONPath beginning with $ or .) and a Replacement Value; a description is
optional. The dialog authors every rule as a replacement. A rule must not change the request's
events: a request whose events a rule has changed cannot be submitted in that environment. Add, change, and remove rows as you like — nothing is written until you save the
deployment, and an incomplete row blocks the save until you fix or remove it.
- Today's input types are text, password, number, date, choice, text collection, workflow selection and job selection. Workflow-instance and job-instance selection are not offered.
- A picker falls back to a plain text box for a requester who isn't allowed to read workflows, so don't rely on it to constrain what they can enter.
- Placeholder and help text are no longer editable on an input. Anything already stored still renders on the form; use documentation for guidance on new ones.
- A button's row menu on the grid holds Edit, Copy and Delete, and selecting rows enables a bulk delete. Edit opens the button for editing, as selecting the row itself does; without edit permission in its workspace, it opens read-only.
- Hidden and Disabled are rules the portal acts on. Each is a switch with an expression
field: switch it on and type a condition over the tenant's global properties —
[[MAINTENANCE_WINDOW]] == "true"— or leave the switch off. Test beside the field runs the rule and reports True, False, or why it couldn't be evaluated, without saving anything. A hidden button is dropped from the portal catalog entirely; a disabled one is shown but can't be submitted; a rule that can't be evaluated fails open, except an over-budget Disable rule, which refuses the submission. Keep a rule's work small. Only global properties and the clock are in scope — a rule has no job, schedule or agent to read — and a rule naming an encrypted property is an error that can't be evaluated, never a comparison against the secret. See Hidden and disabled. - Filing a button in a category, or renaming a category, needs no redeploy: a category isn't part of the versioned configuration. Deleting a category leaves its buttons alone; they just become uncategorised. A category with no visible button draws no section in the portal, so a category whose every button is hidden by a rule simply isn't there.
- Where your button lands in its section is not part of the button. A new button is placed after the buttons already in its section, and the order is then whatever is saved on Organize Self-Service Buttons, which is presentation only and needs no redeploy. Buttons that share a position, as those created by earlier builds do until somebody arranges the page, are ordered by name. Arranging it needs permission to edit categories, which is tenant-wide — so if the toolbar button is disabled for you, that is the reason.
- An event parameter can carry a
[[…]]property token as well as your${…}inputs, and it is resolved when the event is carried out — so$JOB:ADD,[[$DATE]],DAILY,${Job Name}works. The[[…]]half is strict: it reaches global properties and the clock only, and a token that doesn't resolve fails that event rather than being sent as text. See Property tokens are a separate mechanism. - A choice input is searchable on the form, so a long option list is fine — the requester types to narrow it, then picks an option. Typing alone does not choose one. Leave the input optional and it also gets a clear control, so a requester can empty it again after picking something — see Choice.
- Collect a secret the requester supplies with a password input, not a text 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:SETor$PROPERTY:ADD. - A request only appears in the portal where it's deployed, its deployment is active and within its effective window, and no Hidden rule removes it — and only to requesters whose roles grant Self Service Portal View in its workspace, in that environment.
- The events run with the requester's permissions, not yours. A requester needs Self Service Portal Execute in the button's workspace and environment, the permission each event type requires in the workspace of the object it names, and Properties View for every property the events name. Missing any one refuses the whole submission with permission.denied and nothing is sent, so check your requesters' roles against the button's events before you deploy it. See What a requester needs permission for.
- A button imported from Classic keeps its inputs, even when its variable names have spaces in
them (
${Start or Stop}), and Edit Event fills the form by decoding the event's stored template. If the template names an event type the form doesn't know, or carries values past the last field the form defines, the form opens empty with a message instead: re-enter the event in the form. Nothing changes until you save. - A comma in a value is refused, including a resolved one — a display name like Dimick, Ryan
reaching
${SM.USER.NAME}is rejected, because an event separates its fields on commas and cannot escape one.
Related topics
- Service requests — full configuration reference and troubleshooting
- Submit a service request (Business User)
- Version and deploy a workflow (Builder)