Skip to main content

Create a service request

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.

What this solves

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.
  • 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 Order Buttons in Category — see Arranging the portal page.

Set up the request​

To create a service request, complete the following steps:

  1. 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.

  2. 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.

  3. Add inputs: for each, set the 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.

  4. Add events: 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.

    The event form also lists four system variables as chips. 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 other SM.-prefixed name is refused when the request is submitted.

    A text collection needs the right delimiter for the field it fills

    A 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:

    • tags needs a comma, dates and properties need a semicolon — these fields hold several values in one slot and are split back apart on that exact character.
    • Any other field: leave the colon, and pick something else only if your values could contain one. Times, Windows paths and host:port values 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 in

    Each 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.

  5. Add documentation and a confirmation message if helpful.

  6. Save (this creates a version — you can give even the first one a change description), then deploy it to an environment.

Deploy it​

Deploy the request to each environment where it should be available, choosing Latest or a Pinned version (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. 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.

Good to know
  • 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 Copy and Delete, and selecting rows enables a bulk delete. Selecting the row itself opens the button for editing.
  • 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 refused rather than compared 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. Until somebody arranges the page, buttons within a section are ordered by name; after that they follow the order saved on Order Buttons in Category, which is presentation only and needs no redeploy. 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. Leave the input optional and it also gets a clear control, so a requester can empty it again after picking something. Worth knowing when you write the input's help text: the search box is a real text field, so a requester who types over an option they already picked sees their own text while the request still submits the picked option — see Choice.
  • Use a password input plus a connection/property for secrets. Don't collect credentials in a plain field.
  • A request only appears in the portal where it's deployed and active.
  • 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.
  • Transformation rules on a service-request deployment are listed and edited in the deployment dialog. Earlier builds had two problems here that are now fixed: the list failed to load ("Failed to load deployment rules."), and adding or editing a rule left the page unresponsive so the change couldn't be completed. If you hit either, retry on a current build.
  • A button imported from Classic works properly now. Two things used to break it. Its variable names have spaces in them (${Start or Stop}), which weren't detected — and because an input no event references is removed, opening the button deleted all of its inputs. And Edit Event showed every field blank, so the first edit rewrote a correct template from those blanks. Both are fixed. A button whose inputs went missing on an earlier build needs them added back once.
  • 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