freshservice-automation

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Freshservice Automation via Rube MCP

通过Rube MCP实现Freshservice自动化

Automate Freshservice IT Service Management operations through Composio's Freshservice toolkit via Rube MCP.

通过Composio的Freshservice工具包，借助Rube MCP自动化Freshservice IT服务管理操作。

Prerequisites

前置条件

Rube MCP must be connected (RUBE_SEARCH_TOOLS available)
Active Freshservice connection via
```
RUBE_MANAGE_CONNECTIONS
```
with toolkit
```
freshservice
```
Always call
```
RUBE_SEARCH_TOOLS
```
first to get current tool schemas

必须已连接Rube MCP（RUBE_SEARCH_TOOLS可用）
通过
```
RUBE_MANAGE_CONNECTIONS
```
并使用工具包
```
freshservice
```
建立有效的Freshservice连接
请始终先调用
```
RUBE_SEARCH_TOOLS
```
以获取最新的工具架构

Setup

设置步骤

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.

Verify Rube MCP is available by confirming
```
RUBE_SEARCH_TOOLS
```
responds
Call
```
RUBE_MANAGE_CONNECTIONS
```
with toolkit
```
freshservice
```
If connection is not ACTIVE, follow the returned auth link to complete Freshservice authentication
Confirm connection status shows ACTIVE before running any workflows

获取Rube MCP：在客户端配置中添加

https://rube.app/mcp

作为MCP服务器。无需API密钥——只需添加端点即可使用。

确认
```
RUBE_SEARCH_TOOLS
```
能正常响应，以此验证Rube MCP可用
调用
```
RUBE_MANAGE_CONNECTIONS
```
并指定工具包
```
freshservice
```
如果连接状态未显示为ACTIVE，请按照返回的授权链接完成Freshservice身份验证
在运行任何工作流之前，确认连接状态显示为ACTIVE

Core Workflows

核心工作流

1. List and Search Tickets

1. 列出并搜索工单

When to use: User wants to find, list, or search for tickets

Tool sequence:

```
FRESHSERVICE_LIST_TICKETS
```
- List tickets with optional filtering and pagination [Required]
```
FRESHSERVICE_GET_TICKET
```
- Get detailed information for a specific ticket [Optional]

Key parameters for listing:

```
filter
```
: Predefined filter ('all_tickets', 'deleted', 'spam', 'watching')
```
updated_since
```
: ISO 8601 timestamp to get tickets updated after this time
```
order_by
```
: Sort field ('created_at', 'updated_at', 'status', 'priority')
```
order_type
```
: Sort direction ('asc' or 'desc')
```
page
```
: Page number (1-indexed)
```
per_page
```
: Results per page (1-100, default 30)
```
include
```
: Additional fields ('requester', 'stats', 'description', 'conversations', 'assets')

Key parameters for get:

```
ticket_id
```
: Unique ticket ID or display_id
```
include
```
: Additional fields to include

Pitfalls:

By default, only tickets created within the past 30 days are returned
Use
```
updated_since
```
to retrieve older tickets
Each
```
include
```
value consumes additional API credits
```
page
```
is 1-indexed; minimum value is 1
```
per_page
```
max is 100; default is 30
Ticket IDs can be the internal ID or the display_id shown in the UI

适用场景：用户需要查找、列出或搜索工单

工具流程:

```
FRESHSERVICE_LIST_TICKETS
```
- 列出工单，可选择过滤和分页 [必填]
```
FRESHSERVICE_GET_TICKET
```
- 获取特定工单的详细信息 [可选]

列单关键参数:

```
filter
```
: 预定义过滤器（'all_tickets'、'deleted'、'spam'、'watching'）
```
updated_since
```
: ISO 8601时间戳，用于获取该时间之后更新的工单
```
order_by
```
: 排序字段（'created_at'、'updated_at'、'status'、'priority'）
```
order_type
```
: 排序方向（'asc'或'desc'）
```
page
```
: 页码（从1开始）
```
per_page
```
: 每页结果数（1-100，默认30）
```
include
```
: 附加字段（'requester'、'stats'、'description'、'conversations'、'assets'）

获取工单关键参数:

```
ticket_id
```
: 唯一的工单ID或display_id
```
include
```
: 要包含的附加字段

注意事项:

默认仅返回过去30天内创建的工单
使用
```
updated_since
```
参数获取更早的工单
每个
```
include
```
值会消耗额外的API额度
```
page
```
从1开始；最小值为1
```
per_page
```
最大值为100；默认值为30
工单ID可以是内部ID或UI中显示的display_id

2. Create a Ticket

2. 创建工单

When to use: User wants to log a new incident or request

Tool sequence:

```
FRESHSERVICE_CREATE_TICKET
```
- Create a new ticket [Required]

Key parameters:

```
subject
```
: Ticket subject line (required)
```
description
```
: HTML description of the ticket (required)
```
status
```
: Ticket status - 2 (Open), 3 (Pending), 4 (Resolved), 5 (Closed) (required)
```
priority
```
: Ticket priority - 1 (Low), 2 (Medium), 3 (High), 4 (Urgent) (required)
```
email
```
: Requester's email address (provide either email or requester_id)
```
requester_id
```
: User ID of the requester
```
type
```
: Ticket type ('Incident' or 'Service Request')
```
source
```
: Channel - 1 (Email), 2 (Portal), 3 (Phone), 4 (Chat), 5 (Twitter), 6 (Facebook)
```
impact
```
: Impact level - 1 (Low), 2 (Medium), 3 (High)
```
urgency
```
: Urgency level - 1 (Low), 2 (Medium), 3 (High), 4 (Critical)

Pitfalls:

```
subject
```
,
```
description
```
,
```
status
```
, and
```
priority
```
are all required
Either
```
email
```
or
```
requester_id
```
must be provided to identify the requester
Status and priority use numeric codes, not string names
Description supports HTML formatting
If email does not match an existing contact, a new contact is created

适用场景：用户需要记录新的事件或请求

工具流程:

```
FRESHSERVICE_CREATE_TICKET
```
- 创建新工单 [必填]

关键参数:

```
subject
```
: 工单主题（必填）
```
description
```
: 工单的HTML格式描述（必填）
```
status
```
: 工单状态 - 2（已打开）、3（待处理）、4（已解决）、5（已关闭）（必填）
```
priority
```
: 工单优先级 - 1（低）、2（中）、3（高）、4（紧急）（必填）
```
email
```
: 请求者的邮箱地址（需提供email或requester_id其中一个）
```
requester_id
```
: 请求者的用户ID
```
type
```
: 工单类型（'Incident'或'Service Request'）
```
source
```
: 渠道 - 1（邮件）、2（门户）、3（电话）、4（聊天）、5（Twitter）、6（Facebook）
```
impact
```
: 影响级别 - 1（低）、2（中）、3（高）
```
urgency
```
: 紧急程度 - 1（低）、2（中）、3（高）、4（严重）

注意事项:

```
subject
```
、
```
description
```
、
```
status
```
和
```
priority
```
均为必填项
必须提供
```
email
```
或
```
requester_id
```
其中一个以识别请求者
状态和优先级使用数字编码，而非字符串名称
描述支持HTML格式
如果邮箱与现有联系人不匹配，将创建一个新联系人

3. Bulk Update Tickets

3. 批量更新工单

When to use: User wants to update multiple tickets at once

Tool sequence:

```
FRESHSERVICE_LIST_TICKETS
```
- Find tickets to update [Prerequisite]
```
FRESHSERVICE_BULK_UPDATE_TICKETS
```
- Update multiple tickets [Required]

Key parameters:

```
ids
```
: Array of ticket IDs to update (required)
```
update_fields
```
: Dictionary of fields to update (required)
- Allowed keys: 'subject', 'description', 'status', 'priority', 'responder_id', 'group_id', 'type', 'tags', 'custom_fields'

Pitfalls:

Bulk update performs sequential updates internally; large batches may take time
All specified tickets receive the same field updates
If one ticket update fails, others may still succeed; check response for individual results
Cannot selectively update different fields per ticket in a single call
Custom fields must use their internal field names, not display names

适用场景：用户需要一次性更新多个工单

工具流程:

```
FRESHSERVICE_LIST_TICKETS
```
- 查找需要更新的工单 [前置步骤]
```
FRESHSERVICE_BULK_UPDATE_TICKETS
```
- 批量更新工单 [必填]

关键参数:

```
ids
```
: 要更新的工单ID数组（必填）
```
update_fields
```
: 要更新的字段字典（必填）
- 允许的键：'subject'、'description'、'status'、'priority'、'responder_id'、'group_id'、'type'、'tags'、'custom_fields'

注意事项:

批量更新在内部执行顺序更新；大批量操作可能需要耗时
所有指定工单都会收到相同的字段更新
如果某个工单更新失败，其他工单可能仍会成功；请检查响应中的单个结果
单次调用中无法针对不同工单选择性更新不同字段
自定义字段必须使用其内部字段名称，而非显示名称

4. Create Ticket via Outbound Email

4. 通过外发邮件创建工单

When to use: User wants to create a ticket by sending an outbound email notification

Tool sequence:

```
FRESHSERVICE_CREATE_TICKET_OUTBOUND_EMAIL
```
- Create ticket with email notification [Required]

Key parameters:

```
email
```
: Requester's email address (required)
```
subject
```
: Email subject / ticket subject (required)
```
description
```
: HTML email body content
```
status
```
: Ticket status (2=Open, 3=Pending, 4=Resolved, 5=Closed)
```
priority
```
: Ticket priority (1=Low, 2=Medium, 3=High, 4=Urgent)
```
cc_emails
```
: Array of CC email addresses
```
email_config_id
```
: Email configuration ID for the sender address
```
name
```
: Requester name

Pitfalls:

This creates a standard ticket via the /api/v2/tickets endpoint while sending an email
If the email does not match an existing contact, a new contact is created with the provided name
```
email_config_id
```
determines which email address the notification appears to come from

适用场景：用户需要通过发送外发邮件通知来创建工单

工具流程:

```
FRESHSERVICE_CREATE_TICKET_OUTBOUND_EMAIL
```
- 创建工单并发送邮件通知 [必填]

关键参数:

```
email
```
: 请求者的邮箱地址（必填）
```
subject
```
: 邮件主题/工单主题（必填）
```
description
```
: HTML格式的邮件正文内容
```
status
```
: 工单状态（2=已打开，3=待处理，4=已解决，5=已关闭）
```
priority
```
: 工单优先级（1=低，2=中，3=高，4=紧急）
```
cc_emails
```
: 抄送邮箱地址数组
```
email_config_id
```
: 发件人地址的邮件配置ID
```
name
```
: 请求者姓名

注意事项:

此操作会通过/api/v2/tickets端点创建标准工单，同时发送邮件
如果邮箱与现有联系人不匹配，将使用提供的姓名创建一个新联系人
```
email_config_id
```
决定了通知邮件显示的发件人地址

5. Create Service Requests

5. 创建服务请求

When to use: User wants to submit a service catalog request

Tool sequence:

```
FRESHSERVICE_CREATE_SERVICE_REQUEST
```
- Create a service request for a catalog item [Required]

Key parameters:

```
item_display_id
```
: Display ID of the catalog item (required)
```
email
```
: Requester's email address
```
quantity
```
: Number of items to request (default: 1)
```
custom_fields
```
: Custom field values for the service item form
```
parent_ticket_id
```
: Display ID of a parent ticket (for child requests)

Pitfalls:

```
item_display_id
```
can be found in Admin > Service Catalog > item URL (e.g., /service_catalog/items/1)
Custom fields keys must match the service item form field names
Quantity defaults to 1 if not specified
Service requests follow the approval workflow defined for the catalog item

适用场景：用户需要提交服务目录请求

工具流程:

```
FRESHSERVICE_CREATE_SERVICE_REQUEST
```
- 为目录项创建服务请求 [必填]

关键参数:

```
item_display_id
```
: 目录项的显示ID（必填）
```
email
```
: 请求者的邮箱地址
```
quantity
```
: 请求的项数量（默认：1）
```
custom_fields
```
: 服务项表单的自定义字段值
```
parent_ticket_id
```
: 父工单的显示ID（用于子请求）

注意事项:

```
item_display_id
```
可在管理员>服务目录>项URL中找到（例如：/service_catalog/items/1）
自定义字段键必须与服务项表单字段名称匹配
如果未指定数量，默认值为1
服务请求会遵循为目录项定义的审批工作流

Common Patterns

通用模式

Status Code Reference

状态码参考

Code	Status
2	Open
3	Pending
4	Resolved
5	Closed

编码	状态
2	已打开
3	待处理
4	已解决
5	已关闭

Priority Code Reference

优先级编码参考

Code	Priority
1	Low
2	Medium
3	High
4	Urgent

编码	优先级
1	低
2	中
3	高
4	紧急

Pagination

分页

Use
```
page
```
(1-indexed) and
```
per_page
```
(max 100) parameters
Increment
```
page
```
by 1 each request
Continue until returned results count <
```
per_page
```
Default page size is 30

使用
```
page
```
（从1开始）和
```
per_page
```
（最大100）参数
每次请求将
```
page
```
加1
持续请求直到返回的结果数小于
```
per_page
```
默认每页大小为30

Finding Tickets by Date Range

按日期范围查找工单

1. Call FRESHSERVICE_LIST_TICKETS with updated_since='2024-01-01T00:00:00Z'
2. Optionally add order_by='updated_at' and order_type='desc'
3. Paginate through results

1. 调用FRESHSERVICE_LIST_TICKETS并设置updated_since='2024-01-01T00:00:00Z'
2. 可选添加order_by='updated_at'和order_type='desc'
3. 分页遍历结果

Known Pitfalls

已知注意事项

Numeric Codes:

Status and priority use numeric values, not strings
Source channel uses numeric codes (1-6)
Impact and urgency use numeric codes (1-3 or 1-4)

Date Filtering:

Default returns only tickets from the last 30 days
Use
```
updated_since
```
parameter for older tickets
Date format is ISO 8601 (e.g., '2024-01-01T00:00:00Z')

Rate Limits:

Freshservice API has per-account rate limits
Each
```
include
```
option consumes additional API credits
Implement backoff on 429 responses

Response Parsing:

Response data may be nested under
```
data
```
or
```
data.data
```
Parse defensively with fallback patterns
Ticket IDs are numeric integers

数字编码:

状态和优先级使用数值，而非字符串
来源渠道使用数字编码（1-6）
影响级别和紧急程度使用数字编码（1-3或1-4）

日期过滤:

默认仅返回过去30天的工单
使用
```
updated_since
```
参数获取更早的工单
日期格式为ISO 8601（例如：'2024-01-01T00:00:00Z'）

速率限制:

Freshservice API有每个账户的速率限制
每个
```
include
```
选项会消耗额外的API额度
在收到429响应时请实现退避机制

响应解析:

响应数据可能嵌套在
```
data
```
或
```
data.data
```
下
使用防御性解析并设置回退模式
工单ID为数值整数

Quick Reference

快速参考

Task	Tool Slug	Key Params
List tickets	FRESHSERVICE_LIST_TICKETS	filter, updated_since, page, per_page
Get ticket	FRESHSERVICE_GET_TICKET	ticket_id, include
Create ticket	FRESHSERVICE_CREATE_TICKET	subject, description, status, priority, email
Bulk update	FRESHSERVICE_BULK_UPDATE_TICKETS	ids, update_fields
Outbound email ticket	FRESHSERVICE_CREATE_TICKET_OUTBOUND_EMAIL	email, subject, description
Service request	FRESHSERVICE_CREATE_SERVICE_REQUEST	item_display_id, email, quantity

任务	工具标识	关键参数
列出工单	FRESHSERVICE_LIST_TICKETS	filter, updated_since, page, per_page
获取工单	FRESHSERVICE_GET_TICKET	ticket_id, include
创建工单	FRESHSERVICE_CREATE_TICKET	subject, description, status, priority, email
批量更新	FRESHSERVICE_BULK_UPDATE_TICKETS	ids, update_fields
外发邮件创建工单	FRESHSERVICE_CREATE_TICKET_OUTBOUND_EMAIL	email, subject, description
服务请求	FRESHSERVICE_CREATE_SERVICE_REQUEST	item_display_id, email, quantity