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.

Toolkit docs: composio.dev/toolkits/freshservice

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

工具包文档：composio.dev/toolkits/freshservice

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
```
以获取最新的工具schemas

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 with updated_since='2024-01-01T00:00:00Z'
2. 可选添加order_by='updated_at' and 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

Powered by Composio

任务	工具Slug	关键参数
列出工单	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

由Composio提供支持