Jira Service Management

Jira Service Management を Squid に接続して、サービスデスクのリクエストを検索、作成、管理する

Jira Service Management connector の機能

Jira Service Management (JSM) connector により、Squid AI agents はユーザーに代わってサービスデスクのリクエストを操作できます。

機能	説明
リクエストを検索	サービスデスクのリクエストのテキスト検索。必要に応じてサービスデスクとステータスでフィルタリングできます
リクエストの詳細を取得	ステータス、優先度、報告者、担当者、SLAs、コメント、添付ファイルを含む完全なリクエスト詳細
Semantic search	インデックス化されたリクエストに対する自然言語検索。関連または類似するリクエストの検索を含みます
リクエストを作成	サービスデスクで新しいリクエストを作成します。必要に応じて顧客の代理で作成できます
リクエストを更新	リクエストの summary、description、priority、assignee を更新します
コメント	リクエストに public または internal comments を追加します
リクエストを遷移	リクエストを workflow 内で移動します（たとえば、resolve または close）
サービスデスクとリクエストタイプを一覧表示	インスタンスで利用可能なサービスデスクとリクエストタイプを検出します

Index Requests が有効になっている場合、Squid はサービスデスクのリクエストを 10 分ごとに knowledge base に同期し、semantic search と related-request 機能を有効にします。

Jira か Jira Service Management か？

エンジニアリングおよびプロジェクトの issue tracking（issues、projects、JQL）には Jira connector を使用してください。顧客または従業員サポートの workflows には Jira Service Management connector を使用してください。これはサービスデスク、リクエストタイプ、customers、SLAs、public-versus-internal comments と連携します。

認証の設定

connector は 2 つの認証モードをサポートしています。

• API Key（デフォルト）: Atlassian の managing API tokens に関するドキュメントに従って、Atlassian API token を作成します。token と、それが属する Atlassian account の email address を指定します。

• OAuth 2.0: Atlassian developer console で、scopes read:jira-work、write:jira-work、read:servicedesk-request、write:servicedesk-request、offline_access を持つ OAuth 2.0 (3LO) app を作成し、redirect URI を登録します。

Jira Service Management connector を Squid application に追加する

1. Squid Console の Connectors tab に移動します。

2. Available Connectors をクリックします。

3. Jira Service Management connector を見つけ、Add Connector を選択します。

4. 次の設定詳細を指定します。

Connector ID: コード内で connector を一意に識別する文字列。

Subdomain: Jira instance の subdomain。たとえば、instance が https://mycompany.atlassian.net にある場合は、mycompany と入力します。

Authentication Mode: API Key（email + API token）または OAuth 2.0 のいずれか。

API Key mode を使用する場合:

• API Key: Atlassian API token。Squid secret として安全に保存されます。
• Email: API token に関連付けられた email address。

OAuth 2.0 mode を使用する場合:

• Client ID: Atlassian developer console から取得した OAuth 2.0 Client ID。
• Client Secret: OAuth 2.0 client secret。server-side token exchange に使用されます。Squid secret として安全に保存されます。
• Redirect URI: Atlassian developer console に登録された OAuth 2.0 redirect URI。

両方のモードに共通する追加オプション:

Cloud ID: 任意。Atlassian Cloud ID。instance に subdomain 経由でアクセスできない場合に必要です。設定すると、API calls は api.atlassian.com 経由でルーティングされます。

Index Requests: サービスデスクのリクエストに対して semantic search と similarity features を有効にします。

Service Desk IDs to Index: インデックス化する service desk IDs のカンマ区切りリスト。すべてのサービスデスクをインデックス化するには空のままにします。

Request History Days: 同期するリクエスト履歴の日数。デフォルトは 30 です。

注記

Semantic search features を使用するには、Index Requests を有効にする必要があります。有効にした後、初回同期が完了するまでしばらく待ってください。

アプリケーションで Jira Service Management connector を使用する

No-code Studio

1. Squid Console の Studio tab に移動します。

2. Create AI Agent をクリックします。

3. "helpdesk-agent" や "This agent helps the user manage service desk requests" などの agent ID と description を指定します。

4. Add Abilities をクリックします。

5. Jira Service Management entry を展開し、先ほど作成した connector を選択します。

6. "Call this when a user wants to look up or manage service desk requests." など、この connection を agent がどのように使用すべきかの説明を入力します。

7. Test をクリックし、agent に "What are the open requests in the IT service desk?" と尋ねてみます。

Squid SDK を使用する

Squid SDK で AI agent を作成している場合は、ask() function の connectedIntegrations option に connector を追加して接続します。

TypeScript

await this.squid
  .ai()
  .agent('AGENT_ID')
  .ask('Create a request for a new laptop in the IT service desk', {
    connectedIntegrations: [
      {
        integrationId: 'JSM_CONNECTOR_ID',
        integrationType: 'jira_jsm',
        description: 'Call this connector to manage Jira Service Management requests',
      },
    ],
  });

Python

await squid.ai().agent('AGENT_ID').ask(
    'Create a request for a new laptop in the IT service desk',
    options={
        'connectedIntegrations': [
            {
                'integrationId': 'JSM_CONNECTOR_ID',
                'integrationType': 'jira_jsm',
                'description': 'Call this connector to manage Jira Service Management requests',
            }
        ]
    },
)

npm package を使用する

backend または client code から programmatic（non-agent）access を行うには、@squidcloud/jira-jsm-client package をインストールします。

npm install @squidcloud/jira-jsm-client

import { SquidJiraJsmClient } from '@squidcloud/jira-jsm-client';

const jsm = new SquidJiraJsmClient(squid, 'JSM_CONNECTOR_ID');

// Discover service desks and request types
const serviceDesks = await jsm.listServiceDesks();
const requestTypes = await jsm.listRequestTypes(serviceDesks[0].id);

// Create and comment on a request
const request = await jsm.createRequest({
  serviceDeskId: serviceDesks[0].id,
  requestTypeId: requestTypes[0].id,
  summary: 'New laptop request',
});
await jsm.addComment(request.issueKey, 'Ordered, arriving next week.', true);