Configure an application
Every ITSM application has a Setup entry under its Configuration section; it is the only entry there. Asset Management and Agile have Setup in their own menu. It opens the setup of that application only, laid out as the stages of its process. Categories, the priority matrix and Change’s SLA policies are reached from their stages. Settings that belong to the whole organization, such as business hours and the identity connection, are on Organization setup.
Goal
Read the setup of one application, see which stage needs attention, choose the teams that work on it, and change who is told about what without leaving the page.
Prerequisites
- The application is installed at Incident Management 1.9.2, Request Management 1.3.2 or Change Management 1.2.2, or later. Who approves needs Request Management 1.4.1 or Change Management 1.2.5. Automations needs Incident Management 1.11.0, Request Management 1.5.0 or Change Management 1.3.0. Asset Management 1.3.0 and Agile 1.4.0 have a Setup page with the Team, Targets and Assistant stages. On an earlier version the page says so and offers Update the application.
- A role that shows you the application’s Configuration section. A tenant administrator sees every installed application. Which role shows which section, and who can change which stage, is in Roles: who sees what, who configures what.
- To change a stage you need the permission its settings require. Without it the stage shows its state and a line naming who can change it: the application’s admin role for Intake and Automations, a tenant administrator or a Configurator holding the stage’s capability area for the rest.
| Stage | Permission to change it |
|---|---|
| Intake | platform.catalog.write for catalog items, the update grant on the categories table for categories |
| Approval | The update grant on approval policies, platform.iam.write for who holds the approver role |
| Team | platform.iam.write |
| Targets | platform.servicedef.write |
| Updates | platform.notifications.write |
| Automations | platform.rules.write |
| Assistant | platform.tables.write |
Steps
1. Open the page
Open the application, then Configuration → Setup. The address names the application, for example /setup?app=request_management. Add the name of a stage to open on it, for example /setup?app=request_management#updates.
One page, one Save
The sections of the application are listed on the left (a check means set, an amber dot means it needs a decision, a hollow dot means off). Each section says in one line what it does, shows its settings in place, and ends with a grey line that says what the settings mean, for example “A critical record must be answered within 15 minutes and solved within 4 hours of working time.”
- Changing a value is not saved at once. Switches, choices, numbers, times, notes and who is told are collected: the section and its entry on the left say Unsaved, and a bar at the bottom names the changed sections. Select Save changes to write them all, or Discard to put every control back. Leaving the page with unsaved changes asks first.
- Adding or removing something is saved at once: a team, a member, a category, an approver, an approval rule or a category rule. Those buttons say what they do.
- If a change cannot be saved (for example you lack the permission), it stays unsaved and its section says why; the other changes are saved.
2. Read the stages
The row of stages at the top is the summary. Each stage shows its state and one measure. The line beside the title counts the stages that are set out of the stages in use.
| Stage | What it covers | Measure |
|---|---|---|
| Intake | What people can ask for, and how it is sorted | Active categories, or the items offered when the application has no categories |
| Approval | Who agrees before work starts | Active approval rules on the application’s tables |
| Team | Who does the work, and where new work goes | Teams working on the application |
| Targets | How fast work is answered and finished | Priorities with the application’s own target |
| Updates | Who is told, and when | Updates switched on, out of all updates |
| Automations | What the application does by itself | Automations switched on, out of all automations |
| Assistant | What the assistant may do | On or Off |
An application shows the stages of its own process. Incident Management has no Approval stage, because incidents are not approved.
A stage reads Set, Needs attention, Off or Not measured. Off means the stage is not in use and is left out of the count. Not measured means the fact could not be read, and the page says why.
3. Decide what people can ask for
Open the Intake stage.
- Categories lists the application’s categories, by name. Use the search box above the list to find one on a long list. To add one, type its name under the list and select Add category. To rename one, select the pencil beside its name. To stop offering one, switch it off; switch it on again to bring it back. A category is never deleted from here.
- Catalog items lists what the portal offers for the application. Switch an item off to take it out of the portal. Select Open to change an item in the catalog item builder, or New item to build one; Save and Cancel in the builder bring you back to this page.
- Incident Management also shows its Priority matrix: for each impact and urgency, the priority a new incident gets. Choose another priority to change it.
Each change saves by itself.
4. Decide who approves
Open the Approval stage. Incident Management has no Approval stage.
A lead sentence explains the whole card: requests that need approval wait for one person who holds the application’s approver role (for example Request Manager); you choose who that is, then choose which requests need it. The two parts below answer each half.
- Who approves names the approver role of the application, for example Request Manager for Request Management and CAB Member for Change Management, and who holds it. Add a team or a person to give them the role; select the cross on a name to take it away. The members of a team that holds the role approve too. An administrator role is never offered here, and the person picker offers only people, never an agent’s service account.
- Which requests need approval reads each rule as a sentence, for example “When a request is created or updated and State is Pending Approval and Request Type is Access, ask Request Manager to approve.” Rules marked Shipped come with the application and cannot be changed or switched off.
- To add your own rule, select Add a rule, give it a name, choose a field and a value it applies to (or Always), and choose a role or a team to ask. Select Save rule. Your rules can be edited, switched off and removed. A rule that already has approvals on record cannot be removed; switch it off instead.
- An own rule the page cannot put in one sentence shows its name with Custom rule and Open. A shipped rule the page cannot put in one sentence shows its own description of what it approves instead.
5. Choose the teams that work on the application
Open the Team stage. It lists the teams that work on the application, each with its members. A team works on an application when it holds the application’s working role, for example Request Fulfiller for Request Management, so its members can open the application.
Installing an application already gives it a team. Your organization’s desk team (the fallback team set on Organization setup, or a new team named Service Desk when there is none yet) receives the application’s working role, and becomes the default team of every one of the application’s work tables that has none, not only its main one. This happens whether the application is installed before or after your first Setup run, on an update applied through Update, and on every release, so a tenant that has not opened Setup in a while still receives it. Installing again, or a later release, changes nothing that is already set. When the stage says Table … has no default team, choose one under Choose where new work goes. Anyone who holds the application’s own admin role from installing it can also be assigned its work, even before they are added to a team.
- To add a team, select New team, enter a name, choose its members and select Create team. The team is created with the working role in one step.
- To add a team you already have, select Add an existing team and choose it.
- To change a team, select Edit. You can rename it, add a member, or remove a member with the cross on their name.
- To stop a team working on the application, select Remove next to the team and confirm. The team and its members stay; only the application’s roles are taken from the team. Remove is refused, with the reason, while the team is the application’s default team or the team of a category rule; change that first.
A team with no members reads Needs attention.
6. Choose where new work goes
Below the teams, the Team stage says the order new work is routed in: the category’s own team first, then the application’s default team, then the organization’s fallback team.
- New requests go to (or New incidents go to) sets the application’s default team. It takes new work that nothing more specific routes. Choose The organization’s fallback team to use the team set on Organization setup instead.
- By category lists only the categories routed to a team other than the default, each with Remove, which clears the rule (the category then goes to the default team again). The sentence under the list names the default team that every other category goes to. To route a category away from the default, use Add a category rule: choose the category and the team, then Add.
If this application has categories with nothing set in their own default team field, a Setup finding names it: “N of <application>‘s categories route to no team.” A category this finding names still routes somewhere today, through the default team and then the organization’s fallback team; the finding exists so you choose the routing on purpose instead of discovering it the first time a request lands on the fallback team.
Both pickers offer only the teams that work on the application; the default team is never offered again in Add a category rule, since naming it there would mean the same as no rule. A new record is routed in this order: the service offering, the service, the configuration item, the category, the default team, then the organization’s fallback team. A step whose team does not work on the application is skipped. If nothing is left, the record is created without a team, and the stage says so.
7. Who a record can be assigned to
A record’s assignment group must be a team that works on the application. With a group set, the assignee must be a member of that group. With no group, the assignee must be someone who can work on the application, directly or through a team. The pickers on the record offer only those, and a save that names anyone else is refused with the reason. Records assigned before this rule are not changed; the rule applies when the group or the assignee changes.
8. Change who is told
Open the Updates stage. Every notification rule on the application’s tables reads as one sentence, for example “When a request becomes Closed, tell Requested for”.
- To change who is told, choose from the list in the sentence. On the record lists the people and the team named on the record itself, such as the assignee or the assigned team. Teams lists the teams that work on the application. An update that already tells another team keeps it.
- To change how they are told, select or clear In app and Email. An update keeps at least one.
- To stop an update, switch it off. It stays on the page so you can switch it back on.
Each change saves by itself. A rule whose conditions the page cannot put in words shows its own name with the label Custom rule, its channels and its switch. Select Open to see the full rule.
9. Set the application’s targets
Open the Targets stage. It lists the four priorities with their first response and resolution times. A Source column (Own, this application’s target, or Shared, the organization’s targets) shows only when the priorities actually differ; when all four come from the same place, a sentence above the table says so instead.
- To give the application its own targets, select Set targets for the application, change the times and select Save. The four priorities are saved together.
- To change them later, select Edit targets.
- To go back to the organization’s targets, select Use shared targets. The application’s own targets are removed.
A new record takes its due dates from its priority: the application’s own target first, then the shared one. A service offering that names its own SLA still wins over both. Records created before a change keep their due dates.
Change Management also lists its approval and change windows per change type. They are shown here for reference; select Open beside them to change them in Change SLA Policies.
10. Choose what the application does by itself
Open the Automations stage. Each setting reads as one sentence with a switch, for example “Ask for resolution notes before an incident is resolved.” Most of these switches turn one of the application’s business rules on or off; a few, like that example, instead ask for a field (a note, a reason, a code) before a record can move to a particular status, with no business rule behind them.
- To stop a setting, switch it off. It stays on the page so you can switch it back on. A setting you switch off stays off when the application is updated.
- Where a rule reads a number, the number is in the sentence. Change it and select Save. For example, Incident Management links a new incident to an open one with the same subject from the last 7 days; the number of days is yours to choose, from 1 to 365.
Each switch saves by itself. The page shows only the sentence, never the rule’s script. Workflows are not on this stage. Rules you wrote yourself are in the business rules list.
11. Decide what the assistant may do
Open the Assistant stage. For each of the application’s tables:
- Switch the assistant on or off for it.
- Who approves changes the assistant suggests (with a tooltip explaining what this reviews) chooses the record’s assignee (or its team when nobody is assigned), or one team for every record.
- Write the note the assistant is given in every session on the table, and select Save note. Only a role that may manage the assistant’s notes sees and changes the note.
Each control saves by itself and changes only its own setting. Select Open beside the model line to see or change the model the assistant uses.
12. First visit: use recommended settings
While the Team or Targets stage needs attention, the page offers Use recommended settings. It fills only what is missing for this application: when no team works on it, or it has no default team, your desk team is given the application’s working role and becomes its default team; when a priority has no target, the shared targets and business hours are created. When nobody holds the application’s approver role, it names the role so you can choose who approves; it never grants that role itself. It never changes what is already set, and it says “Nothing was missing.” when there was nothing to fill.
Verification
You know it worked when:
- The page shows Saved after a change.
- The Updates measure changes, for example from “3 of 3 on” to “2 of 3 on” after you switch one off. The Automations measure does the same.
- The change is still there after you reload the page.
- A member of a team that works on the application sees it in their sidebar.
- A new request with only a category is assigned to that category’s team; one with a category that names no team goes to the default team.
- A new request with priority Critical is due at the application’s own Critical target when it has one.
- A new request that matches your own approval rule waits for an approval from the people who hold the role you chose.
Troubleshooting
| Symptom | Cause | Fix |
|---|---|---|
| ”This application’s setup is not available to you.” | The application is not installed, or your role does not show you its Configuration section | Ask a tenant administrator for a role on the application |
| Categories or Priority Matrix is gone from the menu | Since Incident 1.12.0, Request 1.6.0 and Change 1.4.0 the Configuration section keeps only Setup | Use the Intake stage, or Open on Change’s windows |
| ”This version of the application has no setup page yet.” | The installed version is older than the versions under Prerequisites | Select Update the application and update it in the Marketplace |
| The controls of a stage are disabled | Your role lacks the permission the stage requires | Ask a tenant administrator to make the change, or to give you the Configurator base role with the Service desk preset (see Roles) |
| “Could not load the choices for who is told.” | The fields of the table or the list of teams could not be read | Reload the page. The controls stay disabled until the choices load, so a change is never saved against an empty list |
| ”A team with this name exists.” | Another team already has that name | Choose another name, or add the existing team with Add an existing team |
| ”The role of this application could not be found.” | The installed version does not carry the working role the page grants | Update the application in the Marketplace |
| ”This rule ships with the application and cannot be changed.” | You tried to change or switch off a Shipped approval rule | Add your own rule beside it; the shipped rule stays as it is |
| ”Nobody holds Request Manager, so rules that ask it wait for no one.” | No team or person holds the approver role | Add a team or a person under Who approves |
| ”Nobody can approve …” | An approval rule that is on resolves to nobody | Give the rule’s role or team a member, or change who the rule asks |
| ”Table … has no default team” | The application’s record table has no default team | Choose one under Choose where new work goes |
| Two updates read the same | Two rules with the same trigger and recipient exist on the table | Switch one off |
| ”That group does not work on this application.” | The default team you chose does not hold the application’s working role | Add the team to the application first, then choose it |
| ”The assignment group is not a team of …” on a record | The group does not work on the application | Choose one of the application’s teams, or add the group to the application on its Setup page |
| ”The assignee is not a member of the assignment group.” | A group is set and the person is not in it | Choose a member of the group, add the person to the team, or clear the group |
| ”Resolution cannot be due before the first response.” | A resolution time is shorter than its response time | Make the resolution time at least as long as the first response |
| A priority reads No target | Neither the application nor the organization has a target for it | Set the application’s own targets, or set the shared targets on Organization setup |
| New work stays without a team | No default team is set and the organization’s fallback team does not work on the application | Set a default team on the Team stage |
Related
- Roles: who sees what, who configures what: which role changes which stage.
- Refine your service desk setup: teams, targets and business hours in detail.
- Work incidents, Work service requests, Work changes: the working surface of each application.
- SLA: how a target stamps a record’s due dates.