BMC Helix ITSM

BMC Helix ITSM stores your infrastructure and clinical equipment as Configuration Items in the AR System. When a tech confirms an asset’s location in Forager, this integration writes the confirmed location directly to the CI record — so anyone querying the CMDB sees the last physically verified location, not a stale import. Choose this approach if your organization runs BMC Helix ITSM (on-prem or Helix Platform SaaS) and wants location data flowing from field attestations into your CI lifecycle without manual data entry.

What happens

Tech scans BED-1142 in ICU Pod B (Forager app)
  → Attestation recorded in Forager
  → Forager POSTs to your proxy endpoint
  → Proxy authenticates to AR System, looks up CI by Tag Number
  → CI fields updated: Location, Last Scan By, Last Scan Time, Forager Result

BMC Helix setup

Step 1 — Create a dedicated integration account

Create a BMC Helix user account for the integration. A dedicated account makes it easy to audit integration writes and rotate credentials independently.

Log in as an administrator
Go to Remedy ITSM → User Management → Create User
Set:
- Login Name: forager_integration
- License Type: Fixed (required for API access)
- Password: strong, saved securely
Assign the CMDB Submitter and Asset Viewer roles — these allow reading and updating asset CI records

If your Helix instance uses SSO, you may need to create the account through your identity provider and then add the AR System roles through the Helix admin console. Coordinate with your BMC administrator.

Step 2 — Add custom fields to AST:BMC_BaseElement

The integration writes to four custom fields. Add them to your asset CI form class:

In AR System Administration, go to Database → Form → AST:BMC_BaseElement
Open Columns and add:

Field label	AR field name	Type	Notes
Forager Location	`Forager_Location`	Character (500)	Full breadcrumb path
Forager Confirmed By	`Forager_ConfirmedBy`	Character (200)	Tech display name
Forager Last Scan	`Forager_LastScan`	Date/Time	ISO 8601 timestamp
Forager Result	`Forager_Result`	Character (50)	`match`, `mismatch_confirmed`, etc.

If you prefer, you can map to the native Location field on the CI form. The native field accepts free text in many Helix configurations — test with a manual update in AR System Administrator to confirm before relying on it in the proxy.

Proxy deployment

The proxy handles JWT authentication (AR System tokens expire and must be refreshed), the CI lookup by tag number, and the field update.

Create `api/forager.js`

const HELIX_URL  = process.env.HELIX_URL   // https://yourcompany.onbmc.com
const HELIX_USER = process.env.HELIX_USER  // forager_integration
const HELIX_PASS = process.env.HELIX_PASS

// AR System JWT tokens expire — fetch a fresh one per request
// (For high-volume deployments, cache the token and refresh before expiry)
async function getToken() {
  const res = await fetch(`${HELIX_URL}/api/jwt/login`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
    body: new URLSearchParams({ username: HELIX_USER, password: HELIX_PASS }),
  })
  if (!res.ok) throw new Error(`JWT login failed: ${res.status}`)
  const { token } = await res.json()
  return token
}

export default async function handler(req, res) {
  // Validate shared secret
  if (req.headers['x-forager-secret'] !== process.env.SHARED_SECRET) {
    return res.status(401).json({ error: 'Unauthorized' })
  }

  const { values } = req.body
  const assetTag = values?.['Asset Tag']
  if (!assetTag) {
    return res.status(400).json({ error: 'Asset Tag is required' })
  }

  let token
  try {
    token = await getToken()
  } catch (err) {
    console.error('Helix auth failed:', err.message)
    return res.status(502).json({ error: 'Helix authentication failed' })
  }

  const headers = {
    Authorization: `AR-JWT ${token}`,
    'Content-Type': 'application/json',
  }

  // 1. Look up CI by Tag Number
  // AR System query syntax: 'Field Name' = "value"
  const query = encodeURIComponent(`'Tag Number' = "${assetTag}"`)
  const searchRes = await fetch(
    `${HELIX_URL}/api/arsys/v1/entry/AST:BMC_BaseElement` +
    `?q=${query}&fields=values(Request%20ID)`,
    { headers }
  )
  if (!searchRes.ok) {
    console.error('Helix search failed:', searchRes.status, await searchRes.text())
    return res.status(502).json({ error: 'Helix CI lookup failed' })
  }
  const { entries } = await searchRes.json()
  if (!entries?.length) {
    console.warn('CI not found in Helix:', assetTag)
    return res.status(200).json({ skipped: true, reason: 'ci_not_found' })
  }

  const requestId = entries[0].values['Request ID']

  // 2. Update CI fields
  const updateRes = await fetch(
    `${HELIX_URL}/api/arsys/v1/entry/AST:BMC_BaseElement/${encodeURIComponent(requestId)}`,
    {
      method: 'PUT',
      headers,
      body: JSON.stringify({
        values: {
          Forager_Location:    values['Location'],
          Forager_ConfirmedBy: values['Last Scan By'],
          Forager_LastScan:    values['Last Scan Time'],
          Forager_Result:      values['Status'],
        },
      }),
    }
  )

  // AR System returns 204 No Content on successful PUT
  if (updateRes.status !== 204 && !updateRes.ok) {
    console.error('Helix update failed:', updateRes.status, await updateRes.text())
    return res.status(502).json({ error: 'Helix CI update failed' })
  }

  return res.status(200).json({ ok: true, request_id: requestId })
}

Environment variables

HELIX_URL=https://yourcompany.onbmc.com
HELIX_USER=forager_integration
HELIX_PASS=your_integration_password
SHARED_SECRET=choose_a_random_string_here

Deploy to Vercel

npx vercel --prod

Add all environment variables in Project → Settings → Environment Variables.

Forager configuration

Go to Dashboard → Settings → Webhooks → Add Webhook
Fill in:

Field	Value
Name	`BMC Helix`
Endpoint URL	Your proxy URL + `/api/forager`
Target Platform	`BMC Helix ITSM`
Auth Header Name	`X-Forager-Secret`
Auth Header Value	Your `SHARED_SECRET` value

Testing

curl -X POST "https://your-proxy.vercel.app/api/forager" \
  -H "Content-Type: application/json" \
  -H "X-Forager-Secret: your_shared_secret" \
  -d '{
    "event": "forager.attestation",
    "values": {
      "Asset Tag": "BED-1142",
      "Location": "Memorial Hospital / Floor 2 / ICU Pod B",
      "Last Scan By": "Maria Ortega",
      "Last Scan Time": "2026-06-07T14:23:11Z",
      "Status": "match"
    }
  }'

Expected response:

{ "ok": true, "request_id": "000000000000042" }

Then open the CI record in Helix and verify:

Forager_Location = Memorial Hospital / Floor 2 / ICU Pod B
Forager_ConfirmedBy = Maria Ortega
Forager_LastScan is updated

Troubleshooting

Symptom	Likely cause	Fix
`401` from proxy	Wrong `SHARED_SECRET`	Verify the header value in Forager matches `SHARED_SECRET` in the proxy
`JWT login failed: 401`	Bad Helix credentials	Test manually: `curl -X POST "HELIX_URL/api/jwt/login" -d "username=forager_integration&password=..."`
`JWT login failed: 403`	Account lacks AR System REST access	In AR System Administration, confirm the user has the `REST API` permission
`skipped: ci_not_found`	Tag Number doesn’t match	Compare the asset tag in Forager to the `Tag Number` field in the Helix CI record — they must match exactly
`Helix CI update failed: 400`	Field name wrong	AR System field names are case-sensitive. Verify `Forager_Location` etc. in AR System Administrator exactly as created
Update returns `204` but fields unchanged	Wrong Request ID	Confirm the lookup is returning the correct entry by checking the `Request ID` in the log and opening that CI directly

AR System field names in the REST API use the database column name, not the display label. If you named the field Forager Location (with a space), the API name may be Forager_Location or FORAGER_LOCATION depending on your Helix version. Check in AR System Administrator → Field Properties.

What your team gains

Helix CI records reflect the last physically verified location of every asset — updated automatically as techs work their normal queues. This eliminates the gap between your CMDB’s imported data and where assets actually are. Auditors querying Helix get attestation-backed location data, and your CMDB team spends less time chasing stale records between discovery cycles.

Getting Started

Field Tech Guide

Dashboard

EC Inspection Rounds

Admin

Integrations

API Reference

Troubleshooting

What happens

BMC Helix setup

Step 1 — Create a dedicated integration account

Step 2 — Add custom fields to AST:BMC_BaseElement

Proxy deployment

Create `api/forager.js`

Environment variables

Deploy to Vercel

Forager configuration

Testing

Troubleshooting

What your team gains

​What happens

​BMC Helix setup

​Step 1 — Create a dedicated integration account

​Step 2 — Add custom fields to AST:BMC_BaseElement

​Proxy deployment

​Create api/forager.js

​Environment variables

​Deploy to Vercel

​Forager configuration

​Testing

​Troubleshooting

​What your team gains

What happens

BMC Helix setup

Step 1 — Create a dedicated integration account

Step 2 — Add custom fields to AST:BMC_BaseElement

Proxy deployment

Create `api/forager.js`

Environment variables

Deploy to Vercel

Forager configuration

Testing

Troubleshooting

What your team gains