Asynchronous Workflows

Some workloads can benefit by processing data in an asynchronous workflow where multiple requests are batched up and sent to Fullstory at once. The general steps clients follow when using a Fullstory Server API that supports an asynchronous workflow are:

1. Send a batch of requests to Fullstory to initiate an asynchronous processing job
2. Use this job’s id to query for processing status
3. Once the job is complete, fetch successful results or any errors that occurred during processing

There are a couple of operations supported by the Fullstory API that support asynchronous workflows:

• Batch event import
• Batch user import

Using asynchronous workflows

Send a single payload with multiple (batched) requests to initialize a processing job using the batched request data.

POST /v2/users/batch

{
  "requests": [
    {
      "uid": "xyz123",
      "properties": { "rewards_status": "platinum"}
    },
    {
      "uid": "abc789",
      "properties": { "rewards_status": "gold" }
    },
    ...
  ]
}

The response will contain a job id that can be used to query status and retrieve final results once the job is complete.

{
  "job": {
    "id": "0xo123",
    "status": "PROCESSING",
    "created": "2023-04-18T14:36:11.123Z"
  }
}

The id can be used to poll job status.

GET /v2/users/batch/0xo123

{
  "imports": 104,
  "errors": 1,
  "job": {
    "id": "0xo123",
    "status": "COMPLETED",
    "created": "2023-04-18T14:36:11.123Z",
    "finished": "2023-04-18T15:36:11.123Z"
  }
}

Once the job is complete, the id can be used to fetch results

GET /v2/users/batch/0xo123/imports

{
  "results": [
    {
      "id": "456",
      "uid": "xyz123",
      "properties": { "rewards_status": "platinum"}
    },
    {
      "id": "876",
      "uid": "abc789",
      "properties": { "rewards_status": "gold" }
    },
    ...
  ],
  "total_records": "103",
  "next_page_token": "asd543"
}

or any errors that occurred during processing.

GET /v2/users/batch/0xo123/errors

{
  "results": [ {
    “message”: “The provided uid parameter can not be empty”
    “code” : “invalid_parameter”,
    “user”: {
      "uid": "",
      "properties": { "rewards_status": "silver" }
    }
  }],
  "total_records": "1",
  "next_page_token": null
}

Job Status

The job object will report one of these 3 statuses:

• PROCESSING - work is in progress
• FAILED - work has completed, with errors (possible partial success)
• COMPLETED - work is done, no errors

Job Fields

The job object will contain these fields:

• id (string) - The Id of the job
• status (enum) - The current job status
• created (string) - The time the job was started, in ISO-8601 UTC format
• finished (string) - The time the job was completed, in ISO-8601 UTC format. This field have a value if the job status is FAILED or COMPLETED, otherwise it is null.

Additional fields may be included in responses that contain a job object, for example the “imports” and “errors” fields that are included when a batch user or event operation has completed.