# Jira Service Management Integration Guide

## Overview
This guide walks you through configuring the **Incode Identity Verification** app for Jira Service Management (JSM). The integration allows help desk agents to verify employee identities directly from a JSM service request using Incode's biometric verification platform.

When a service request is created, agents can send a verification link to the employee via SMS or email. The employee completes a liveness check and face match on their device, and the result is automatically posted back to the ticket.

---

## Prerequisites
Before you begin, ensure you have the following:

- An active **Incode Workforce** account
- A **Jira Service Management** Cloud instance
- Admin access to both your JSM instance and Incode dashboard
- The **Integration Ecosystem** feature enabled in your Incode dashboard (required for Client Credentials)

---

## Step 1: Install the App
1. Go to the [Atlassian Marketplace](https://marketplace.atlassian.com/) and search for **Incode Identity Verification**
2. Click **Get it now** and select your JSM site
3. Follow the installation prompts and grant the requested permissions
4. Once installed, navigate to **Jira Settings → Apps → Incode Verification Settings**

---

## Step 2: Gather Your Incode Credentials
You will need the following from your Incode dashboard:

| Field | Where to find it |
| --- | --- |
| **API Key** | Reach out to your Incode Point of Contact |
| **Client ID** | Dashboard → Integrations → Default client credentials integration |
| **Client Secret** | Dashboard → Integrations → Default client credentials integration → Generate |
| **Integration Reference** | Dashboard → Integrations → your B2B integration |

> ⚠️
> ### The Client Secret is only shown once when generated. Store it securely before closing the dialog.

---

## Step 3: Configure the App
Navigate to **Jira Settings → Apps → Incode Verification Settings** and fill in the following sections:

### Incode API Credentials
- **Environment** — Select **Demo** for testing or **Production** for live use
  - Demo API: `demo-api.incodesmile.com`
  - Production API: `saas-api.incodesmile.com`
- **API Key** — Enter your Incode API key
- **Client ID** — Enter your OAuth 2.0 Client ID
- **Client Secret** — Enter your OAuth 2.0 Client Secret
- **Integration Reference** — Enter your B2B integration reference ID

Click **Test credentials** to verify the connection. You should see a **✓ Connected** badge if the credentials are valid.

### Verification Settings
- **Link expiry (minutes)** — How long the verification link remains valid (5–60 minutes, default 10)
- **Default delivery method** — Whether to default to **SMS** or **Email** delivery when the agent opens the panel

### JIRA Status Transitions _(Optional)_
Map Incode verification outcomes to your existing JSM ticket statuses. Leave blank to manage ticket status manually.

| Outcome | Recommended status |
| --- | --- |
| Verification passes | In Progress |
| Verification fails | Escalate |
| Manual review required | Escalate or Pending |

### Comment Messages _(Optional)_
Customize the comments posted to JIRA tickets when verification completes. The following template variables are available:

| Variable | Description |
| --- | --- |
| `{{name}}` | Employee's display name |
| `{{email}}` | Employee's corporate email |
| `{{identityId}}` | Incode identity ID |
| `{{sessionId}}` | Incode session ID |

Click **Save configuration** when done.

---

## Step 4: Configure Webhooks in Incode Dashboard
To receive real-time verification results in your JSM tickets, you need to register your webhook URL in the Incode dashboard.

1. In your Incode dashboard, go to **Configuration → Webhooks**
2. Add a new webhook with the following settings:
   - **URL**: Your Forge webhook URL (provided during app setup)
   - **Events**: `SESSION_STARTED`, `SESSION_SUCCEEDED`, `SESSION_FAILED`, `SESSION_PENDING_REVIEW`
3. Save the webhook configuration

> 💡
> ### Your webhook URL is unique to your JSM installation. Contact [support.incode.com](https://support.incode.com/) if you need help locating it.

---

## Step 5: Set Up Your Employee Directory
The B2B API matches employees against your Incode directory using the **corporate email address** as the `loginHint`. Ensure your employees are enrolled in Incode before using the integration.

---

## How It Works for Agents
Once configured, here is the agent workflow:
1. Employee calls the help desk and a service request is open in JSM
2. Agent opens the ticket and scrolls to the **Incode Identity Verification** panel
3. Agent enters the employee's **corporate email address**
4. Agent selects the delivery method:
   - **SMS** — recommended for lockout scenarios where the employee cannot access corporate email
   - **Email** — sends to corporate email or an alternate address
5. Agent clicks **Send verification link**
6. Employee receives the link and completes biometric verification on their device (typically under 30 seconds)
7. The panel automatically updates with the result — no refresh needed
8. The JSM ticket is updated with:
   - An activity comment showing the verification result, identity ID, and session ID
   - An automatic status transition (if configured)

---

## Verification Outcomes
| Outcome | Panel display | Default comment |
| --- | --- | --- |
| **Passed** | ✅ Verification passed | Identity confirmed — you may proceed |
| **Failed** | ❌ Verification failed | Do not proceed — escalate for review |
| **Pending review** | ⚠️ Manual review required | Do not proceed until review is complete |

---

## Troubleshooting
### "Setup required" message in the panel
The app has not been configured yet. Go to **Jira Settings → Apps → Incode Verification Settings** and enter your Incode credentials.

### "Error sending verification"
Check the following:
- Your Incode credentials are correct (use the **Test credentials** button)
- The employee's corporate email exists in your Incode directory
- Your integration reference is correct
- The Incode environment (Demo/Production) matches your account

### Ticket status not updating automatically
- Ensure you have selected status transitions in the admin settings
- The transition name must exactly match an available transition from the ticket's current state
- Check that your JSM project workflow includes the configured transitions

### Webhook results not appearing
- Verify the webhook URL is registered in your Incode dashboard
- Confirm all four session event types are enabled
- Check that your Incode account has the Integration Ecosystem feature enabled

---

## Support
- **Incode support**: [support.incode.com](https://support.incode.com/)
- **Developer docs**: [workforce.developer.incode.com](https://workforce.developer.incode.com/)
- **API reference**: [developer.incode.com](https://developer.incode.com/)