1 | # Command Handlers
|
2 |
|
3 | Command handlers define an Atomist Bot command. Thus, command
|
4 | handlers provide an easy way for you to define your own "bot commands"
|
5 | that act on the world, with access to any system you have access to
|
6 | _and_ the Atomist Cortex data model. They are typically invoked by a
|
7 | human by sending a message to the Atomist bot.
|
8 |
|
9 | Command handlers may take parameters. Like event handlers, they return
|
10 | a `HandlerResult`.
|
11 |
|
12 | ## Intent
|
13 |
|
14 | Each command handler has an associated "intent", i.e., the message the
|
15 | Atomist Bot will associate with that command handler. When the
|
16 | Atomist bot receives a message matching the intent, it will invoke the
|
17 | associated command handler. You provide the intent as the second
|
18 | argument to the `@CommandHandler` decorator on the command handler
|
19 | class. The first argument is a description of the command handler.
|
20 | In the example below, the registered intent is "hello world".
|
21 |
|
22 | ```typescript
|
23 | @CommandHandler("Sends a hello back to the client", "hello world")
|
24 | export class HelloWorld implements HandleCommand {
|
25 | public handle(ctx: HandlerContext): Promise<HandlerResult> {
|
26 | ...
|
27 | }
|
28 | }
|
29 | ```
|
30 |
|
31 | When you send the message `@atomist hello world` in a channel to which
|
32 | the Atomist Bot has been invited, it will execute the `handle` command
|
33 | in the `HelloWorld` class.
|
34 |
|
35 | ## Parameters
|
36 |
|
37 | Command handlers may take any number of **parameters**, which will be
|
38 | injected into a fresh instance at runtime. Parameters are specified
|
39 | using [decorators](Decorators.md).
|
40 |
|
41 | For example:
|
42 |
|
43 | ```typescript
|
44 | @Parameter({
|
45 | displayName: "Desired Spring Boot version",
|
46 | description: "The desired Spring Boot version across these repos",
|
47 | pattern: /^.+$/,
|
48 | validInput: "Semantic version",
|
49 | required: false,
|
50 | })
|
51 | public desiredBootVersion: string = "1.5.6.RELEASE";
|
52 | ```
|
53 |
|
54 | The decorated variable names the parameter. If you assign a value to
|
55 | the variable, as in the example, it becomes the parameter’s default
|
56 | value. The `@Parameter` decorator adds additional metadata via a
|
57 | single argument: a JavaScript object whose properties are documented
|
58 | in the conventions. It is recommended to set `description` and `displayName`
|
59 | in order to help other users when invoking the command
|
60 | via the Atomist bot. If you supply a `pattern` for validation, supply
|
61 | `validInput` to describe it.
|
62 |
|
63 | ## Response Messages
|
64 |
|
65 | Another unique feature of command handlers is the ability to respond
|
66 | to the invoking user in Slack, in the channel where the command was
|
67 | issued.
|
68 |
|
69 | `ctx.messageClient.respond("No, but thank you for asking.");`
|
70 |
|
71 | ## Queries
|
72 |
|
73 | Command handlers can issue GraphQL queries, using the `GraphClient` on
|
74 | the `HandlerContext` argument to their `handler` function.
|