ChatOps commands and scenarios

After you deploy ChatOps, you can enter commands in a Slack channel to handle incidents and collaborate with other team members.

Before you begin

Ensure that you complete the configurations in Configuring ChatOps.

How to chat

Create a channel in Slack. In the Channels section, click + and select Create a channel. In the Create a channel page, enter a name and description, and click Create.
Open the channel that you create, and click Add an app. In the search field, enter the hubot name that you specify during installation. Click Add to add hubot to your channel. Then, you can run commands and collaborate with your team members in the slack channel.
To get all commands and their descriptions, enter @<hubot-name> help. Remember to start a command with @<hubot-name>. Replace <hubot-name> with the hubot name that you use.

Notes: Commands with the prefix mon are related to IBM Cloud Pak® for Multicloud Management. Commands with the prefix pd are related to PagerDuty. Commands with the prefix pack are related to the built-in technology that ChatOps uses. You can ignore those commands with the prefix pack. For detailed command descriptions, see Table 1. ChatOps commands for integration with IBM Cloud Pak® for Multicloud Management incidents, and Table 2. ChatOps commands for integration with PagerDuty.
You can provide more keywords in the command to limit the returned result. For example,
```
@<hubot-name> help mon
@<hubot-name> help pd
@<hubot-name> help find
```
Note: To improve user experience, a maximum of 25 results can be returned for each command.
Run a specific command in Slack as you need.

Important: Ensure that each command is in plain text format. A command in bold can't be run successfully in Slack.

IBM Cloud Pak® for Multicloud Management scenarios

To know whether there are non-closed IBM Cloud Pak® for Multicloud Management incidents with priority 1 or priority 2 for you, run the command:
```
@<hubot-name> mon find major incidents
```
Note: Replace <hubot-name> with the hubot name that you use.
To get more information about a IBM Cloud Pak® for Multicloud Management incident, run the command:
```
@<hubot-name> mon get incident <incident_id>
```
where <incident_id> is the unique identifier of an incident.

There are many ways to get the <incident_id>. For example,
- run @<hubot-name> mon find major incidents.
- check the Slack channel history for incidents that are retrieved by others.
- check My incidents page on IBM Cloud Pak® console. For more information, see Managing your incidents.
To get all the events that are related to a IBM Cloud Pak® for Multicloud Management incident, run the command:
```
@<hubot-name> mon get events for incident <incident_id>
```
To get the history of a IBM Cloud Pak® for Multicloud Management incident, run the command:
```
@<hubot-name> mon get timeline <incident_id>
```
To set a IBM Cloud Pak® for Multicloud Management incident as resolved, run the command.
```
@<hubot-name> mon resolve incident <incident_id>
```
To get all IBM Cloud Pak® for Multicloud Management users, run the command:
```
@<hubot-name> mon list users
```

PagerDuty scenarios

To get more information about a team, run the command:
```
@<hubot-name> pd find team <query>
```
where <query> is a substring of the team name or email address.

For example, if you run the following command, you can get the teams which name contains SRE console.
```
@<hubot-name> pd find team SRE console
```
Note: Replace <hubot-name> with the hubot name that you use.
To get more information about a user, run the command:
```
@<hubot-name> pd find user <query>
```
where <query> is a substring of the username or email address.

For example, if you run the following command, you can get the users which name contains SRE.
```
@<hubot-name> pd find user SRE
```
To know whether there are PagerDuty incidents with high urgency for teams or users, run the command:
```
@<hubot-name> pd find major incidents for <team¦user> <team_id¦user_id>[,<team_id¦user_id>]
```
where <user_id> is the unique identifier of a user and <team_id> is the unique identifier of a team. You can get the <user_id> and <team_id> from step 1 and step 2.

For example, if you run the following command, you can get PagerDuty incidents with high urgency for user01 and user02.
```
@<hubot-name> pd find major incidents for user user01, user02
```
To get more information about a PagerDuty incident, run the command:
```
@<hubot-name> pd get incident <incident_id>
```
Note: <incident_id> is the unique identifier of an incident. You can get the <incident_id> from the last step.
To acknowledge a PagerDuty incident, run the command:
```
@<hubot-name> pd acknowledge incident <incident_id> from <user_email>
```
Note: <user_email> is your email address.

To resolve a PagerDuty incident, run the command:

@<hubot-name> pd resolve incident <incident_id> from <user_email>

To create a note for a PagerDuty incident, run the command:

@<hubot-name> pd create note for incident <incident_id> from <user_email> with content <content>

To get the escalation policy for a team, run the command:
```
@<hubot-name> pd find escalation for team <team_id>
```
To get the on-call information for an escalation, run the command:
```
@<hubot-name> pd find oncall for escalation policy <escalation_policy_id>
```
Note: <escalation_policy_id> is the unique identifier of an escalation policy. You can get the <escalation_policy_id> from the last step.

Table 1. ChatOps commands for integration with IBM Cloud Pak® for Multicloud Management incidents
Command	Description
mon find major incidents	Return a list of non-closed incidents with priority 1 or priority 2. The incidents that are created in the last 7 days can be retrieved.
mon find major unassigned incidents	Return a list of unassigned incidents with priority 1 or priority 2. The incidents that are created in the last 7 days can be retrieved.
mon find incidents "owner == '<name>'"	Return a list of non-closed incidents for a specific owner. The incidents that are created in the last 7 days can be retrieved. If a IBM Cloud Pak® for Multicloud Management incident is assigned to a user, the user is the incident owner. Command example: @<hubot-name> mon find incidents "owner == 'Lisa'"
mon find all incidents filter by <query string>	Return a list of incidents filtered by a query string. The incidents that are created in the last 7 days can be retrieved. See Table 3. Supported filtering attributes and operators. Command example: @<hubot-name> mon find all incidents filter by "lastChanged > '2020-04-01'" @<hubot-name> mon find all incidents filter by "priority <= 2 and state != 'closed'" @<hubot-name> mon find all incidents filter by "team == 'sre'" Restrictions: 1. Attribute names are case-sensitive. 2. Expressions must include an attribute name, operator, and value (no value is allowed for operators "is empty" "is not empty"). 3. There must be at least one space between the attribute name and operator and the operator and value. 4. Operators and logical operators are case-insensitive 'or' == 'OR' == 'Or'. 5. Only "or's" or "and's" are allowed in an expression, not a mixture of both. 6. No parentheses are allowed for grouping expressions.
mon get incident <incident_id>	Get details of a specific incident.
mon get timeline <incident_id>	Get timeline (history) for a specific incident.
mon get events for incident <incident_id>	Get events for a specific incident.
mon get the event on eventid <event_id> and dedupkey <dedupkey>	Get event details for a specific event.
mon resolve incident <incident_id>	Set a specific incident as `resolved`.
mon list users	Return a list of users.
mon get user <user_id>	Get details of a specific user.
mon list groups	Return a list of groups.
mon get group <group_name>	Get details of a specific group.

Table 2. ChatOps commands for integration with PagerDuty
Command	Description
pd find major incidents for <team\|user> <team_id\|user_id>[,<team_id\|user_id>]	Return a list of open PagerDuty incidents with high urgency for teams or users. The incidents that are created in the last 30 days can be retrieved.
pd find major incidents for <team\|user> <team_ids\|user_id> from <YYYY-MM-DDTHH-MM-SS> to <YYYY-MM-DDTHH-MM-SS>	Return a list of open PageDuty incidents with high urgency during a specific period.
pd get incident <incident_id>	Get details of a specific PagerDuty incident.
pd reassign incident <incident_id> to user <user_ids> from <from_user_email>	Reassign a PagerDuty incident.
pd acknowledge incident <incident_id> from <user_email>	Acknowledge a PagerDuty incident.
pd create note for incident <incident_id> from <user_email> with content <content>	Create a note for a PagerDuty incident.
pd resolve incident <incident_id> from <from_email>	Set a PagerDuty incident as `resolved`.
pd find user <query>	Return a list of teams. <query> is a substring of the username or email.
pd find team <query>	Return a list of teams. <query> is a substring of the team.
pd find escalation for team <team_id>	Return the escalation policy for a team.
pd find oncall for escalation policy <escalation_policy_id>	Return the on-call information for an escalation.
pd find schedule <query>	Return the schedule. <query> is the name of the schedule.
pd find oncall for schedule <schedule_id>	Return the on-call information for a schedule.

Table 3. Supported filtering attributes and operators
Filtering attribute	Attribute description	Supported operators	Type and supported values
priority	==, !=, >, >=, <, <=	The priority that is assigned to the incident. 1 is the highest and 5 is the lowest, but the expressions are evaluated numerically. For example, use priority < 3 to find higher priority defects (1,2).	Integer.
state	==, !=	Current state of the incident.	String. Supported values are 'unassigned', 'assignedToTeam', 'assignedToIndividual', 'inProgress', 'onHold', 'resolved', 'closed'.
owner	==, !=, contains, does not contain, starts with, ends with, is empty, is not empty	The owning user of the incident.	String.
team	==, !=, contains, does not contain, starts with, ends with, is empty, is not empty	The owning group of the incident.	String.
displayId	==, !=, contains, does not contain, starts with, ends with, is empty, is not empty	Display ID of the incident.	String.
lastChanged	==, !=, >, >=, <, <=	The timestamp of the last update to the incident. Expressions use the ISO time format. Example expressions: lastChanged >= '2017-09-12T08:00:00.000Z' lastChanged >= '2017-09-12T08' lastChanged >= '2017-09-12'	Datetime.
assignedBy	==, !=	Indicates whether the last assignment of the incident to a team or owner was manual or by an incident policy.	String. Supported values are 'MANUAL' and POLICY'.
id	==, !=	Internal UUID of the incident.	String.