Freshservice Automation

1---
2name: freshservice-automation
3description: "Automate Freshservice ITSM tasks via Rube MCP (Composio): create/update tickets, bulk operations, service requests, and outbound emails. Always search tools first for current schemas."
4requires:
5  mcp: [rube]
6---
7 
8# Freshservice Automation via Rube MCP
9 
10Automate Freshservice IT Service Management operations through Composio's Freshservice toolkit via Rube MCP.
11 
12## Prerequisites
13 
14- Rube MCP must be connected (RUBE_SEARCH_TOOLS available)
15- Active Freshservice connection via `RUBE_MANAGE_CONNECTIONS` with toolkit `freshservice`
16- Always call `RUBE_SEARCH_TOOLS` first to get current tool schemas
17 
18## Setup
19 
20**Get Rube MCP**: Add `https://rube.app/mcp` as an MCP server in your client configuration. No API keys needed — just add the endpoint and it works.
21 
22 
231. Verify Rube MCP is available by confirming `RUBE_SEARCH_TOOLS` responds
242. Call `RUBE_MANAGE_CONNECTIONS` with toolkit `freshservice`
253. If connection is not ACTIVE, follow the returned auth link to complete Freshservice authentication
264. Confirm connection status shows ACTIVE before running any workflows
27 
28## Core Workflows
29 
30### 1. List and Search Tickets
31 
32**When to use**: User wants to find, list, or search for tickets
33 
34**Tool sequence**:
351. `FRESHSERVICE_LIST_TICKETS` - List tickets with optional filtering and pagination [Required]
362. `FRESHSERVICE_GET_TICKET` - Get detailed information for a specific ticket [Optional]
37 
38**Key parameters for listing**:
39- `filter`: Predefined filter ('all_tickets', 'deleted', 'spam', 'watching')
40- `updated_since`: ISO 8601 timestamp to get tickets updated after this time
41- `order_by`: Sort field ('created_at', 'updated_at', 'status', 'priority')
42- `order_type`: Sort direction ('asc' or 'desc')
43- `page`: Page number (1-indexed)
44- `per_page`: Results per page (1-100, default 30)
45- `include`: Additional fields ('requester', 'stats', 'description', 'conversations', 'assets')
46 
47**Key parameters for get**:
48- `ticket_id`: Unique ticket ID or display_id
49- `include`: Additional fields to include
50 
51**Pitfalls**:
52- By default, only tickets created within the past 30 days are returned
53- Use `updated_since` to retrieve older tickets
54- Each `include` value consumes additional API credits
55- `page` is 1-indexed; minimum value is 1
56- `per_page` max is 100; default is 30
57- Ticket IDs can be the internal ID or the display_id shown in the UI
58 
59### 2. Create a Ticket
60 
61**When to use**: User wants to log a new incident or request
62 
63**Tool sequence**:
641. `FRESHSERVICE_CREATE_TICKET` - Create a new ticket [Required]
65 
66**Key parameters**:
67- `subject`: Ticket subject line (required)
68- `description`: HTML description of the ticket (required)
69- `status`: Ticket status - 2 (Open), 3 (Pending), 4 (Resolved), 5 (Closed) (required)
70- `priority`: Ticket priority - 1 (Low), 2 (Medium), 3 (High), 4 (Urgent) (required)
71- `email`: Requester's email address (provide either email or requester_id)
72- `requester_id`: User ID of the requester
73- `type`: Ticket type ('Incident' or 'Service Request')
74- `source`: Channel - 1 (Email), 2 (Portal), 3 (Phone), 4 (Chat), 5 (Twitter), 6 (Facebook)
75- `impact`: Impact level - 1 (Low), 2 (Medium), 3 (High)
76- `urgency`: Urgency level - 1 (Low), 2 (Medium), 3 (High), 4 (Critical)
77 
78**Pitfalls**:
79- `subject`, `description`, `status`, and `priority` are all required
80- Either `email` or `requester_id` must be provided to identify the requester
81- Status and priority use numeric codes, not string names
82- Description supports HTML formatting
83- If email does not match an existing contact, a new contact is created
84 
85### 3. Bulk Update Tickets
86 
87**When to use**: User wants to update multiple tickets at once
88 
89**Tool sequence**:
901. `FRESHSERVICE_LIST_TICKETS` - Find tickets to update [Prerequisite]
912. `FRESHSERVICE_BULK_UPDATE_TICKETS` - Update multiple tickets [Required]
92 
93**Key parameters**:
94- `ids`: Array of ticket IDs to update (required)
95- `update_fields`: Dictionary of fields to update (required)
96  - Allowed keys: 'subject', 'description', 'status', 'priority', 'responder_id', 'group_id', 'type', 'tags', 'custom_fields'
97 
98**Pitfalls**:
99- Bulk update performs sequential updates internally; large batches may take time
100- All specified tickets receive the same field updates
101- If one ticket update fails, others may still succeed; check response for individual results
102- Cannot selectively update different fields per ticket in a single call
103- Custom fields must use their internal field names, not display names
104 
105### 4. Create Ticket via Outbound Email
106 
107**When to use**: User wants to create a ticket by sending an outbound email notification
108 
109**Tool sequence**:
1101. `FRESHSERVICE_CREATE_TICKET_OUTBOUND_EMAIL` - Create ticket with email notification [Required]
111 
112**Key parameters**:
113- `email`: Requester's email address (required)
114- `subject`: Email subject / ticket subject (required)
115- `description`: HTML email body content
116- `status`: Ticket status (2=Open, 3=Pending, 4=Resolved, 5=Closed)
117- `priority`: Ticket priority (1=Low, 2=Medium, 3=High, 4=Urgent)
118- `cc_emails`: Array of CC email addresses
119- `email_config_id`: Email configuration ID for the sender address
120- `name`: Requester name
121 
122**Pitfalls**:
123- This creates a standard ticket via the /api/v2/tickets endpoint while sending an email
124- If the email does not match an existing contact, a new contact is created with the provided name
125- `email_config_id` determines which email address the notification appears to come from
126 
127### 5. Create Service Requests
128 
129**When to use**: User wants to submit a service catalog request
130 
131**Tool sequence**:
1321. `FRESHSERVICE_CREATE_SERVICE_REQUEST` - Create a service request for a catalog item [Required]
133 
134**Key parameters**:
135- `item_display_id`: Display ID of the catalog item (required)
136- `email`: Requester's email address
137- `quantity`: Number of items to request (default: 1)
138- `custom_fields`: Custom field values for the service item form
139- `parent_ticket_id`: Display ID of a parent ticket (for child requests)
140 
141**Pitfalls**:
142- `item_display_id` can be found in Admin > Service Catalog > item URL (e.g., /service_catalog/items/1)
143- Custom fields keys must match the service item form field names
144- Quantity defaults to 1 if not specified
145- Service requests follow the approval workflow defined for the catalog item
146 
147## Common Patterns
148 
149### Status Code Reference
150 
151| Code | Status |
152|------|--------|
153| 2 | Open |
154| 3 | Pending |
155| 4 | Resolved |
156| 5 | Closed |
157 
158### Priority Code Reference
159 
160| Code | Priority |
161|------|----------|
162| 1 | Low |
163| 2 | Medium |
164| 3 | High |
165| 4 | Urgent |
166 
167### Pagination
168 
169- Use `page` (1-indexed) and `per_page` (max 100) parameters
170- Increment `page` by 1 each request
171- Continue until returned results count < `per_page`
172- Default page size is 30
173 
174### Finding Tickets by Date Range
175 
176```
1771. Call FRESHSERVICE_LIST_TICKETS with updated_since='2024-01-01T00:00:00Z'
1782. Optionally add order_by='updated_at' and order_type='desc'
1793. Paginate through results
180```
181 
182## Known Pitfalls
183 
184**Numeric Codes**:
185- Status and priority use numeric values, not strings
186- Source channel uses numeric codes (1-6)
187- Impact and urgency use numeric codes (1-3 or 1-4)
188 
189**Date Filtering**:
190- Default returns only tickets from the last 30 days
191- Use `updated_since` parameter for older tickets
192- Date format is ISO 8601 (e.g., '2024-01-01T00:00:00Z')
193 
194**Rate Limits**:
195- Freshservice API has per-account rate limits
196- Each `include` option consumes additional API credits
197- Implement backoff on 429 responses
198 
199**Response Parsing**:
200- Response data may be nested under `data` or `data.data`
201- Parse defensively with fallback patterns
202- Ticket IDs are numeric integers
203 
204## Quick Reference
205 
206| Task | Tool Slug | Key Params |
207|------|-----------|------------|
208| List tickets | FRESHSERVICE_LIST_TICKETS | filter, updated_since, page, per_page |
209| Get ticket | FRESHSERVICE_GET_TICKET | ticket_id, include |
210| Create ticket | FRESHSERVICE_CREATE_TICKET | subject, description, status, priority, email |
211| Bulk update | FRESHSERVICE_BULK_UPDATE_TICKETS | ids, update_fields |
212| Outbound email ticket | FRESHSERVICE_CREATE_TICKET_OUTBOUND_EMAIL | email, subject, description |
213| Service request | FRESHSERVICE_CREATE_SERVICE_REQUEST | item_display_id, email, quantity |
214