Integration Tickets: Async Processing & Polling

How it works

┌──────────┐          ┌──────────────┐          ┌──────────────┐
│  Client   │──POST──▶│  smenso API  │──202──▶  │  ticketId    │
│           │          │  (accepted)  │          │  returned    │
└──────────┘          └──────────────┘          └──────┬───────┘
                                                       │
     ┌─────────────────────────────────────────────────┘
     ▼
┌──────────┐   poll    ┌──────────────┐
│  Client   │──GET───▶ │  Status      │──▶ Processing / Completed / Failed
│           │◀─────────│  Endpoint    │
└──────────┘  result   └──────────────┘

1. You send a request (e.g., create tasks in bulk).
2. The API accepts the job and returns a ticketId (HTTP 202).
3. Processing happens in the background.
4. You poll the status endpoint with the ticketId until a terminal state is reached.

When do I get a ticketId?

You typically receive a ticketId when:

• The request contains multiple items (batch operations)
• The operation may take longer to process (e.g., creating/updating many records)
• Additional validation or business rules must be applied before completion

Not all endpoints are asynchronous. Synchronous endpoints return the final result immediately without a ticketId. You can check whether an endpoint uses tickets by looking at the Responses section in the API Reference.

Ticket lifecycle

Status endpoints

Poll the ticket status using the endpoint that matches your API format:

Example: Polling in JSON

curl -X GET \
  "https://{workspace}.smenso.cloud/skyisland/api/integration/status/json/{ticketId}" \
  -H "Authorization: Basic {your-api-token}"

Example response (completed)

{
  "id": "c3406426-6028-48da-ad4a-76865336ff0f",
  "endpoint": "Task",
  "status": "Success",
  "statusId": 10,
  "received": "2024-05-10T09:53:49+00:00",
  "started": "2024-05-10T09:53:52+00:00",
  "processed": "2024-05-10T09:56:41+00:00",
  "projects": {
    "created": 0,
    "modified": 0
  },
  "tasks": {
    "created": 100,
    "modified": 0
  }
}

Example response (failed)

{
  "id": "d4517937-9c6d-49eb-be5b-87976746aa08",
  "endpoint": "Task",
  "status": "Failed",
  "statusId": 20,
  "received": "2024-05-10T10:01:00+00:00",
  "errors": [
    "The Title field is required.",
    "Project with ID 'abc-123' not found."
  ]
}

Recommended polling strategy

Use exponential backoff to avoid unnecessary load while keeping response times short:

Stop polling when the ticket reaches a terminal state (Completed or Failed).

Timeout recommendations

If the ticket does not reach a terminal state within your timeout:

1. Log the ticketId for later investigation.
2. Treat the outcome as "unknown."
3. Retry the status check later or alert an operator.

Handling results

On success (Completed)

• Mark the job as successful in your system.
• Store any created/updated entity IDs returned in the response.
• Review warnings - even successful jobs may include informational messages about business rule adjustments.

On failure (Failed)

Inspect the error details and categorize them:

For batch operations, check whether the response includes item-level results to identify which specific records succeeded or failed.

📘

TempId mapping (XML API): When submitting batches via XML, you can include a client-side TempId for each item. The ticket response maps TempId values to created entity IDs, allowing you to correlate results with your source records.

Common pitfalls

Troubleshooting checklist

If a ticket fails:

1. ✅ Verify the API token is valid and has Admin permissions
2. ✅ Check that all required fields are present and correctly formatted
3. ✅ Confirm that all referenced GUIDs (project, user, type, etc.) exist in your workspace
4. ✅ Review business rules that might block the operation (e.g., absence overlap, locked time records)
5. ✅ Try resubmitting with a smaller batch to isolate the problematic item(s)
6. ✅ Check the API Reference for endpoint-specific validation rules