メインコンテンツまでスキップ

Jira Service Management

Jira Service Management を Squid に接続し、service desk request を検索、作成、管理します​

Jira Service Management Connector の Functionality​

Jira Service Management（JSM）connector により、Squid AI agent は user に代わって service desk request を操作できます。

Capability説明
Request の検索service desk および status で optional に filter できる、service desk request の text search
Request detail の取得status、priority、reporter、assignee、SLA、comment、attachment を含む完全な request detail
Semantic searchrelated request や similar request の検索を含む、index 済み request に対する自然言語 search
Request の作成customer に代わる作成も optional で可能な、service desk 内の新規 request の作成
Request の更新request の summary、description、priority、assignee の update
Commentrequest への public comment または internal comment の追加
Request の transitionrequest を workflow 内で移動する（例: resolve または close）
Service desk と request type の list 化instance で利用可能な service desk と request type の discovery

Index Requests が有効な場合、Squid は service desk request を 10 分ごとに knowledge base に sync します。これにより semantic search と related-request feature が有効になります。Squid は request に設定された permission を尊重できるため、agent は Jira Service Management で chat 中の person が閲覧できる request のみを retrieve します。Respecting source permissionsを参照してください。

Jira または Jira Service Management？

engineering および project issue tracking（issue、project、JQL）には Jira connector を使用してください。customer または employee support workflow には Jira Service Management connector を使用します。これは service desk、request type、customer、SLA、public comment と internal comment の区別に対応します。

Authentication の設定​

connector は 2 つの authentication mode をサポートします。

  • API Key（default）: API token の管理に関する Atlassian documentation に従い、Atlassian API token を作成します。token と、その token に属する Atlassian account の email address を指定します。

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

Squid Application に Jira Service Management Connector を追加する​

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

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

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

  4. 以下の configuration detail を指定します。

Connector ID: code 内で connector を一意に識別する string。

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: Squid secret として安全に保存される Atlassian API token。
  • Email: API token に関連付けられた email address。

OAuth 2.0 mode を使用する場合:

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

両 mode の追加 option:

Cloud ID: Optional。instance が subdomain を介して access できない場合に必要な Atlassian Cloud ID。設定すると、API call は api.atlassian.com を通じて route されます。

Index Requests: service desk request の semantic search と similarity feature を有効にします。

Service Desk IDs to Index: index 化する service desk ID の comma-separated list。すべての service desk を index 化するには空欄にします。

Request History Days: sync する request history の日数。default は 30。

注記

semantic search feature を使用するには、Index Requests を有効にする必要があります。有効にした後、initial sync が完了するまでしばらく待機してください。

Application で 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. 「user が service desk request を検索または管理したい場合にこれを call する」など、agent がこの connection を使用する方法について description を指定します。

  7. Test をクリックし、「What are the open requests in the IT service desk?」と agent に質問してみます。

Squid SDK を使用する​

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

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',
      },
    ],
  });

npm Package を使用する​

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

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);