Snap-in triggered by a DevRev event

Installation guide

• Install DevRev CLI
• Install jq
• Install DevRev SDK

$
devrev profiles authenticate -o <dev-org-slug> -u <youremail@yourdomain.com>

$
devrev snap_in_version init

Trigger

To invoke the snap-in, two distinct triggers are implemented:

1. Creation of work item: This trigger is activated when new objects of type Issue or Ticket are created in DevRev.

2. Text command: This manual trigger is achieved by utilizing a slash command in the Discussions tab of the objects that support this feature.

Action

To implement the desired action of adding a comment to the object timeline, it is essential to identify the appropriate [API] for this task. In this scenario, the /timeline-entries.create API is the designated choice for executing the action of adding a text comment from the snap-in. To accomplish this task, the DevRev SDK is employed.

Creating the snap-in

Updating the manifest

The next step involves updating the manifest to define key attributes of the snap-in. This includes deciding on the name and providing a descriptive overview that is visible to users, offering context about the snap-in’s purpose.

1
version: "2"
2
3
name: Sample snap-in
4
description: Snap-in to add comments for demonstration purpose.
5
6
service_account:
7
  display_name: "DevRev Bot"

Event source

Following the manifest update, the next step is to incorporate the event source. For this scenario, events from DevRev are essential. Therefore, an event source of type devrev-webhook is added. In the configuration, the event type is specified as work_created.

1
event_sources:
2
  organization:
3
    - name: devrev-webhook
4
      display_name: DevRev
5
      type: devrev-webhook
6
      config:
7
        event_types:
8
          - work_created

Input fields

To enable users to configure specific comments, input fields must be defined. For our use case, the following input fields are specified:

1. Input field: This text field empowers users to input a custom message to be added as a comment. The default value is set to “Message from the input field.”

2. Should extra comment be added?: This boolean field determines whether an additional comment should be included. The default value is set to true.

3. List of extra names: This array field allows users to provide a list of names to be added as comments. The default value is set to [“name1”, “name2”].

By incorporating these input fields, the snap-in becomes more adaptable and user-friendly, enabling users to supply specific comments tailored to their needs.

1
inputs:
2
  organization:
3
    - name: input_field_1
4
      description: Input field to add comment to the work item.
5
      field_type: text
6
      default_value: "Message from the input field."
7
      ui:
8
        display_name: Input Field 1
9
10
    - name: input_field_2
11
      description: Add extra comment.
12
      field_type: bool
13
      default_value: true
14
      ui:
15
        display_name: Should extra comment be added?
16
17
    - name: input_field_array
18
      description: List of names to add as comment.
19
      base_type: text
20
      field_type: array
21
      default_value: ["name1", "name2"]
22
      ui:
23
        display_name: List of extra names!

Functions

With the groundwork laid out, the next crucial step involves defining the functions responsible for handling the logic in TypeScript to add comments using the DevRev SDK. The actual implementation of these functions is added in the subsequent step.

1
functions:
2
  - name: function_1
3
    description:
4
      Function to create a timeline entry comment on a DevRev work item created.
5
  - name: function_2
6
    description:
7
      Function to create a timeline entry comment on a DevRev work item on which
8
      comment is added.

Automations

With the building blocks in place, the final piece of the puzzle involves defining automations. These automations encapsulate a trigger and a corresponding function that executes when an event of a specified type occurs.

1
automations:
2
  - name: convergence_automation_devrev
3
    source: devrev-webhook
4
    event_types:
5
      - work_created
6
    function: function_1

Commands

To accommodate the additional trigger, a command must be defined within the manifest file:

1
commands:
2
  - name: comment_here
3
    namespace: devrev
4
    description: Command to trigger function to add comment to this work item.
5
    surfaces:
6
      - surface: discussions
7
        object_types:
8
          - issue
9
          - ticket
10
    usage_hint: "Command to add comment to this work item."
11
    function: function_2

Function logic

Having established the architectural framework for the snap-in, identified its triggers, and outlined the overall workflow, the next crucial phase involves crafting the functions - function_1 and function_2. These functions serve as the engines driving the business logic behind the snap-in’s behavior.

Getting the payload

To kickstart the implementation process, understanding the structure of the payload is paramount. Whether dealing with a work creation event or a command event, having insight into the payload’s composition is crucial. In scenarios where the payload structure is known, implementation can proceed seamlessly. However, if the payload structure is uncertain or real data exploration is desired, logging the entire payload becomes an invaluable step.

To achieve this, the following code snippet can be added to the index.ts file:

1
export const run = async (events: any[]) => {
2
  console.info("events", JSON.stringify(events));
3
};
4
export default run;

Handling DevRev event

Having gained clarity on the expected payload structure, the next step involves crafting custom code to handle the incoming events. In this context, the objective is to print information based on the event type. The provided TypeScript snippet exemplifies a function, handleEvent, tailored for our use case.

1
async function handleDevRevEvent(event: any) {
2
  // Extracting necessary credentials and configurations from the event context
3
  const devrevPAT = event.context.secrets.service_account_token;
4
  const API_BASE = event.execution_metadata.devrev_endpoint;
5
6
  // Setting up the DevRev SDK client
7
  const devrevSDK = client.setup({
8
    endpoint: API_BASE,
9
    token: devrevPAT,
10
  });
11
12
  // Extracting relevant information from the event payload
13
  const workCreated = event.payload.work_created.work;
14
15
  // Retrieving the comment input provided by the user
16
  const messageInput = event.input_data.global_values.input_field_1;
17
18
  // Building the initial comment body
19
  let bodyComment =
20
    "Hello World is printed on the work " +
21
    workCreated.display_id +
22
    " from the automation, with message: " +
23
    messageInput;
24
25
  // Checking if additional comments are requested
26
  const extraComment = event.input_data.global_values.input_field_2;
27
  const extraComments = event.input_data.global_values.input_field_array;
28
29
  // Appending extra comments to the body if requested
30
  if (extraComment) {
31
    for (let comment of extraComments) {
32
      bodyComment = bodyComment + " " + comment;
33
    }
34
  }
35
36
  // Creating the timeline entry comment using DevRev SDK
37
  const body = {
38
    object: workCreated.id,
39
    type: "timeline_comment",
40
    body: bodyComment,
41
  };
42
  const response = await devrevSDK.timelineEntriesCreate(body as any);
43
44
  // Returning the response from the DevRev SDK
45
  return response;
46
}

This function illustrates the process of handling events, extracting necessary information from the payload, and utilizing the DevRev SDK to create a timeline entry comment. It serves as a foundational template that can be adapted based on specific use cases and requirements.

Handling command event

For scenarios where a command event is triggered, a dedicated function, handleCommandEvent, can be implemented to handle the event appropriately. The provided TypeScript snippet outlines the structure of this function, demonstrating how to extract relevant information from the event payload and utilize the DevRev SDK to create a timeline entry comment.

1
async function handleCommandEvent(event: any) {
2
  // Extracting necessary credentials and configurations from the event context
3
  const devrevPAT = event.context.secrets.service_account_token;
4
  const API_BASE = event.execution_metadata.devrev_endpoint;
5
6
  // Setting up the DevRev SDK client
7
  const devrevSDK = client.setup({
8
    endpoint: API_BASE,
9
    token: devrevPAT,
10
  });
11
12
  // Extracting relevant information from the event payload
13
  const workCreated = event.payload.source_id;
14
15
  // Building the comment body for command events
16
  const bodyComment = "Hello World is printed on the work from the command.";
17
18
  // Creating the timeline entry comment using DevRev SDK
19
  const body = {
20
    object: workCreated,
21
    type: "timeline_comment",
22
    body: bodyComment,
23
  };
24
25
  // Sending the request to create the timeline entry comment
26
  const response = await devrevSDK.timelineEntriesCreate(body as any);
27
28
  // Returning the response from the DevRev SDK
29
  return response;
30
}

Deploying the snap-in to your organization

Upon completing and validating the code changes, the next crucial step is deploying the snap-in to your organization. Follow these steps for a seamless deployment:

1. Navigate to the code folder in your project directory.

2. Execute the following commands in sequence to build, package, and create the necessary artifacts:

   $
   npm install
   >
   npm run build
   >
   npm run package