Skip to main content

Migrate from Integration Endpoints to Conversations (Alfresco)

This guide helps teams currently using the integration endpoints (single-shot + polling) migrate to the standard conversation endpoints (synchronous response, multi-turn ready).

Why migrate?​

  • No polling: the conversation endpoints return the answer synchronously.
  • No service user: the integration “service-to-service” model (with an external user passed explicitly) is removed.
  • Future-proof: conversations enable multi-turn, richer context, and improvements that won’t land in the legacy integration flow.

Quick mapping (old → new)​

Base URL note: examples below use {{baseUrl}}/agent/... for Agent API and {{baseUrl}}/qna/... for QnA API.

Workflow stepIntegration flow (legacy)Conversation flow (standard)Notes
Get agents by source IDGET /agent/integrations/agents?sourceId={sourceId}GET /agent/agents?sourceId={sourceId}In the standard endpoint, sourceId is optional, but you should keep it to preserve scoping.
Get agent by IDGET /agent/integrations/agents/{agentId}GET /agent/agents/{agentId}Response shape is the same (agent configuration).
Submit questionPOST /agent/integrations/agents/{agentId}/questionsPOST /qna/agents/{agentId}/conversationsStandard flow returns the first message (question + answer) immediately.
Poll for answerGET /qna/integrations/questions/{questionId}/answer?userId={externalUserId}RemovedPolling is replaced by synchronous response from POST /conversations.

Step-by-step migration​

Step 1 — List agents by sourceId​

GET {{baseUrl}}/agent/agents?sourceId={{sourceId}}
Authorization: Bearer {{accessToken}}
Hxp-Environment: {{environmentKey}}
Hxp-App: {{appKey}}

Response (example)

[
  {
    "id": "a3dbf6e1-3b89-4caa-9b16-0cfa1b1d5d5f",
    "name": "Alfresco Discovery Agent",
    "description": "Answers questions using Alfresco content",
    "modelName": "amazon.nova-micro-v1:0",
    "version": 3,
    "latest": true,
    "sourceIds": ["550e8400-e29b-41d4-a716-446655440000"],
    "accessRights": [
      { "id": "<user-id>", "type": "User" },
      { "id": "<user-group-id>", "type": "UserGroup" }
    ]
  }
]

Step 2 — Get agent by ID​

GET {{baseUrl}}/agent/agents/{{agentId}}
Authorization: Bearer {{accessToken}}
Hxp-Environment: {{environmentKey}}
Hxp-App: {{appKey}}

Response (example)

{
  "id": "a3dbf6e1-3b89-4caa-9b16-0cfa1b1d5d5f",
  "name": "Alfresco Discovery Agent",
  "description": "Answers questions using Alfresco content",
  "modelName": "amazon.nova-micro-v1:0",
  "version": 3,
  "latest": true,
  "sourceIds": ["550e8400-e29b-41d4-a716-446655440000"],
  "accessRights": [
    { "id": "<user-id>", "type": "User" },
    { "id": "<user-group-id>", "type": "UserGroup" }
  ],
  "staticFilterExpression": null,
  "dynamicFilterTemplate": null,
  "knowledgeGraphDomainId": null
}

Step 3 — Submit question by starting a conversation (synchronous)​

This is the key migration step: replace POST /integrations/.../questions + polling with a single POST /conversations call.

Request​

POST {{baseUrl}}/qna/agents/{{agentId}}/conversations
Authorization: Bearer {{accessToken}}
Hxp-Environment: {{environmentKey}}
Hxp-App: {{appKey}}
Content-Type: application/json

{
  "question": "What is the status of my latest order?",
  "contextObjectIds": [
    "123e4567-e89b-12d3-a456-426614174000"
  ]
}

Response​

You get both the new conversation metadata and the first message.

{
  "conversation": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "name": "Conversation",
    "description": null,
    "lastModified": "2026-04-07T10:30:00Z"
  },
  "message": {
    "id": "f1e2d3c4-b5a6-7890-1234-567890abcdef",
    "question": "What is the status of my latest order?",
    "answer": "Based on the documents, your latest order is currently processing.",
    "status": "Answered",
    "agentVersion": 3,
    "dateCreated": "2026-04-07T10:30:00Z",
    "dateAnswered": "2026-04-07T10:30:02Z",
    "documentReferences": [],
    "graphDocumentReferences": [],
    "feedback": null,
    "staticFilter": null,
    "dynamicFilter": null
  }
}

(Optional) Step 4 — Multi-turn follow-up questions​

If you previously used the integrations flow for single-shot only, you can stop at Step 3.

If you want multi-turn follow-ups, call ContinueConversation with the conversationId returned from Step 3.

POST {{baseUrl}}/qna/agents/{{agentId}}/conversations/{{conversationId}}/messages
Authorization: Bearer {{accessToken}}
Hxp-Environment: {{environmentKey}}
Hxp-App: {{appKey}}
Content-Type: application/json

{
  "question": "Can you summarize the last update?",
  "contextObjectIds": []
}

Before vs. after (legacy integrations → conversations)​

Before: submit + poll​

1) Submit a single-shot question (integration flow)​

POST {{baseUrl}}/agent/integrations/agents/{{agentId}}/questions
Authorization: Bearer {{accessToken}}
Hxp-Environment: {{environmentKey}}
Hxp-App: {{appKey}}
Content-Type: application/json

{
  "question": "What is the status of my latest order?",
  "userId": "12345678-90ab-cdef-1234-567890abcdef",
  "contextObjectIds": [
    "123e4567-e89b-12d3-a456-426614174000"
  ]
}

Response (202 Accepted)

{ "questionId": "550e8400-e29b-41d4-a716-446655440000" }

2) Poll for the answer (integration flow)​

GET {{baseUrl}}/qna/integrations/questions/{{questionId}}/answer?userId={{externalUserId}}
Authorization: Bearer {{accessToken}}
Hxp-Environment: {{environmentKey}}
Hxp-App: {{appKey}}

After: single synchronous call​

Replace both calls above with:

POST {{baseUrl}}/qna/agents/{{agentId}}/conversations
Authorization: Bearer {{accessToken}}
Hxp-Environment: {{environmentKey}}
Hxp-App: {{appKey}}
Content-Type: application/json

{
  "question": "What is the status of my latest order?",
  "contextObjectIds": ["123e4567-e89b-12d3-a456-426614174000"]
}

The 200 OK response contains the answer immediately (see Step 3 response example).

Auth differences (what changes for Alfresco)​

Integration flow (legacy)​

  • Requires an access token with hxp.integrations scope.
  • Uses a service user and passes an external user identity explicitly (e.g. externalUserId in the integration request, and externalUserId query parameter when fetching answers).
  • Used to support polling for the answer.

Conversation flow (standard)​

  • Requires a standard user JWT token — no additional scope beyond the HxP subscription is needed.
  • No service user requirement.
  • User identity is taken from the JWT token — no userId/externalUserId parameter in the API contract.

Code change checklist (consumer-side)​

  • Replace /agent/integrations/agents with /agent/agents.
  • Replace /agent/integrations/agents/{agentId}/questions with /qna/agents/{agentId}/conversations.
  • Remove polling logic (drop GET /qna/integrations/questions/{id}/answer).
  • Stop sending userId in the request body; use the real user token instead.
  • (Optional) store conversationId and use it for follow-up messages.