feat(agiloft): add table discovery and upsert

Two operations the current documentation fully specifies, both of which close
real gaps.

EWTable answers the question every other operation depends on: what are the
logical table and field names? Until now users had to read them out of Setup >
Tables by hand. It is knowledge-base scoped, so the request carries $KB but no
$table — narrowing to one table uses the plain `table` parameter — and JSON is
the only supported output, so the .json decorator is mandatory. Like
EWSavedSearch it must run under EWLogin or OAuth, so it uses the token-bearing
executor. `includelinkedinfo` exposes the source of linked fields, and
`skipColumnsInfo` returns names only, which matters on knowledge bases where
the full field listing is large.

EWUpsert creates or updates in one call, matched on a caller-chosen field.
Every parameter including credentials goes in the form body, so nothing
sensitive reaches the URL and record data has no request-line length ceiling.
Agiloft distinguishes the two outcomes by status — 201 created, 200 updated —
which the tool surfaces as a `created` flag, and answers 409 when the match
criteria are ambiguous, which is reported as such rather than as a generic
failure.

`table` becomes conditionally optional, since List Tables with no table is the
operation for users who do not yet know the names. EWLogin omits $table when
absent.

Route-count baseline moves 1094 -> 1096.

Author: waleedlatif1

apps/docs/content/docs/en/integrations/agiloft.mdx

@@ -160,6 +160,37 @@ Resolve the internal numeric ID of a choice-list value, for use in EWSelect WHER
 | --------- | ---- | ----------- |
 | `choiceLineId` | number | Internal numeric line ID of the choice value |
 
+### Agiloft List Tables
+
+List the tables and fields in an Agiloft knowledge base, to discover the logical names other operations need.
+
+#### Input
+
+| Parameter | Type | Required | Description |
+| --------- | ---- | -------- | ----------- |
+| `instanceUrl` | string | Yes | Agiloft instance URL \(e.g., https://mycompany.agiloft.com\) |
+| `knowledgeBase` | string | Yes | Knowledge base name |
+| `login` | string | Yes | Agiloft username |
+| `password` | string | Yes | Agiloft password |
+| `table` | string | No | Logical name of a single table to describe \(e.g., "contacts"\). Leave empty to list every table in the knowledge base. |
+| `includeLinkedInfo` | boolean | No | Include the source table and column behind each linked field |
+| `skipColumnsInfo` | boolean | No | Return table names only, omitting field details, for a much smaller response |
+
+#### Output
+
+| Parameter | Type | Description |
+| --------- | ---- | ----------- |
+| `tables` | array | Tables in the knowledge base with their fields |
+|   ↳ `label` | string | Display name of the table |
+|   ↳ `logicalName` | string | Logical table name, as other Agiloft operations expect it |
+|   ↳ `fields` | array | Fields on the table |
+|     ↳ `columnName` | string | Logical field name |
+|     ↳ `columnLabel` | string | Display label |
+|     ↳ `columnType` | string | SQL column type |
+|     ↳ `columnTypeDomain` | string | Agiloft field type |
+|     ↳ `isLinked` | boolean | Whether the field is a linked field |
+| `totalCount` | number | Number of tables returned |
+
 ### Agiloft Lock Record
 
 Lock, unlock, or check the lock status of an Agiloft record.
@@ -378,4 +409,27 @@ Update an existing record in an Agiloft table.
 | `id` | string | ID of the updated record |
 | `fields` | json | Updated field values of the record |
 
+### Agiloft Upsert Record
+
+Create an Agiloft record, or update it when a record already matches the given fields.
+
+#### Input
+
+| Parameter | Type | Required | Description |
+| --------- | ---- | -------- | ----------- |
+| `instanceUrl` | string | Yes | Agiloft instance URL \(e.g., https://mycompany.agiloft.com\) |
+| `knowledgeBase` | string | Yes | Knowledge base name |
+| `login` | string | Yes | Agiloft username |
+| `password` | string | Yes | Agiloft password |
+| `table` | string | Yes | Table name \(e.g., "contracts", "contacts.employees"\) |
+| `match` | string | Yes | Field used to find an existing record \(e.g., "ext_id"\). Pick something that identifies a record uniquely — if more than one record matches, Agiloft writes nothing and returns a conflict. |
+| `data` | string | Yes | Field values as a JSON object. On create these populate the new record; on update only the supplied fields change. |
+
+#### Output
+
+| Parameter | Type | Description |
+| --------- | ---- | ----------- |
+| `id` | string | ID of the created or updated record |
+| `created` | boolean | True when a new record was created, false when an existing one was updated |
+
 

apps/sim/app/api/tools/agiloft/create_record/route.test.ts

@@ -286,3 +286,154 @@ describe('documented EWREST response keys', () => {
     expect(data.output.choiceLineId).toBe(1)
   })
 })
+
+describe('EWTable', () => {
+  it('is KB-scoped: no $table, mandatory .json, and no inline credentials', async () => {
+    const { POST: LIST } = await import('@/app/api/tools/agiloft/list_tables/route')
+    arrange(res({ json: { success: true, result: { tables: [] } } }))
+
+    await LIST(
+      createMockRequest('POST', {
+        instanceUrl: baseBody.instanceUrl,
+        knowledgeBase: baseBody.knowledgeBase,
+        login: baseBody.login,
+        password: baseBody.password,
+        includeLinkedInfo: true,
+      })
+    )
+
+    const [url, , init] = inputValidationMockFns.mockSecureFetchWithPinnedIP.mock.calls[1]
+    expect(url).toContain('/ewws/EWTable/.json?')
+    expect(url).toContain('&includelinkedinfo=true')
+    expect(url).not.toContain('$table=')
+    expect(url).not.toContain('$password')
+    expect(init.headers.Authorization).toBe('Bearer tok-123')
+  })
+
+  it('narrows to one table with the plain table parameter, not $table', async () => {
+    const { POST: LIST } = await import('@/app/api/tools/agiloft/list_tables/route')
+    arrange(res({ json: { success: true, result: { tables: [] } } }))
+
+    await LIST(createMockRequest('POST', { ...baseBody, table: 'contacts' }))
+
+    const [url] = inputValidationMockFns.mockSecureFetchWithPinnedIP.mock.calls[1]
+    expect(url).toContain('&table=contacts')
+    expect(url).not.toContain('$table=')
+  })
+
+  it('flattens tables and fields into the documented shape', async () => {
+    const { POST: LIST } = await import('@/app/api/tools/agiloft/list_tables/route')
+    arrange(
+      res({
+        json: {
+          success: true,
+          result: {
+            tables: [
+              {
+                label: 'WMI Sample',
+                logicalName: 'wmi_sample',
+                fields: [
+                  {
+                    columnLabel: 'ID',
+                    columnName: 'id',
+                    columnType: 'BIGINT',
+                    columnTypeDomain: 'swautoincrementfield',
+                  },
+                  {
+                    columnLabel: 'Updated By',
+                    columnName: '_1794_full_name',
+                    columnType: 'VARCHAR',
+                    columnTypeDomain: 'swshorttextfield',
+                    isLinked: true,
+                  },
+                ],
+              },
+            ],
+          },
+        },
+      })
+    )
+
+    const response = await LIST(createMockRequest('POST', baseBody))
+    const data = (await response.json()) as {
+      output: { tables: Array<{ logicalName: string; fields: unknown[] }>; totalCount: number }
+    }
+
+    expect(data.output.totalCount).toBe(1)
+    expect(data.output.tables[0].logicalName).toBe('wmi_sample')
+    expect(data.output.tables[0].fields).toEqual([
+      {
+        columnName: 'id',
+        columnLabel: 'ID',
+        columnType: 'BIGINT',
+        columnTypeDomain: 'swautoincrementfield',
+        isLinked: false,
+      },
+      {
+        columnName: '_1794_full_name',
+        columnLabel: 'Updated By',
+        columnType: 'VARCHAR',
+        columnTypeDomain: 'swshorttextfield',
+        isLinked: true,
+      },
+    ])
+  })
+})
+
+describe('EWUpsert', () => {
+  const upsertBody = { ...baseBody, match: 'ext_id', data: '{"first_name":"John"}' }
+
+  it('sends every parameter in the form body, keeping credentials out of the URL', async () => {
+    const { POST: UPSERT } = await import('@/app/api/tools/agiloft/upsert_record/route')
+    inputValidationMockFns.mockSecureFetchWithPinnedIP.mockResolvedValueOnce(
+      res({ status: 201, text: "EWREST_id='353';" })
+    )
+
+    await UPSERT(createMockRequest('POST', upsertBody))
+
+    const calls = inputValidationMockFns.mockSecureFetchWithPinnedIP.mock.calls
+    // Inline-credential auth: a single call, no login/logout pair.
+    expect(calls).toHaveLength(1)
+    expect(calls[0][0]).toBe('https://example.agiloft.com/ewws/EWUpsert')
+    expect(calls[0][0]).not.toContain('?')
+
+    const sent = new URLSearchParams(calls[0][2].body as string)
+    expect(sent.get('$match')).toBe('ext_id')
+    expect(sent.get('$table')).toBe('contract')
+    expect(sent.get('$password')).toBe(PLACEHOLDER_PASSWORD)
+    expect(sent.get('first_name')).toBe('John')
+  })
+
+  it('reports 201 as a create and 200 as an update', async () => {
+    const { POST: UPSERT } = await import('@/app/api/tools/agiloft/upsert_record/route')
+
+    inputValidationMockFns.mockSecureFetchWithPinnedIP.mockResolvedValueOnce(
+      res({ status: 201, text: "EWREST_id='353';" })
+    )
+    let data = (await (await UPSERT(createMockRequest('POST', upsertBody))).json()) as {
+      output: { id: string; created: boolean }
+    }
+    expect(data.output).toEqual({ id: '353', created: true })
+
+    inputValidationMockFns.mockSecureFetchWithPinnedIP.mockResolvedValueOnce(
+      res({ status: 200, text: "EWREST_id='353';" })
+    )
+    data = (await (await UPSERT(createMockRequest('POST', upsertBody))).json()) as {
+      output: { id: string; created: boolean }
+    }
+    expect(data.output).toEqual({ id: '353', created: false })
+  })
+
+  it('surfaces a 409 as an ambiguous match rather than a generic failure', async () => {
+    const { POST: UPSERT } = await import('@/app/api/tools/agiloft/upsert_record/route')
+    inputValidationMockFns.mockSecureFetchWithPinnedIP.mockResolvedValueOnce(
+      res({ ok: false, status: 409, text: 'Multiple matching records found' })
+    )
+
+    const response = await UPSERT(createMockRequest('POST', upsertBody))
+    const data = (await response.json()) as { success: boolean; error?: string }
+
+    expect(data.success).toBe(false)
+    expect(data.error).toContain('more than one record matching "ext_id"')
+  })
+})

apps/sim/app/api/tools/agiloft/list_tables/route.ts

@@ -0,0 +1,102 @@
+import { createLogger } from '@sim/logger'
+import { toError } from '@sim/utils/errors'
+import { type NextRequest, NextResponse } from 'next/server'
+import { agiloftListTablesContract } from '@/lib/api/contracts/tools/agiloft'
+import { getValidationErrorMessage, parseRequest } from '@/lib/api/server'
+import { checkInternalAuth } from '@/lib/auth/hybrid'
+import { generateRequestId } from '@/lib/core/utils/request'
+import { withRouteHandler } from '@/lib/core/utils/with-route-handler'
+import type { AgiloftListTablesResponse, AgiloftTableField } from '@/tools/agiloft/types'
+import { buildListTablesUrl } from '@/tools/agiloft/utils'
+import { executeAgiloftRequest, readAlrestJson } from '@/tools/agiloft/utils.server'
+
+export const dynamic = 'force-dynamic'
+
+const logger = createLogger('AgiloftListTablesAPI')
+
+/** Shape of the `result` object EWTable returns. */
+interface EwTableResult {
+  tables?: Array<{
+    label?: string
+    logicalName?: string
+    fields?: Array<{
+      columnName?: string
+      columnLabel?: string
+      columnType?: string
+      columnTypeDomain?: string
+      isLinked?: boolean
+    }>
+  }>
+}
+
+export const POST = withRouteHandler(async (request: NextRequest) => {
+  const requestId = generateRequestId()
+
+  try {
+    const authResult = await checkInternalAuth(request, { requireWorkflowId: false })
+
+    if (!authResult.success || !authResult.userId) {
+      logger.warn(`[${requestId}] Unauthorized Agiloft list_tables attempt: ${authResult.error}`)
+      return NextResponse.json(
+        { success: false, error: authResult.error || 'Authentication required' },
+        { status: 401 }
+      )
+    }
+
+    const parsed = await parseRequest(
+      agiloftListTablesContract,
+      request,
+      {},
+      {
+        validationErrorResponse: (error) => {
+          logger.warn(`[${requestId}] Invalid request data`, { errors: error.issues })
+          return NextResponse.json(
+            {
+              success: false,
+              error: getValidationErrorMessage(error, 'Invalid request data'),
+              details: error.issues,
+            },
+            { status: 400 }
+          )
+        },
+      }
+    )
+    if (!parsed.success) return parsed.response
+    const params = parsed.data.body
+
+    /** EWTable must run under EWLogin or OAuth authorization. */
+    const result = await executeAgiloftRequest<AgiloftListTablesResponse>(
+      params,
+      (base) => ({
+        url: buildListTablesUrl(base, params),
+        method: 'GET',
+        headers: { Accept: 'application/json' },
+      }),
+      async (response) => {
+        const payload = await readAlrestJson<EwTableResult>(response)
+
+        const tables = (payload?.tables ?? []).map((table) => ({
+          label: table.label ?? '',
+          logicalName: table.logicalName ?? '',
+          fields: (table.fields ?? []).map(
+            (field): AgiloftTableField => ({
+              columnName: field.columnName ?? '',
+              columnLabel: field.columnLabel ?? '',
+              columnType: field.columnType ?? '',
+              columnTypeDomain: field.columnTypeDomain ?? '',
+              isLinked: field.isLinked === true,
+            })
+          ),
+        }))
+
+        return { success: true, output: { tables, totalCount: tables.length } }
+      }
+    )
+
+    return NextResponse.json(result)
+  } catch (error) {
+    logger.error(`[${requestId}] Error listing Agiloft tables:`, error)
+
+    return NextResponse.json({ success: false, error: toError(error).message }, { status: 500 })
+  }
+})