Server

Server

Provides various methods to access the server-side data API.

Specifying Column Names

Many server calls support filtering, grouping and sorting. In order to be compatible with the API's data Sieve, best-practice is to wrap any variable names in braces: {var}.

Filter format

The filter argument is a string that supports the same expressions as the underlying database engine's WHERE clause. Note that the specific keyword format depends on the SQL dialect support by the backend engine. The API includes some helper methods to make this easier e.g. getSqlDateFormat

{var1} > 5 AND {var2} BETWEEN 1 AND 5

Sort format

The sort argument is a string that supports the same expressions as the underlying database engine's ORDER BY clause. The default sort order is ASC.

{var1}, {var2} DESC, {var3} ASC

Group format

A comma-delimited set of variable names to group the result by. Generating sub-total results from groupings is controlled via the rollup and cube options.

{var1},{var2}

Constructor

new Server(api)

Source:
Copyright:
  • (c) 2021 TLF Research Ltd.
Example
const server = new Server("api/v1");
Parameters:
Name Type Description
api string

Path to the API handler's relative path, excluding the server's host name.
Returns:

A new Server instance.

Members

(static, constant) API_ENDPOINT :string

Source:

Path to the API handler's relative path, excluding the server's host name (as provided to the Server's constructor).

Type:
  • string

(static, constant) NO_CACHE :bool

Source:

When used on a method that supports it will disable the client-side cache.

Type:
  • bool

Globals :object

Source:

Store for any Global objects

Type:
  • object

Methods

deleteAIAttachment(project, id, optionsopt) → {Promise.<void>}

Source:

Removes a chat attachment.

Safe to call more than once, and safe to call for something already expired: the server answers 204 either way. Nothing depends on this being called - abandoned attachments are collected automatically - it simply frees the space sooner.

Parameters:
Name Type Attributes Description
project object

The project the chat session belongs to.
id string

The attachment ID.
options object <optional>

Optional settings.

Properties
Name Type Attributes Default Description
keepalive bool <optional>
 false

Set true to let the request outlive the page, for cleanup fired from a pagehide handler.
Returns:
Type
Promise.<void>

formatQuery(query) → {string}

Source:

Formats an object containing query parameters into a string that can be appended to a URL.

Parameters:
Name Type Description
query object
Returns:
Type
string

getAIAssistantCapabilities(tieropt, cacheopt) → {jQuery.Deferred}

Source:

Fetches what the AI assistant will accept as an attachment, and the limits that apply.

Use this to build a file dialog's accept filter and to refuse a hopeless file before uploading it. The 'vision' and 'documents' flags depend on the model in use, and the accept lists are filtered to match - a model that cannot read images returns an empty accept.image.

When 'enabled' is false, attachments are switched off on the server and no attach control should be offered at all.

Example
server.getAIAssistantCapabilities().done(caps => {
    if (!caps.enabled) return;
    input.accept = [...caps.accept.image, ...caps.accept.document, ...caps.accept.text].join(',');
});
Parameters:
Name Type Attributes Default Description
tier string <optional>

Model tier to report on - 'fast', 'balanced' or 'powerful'.
cache bool <optional>
 true

If false, the query will include a timestamp to override any server-side caching.
Returns:
Type
jQuery.Deferred

getAIAttachmentContent(project, id, optionsopt) → {Promise.<Blob>}

Source:

Fetches a chat attachment's content as a Blob, for previewing it.

Deliberately a fetch rather than a URL to point an or at. The portal is served from a different origin to the API, so an element load would only send the API session cookie if it were marked SameSite=None; and when a login has lapsed the API answers with a redirect, which an element load reports as nothing more than a broken image. Fetching sends credentials explicitly and lets an expired attachment be told apart from an expired session.

Parameters:
Name Type Attributes Description
project object

The project the chat session belongs to.
id string

The attachment ID.
options object <optional>

Optional settings.

Properties
Name Type Attributes Default Description
preview bool <optional>
 false

If true, a large text attachment is capped at the first 64 KB - all a preview shows in any case.
signal AbortSignal <optional>

Signal to abort the fetch.
Throws:

With 'expired' set to true when the attachment is no longer available.

Type
Error
Returns:
Type
Promise.<Blob>

getAIModels(cacheopt) → {jQuery.Deferred}

Source:

Asynchronously fetches information about any available AI models.

Examples
server.getAIModels().done(models => {
    // models in here
}).catch(function() {
    // something went wrong
});
models = "[
 {
     "ModelArn": "arn:aws:bedrock:eu-west-2::foundation-model/amazon.titan-text-lite-v1:0:4k",
     "ModelId": "amazon.titan-text-lite-v1:0:4k",
     "CustomizationsSupported": [],
     "InferenceTypesSupported": [
         "PROVISIONED"
     ],
     "InputModalities": [
     "TEXT"
     ],
     "ModelLifecycle": {
         "Status": "ACTIVE"
     },
     "ModelName": "Titan Text G1 - Lite",
     "OutputModalities": [
         "TEXT"
     ],
  "ProviderName": "Amazon",
  "ResponseStreamingSupported": true
 },
 ...
];
Parameters:
Name Type Attributes Default Description
cache bool <optional>
 true

If false, the query will include a timestamp to override any server-side caching.
Returns:
Type
jQuery.Deferred

getAIRAGResponse(kbID, modelID, prompt, temperature, sessionID, cacheopt) → {jQuery.Deferred}

Source:

Fetches a Retrieval Augmentation Generation (RAG) response from a model via a knowledge base.

Examples
server.getAIRAGResponse('my-model', 'my-knowledge-base', 'hello world', 0.6).done(resp => {
    // resp in here
}).catch(function() {
    // something went wrong
});
resp = ""
Parameters:
Name Type Attributes Default Description
kbID string

The ID of the knowledge base to query.
modelID string

The ID of the foundation model used to process the RAG request.
prompt string

The prompt to use.
temperature number

The LLM temperature.
sessionID string

The chat session ID (used to maintain context).
cache bool <optional>
 true

If false, the query will include a timestamp to override any server-side caching.
Returns:
Type
jQuery.Deferred

getAIResponse(projectID, prompt, tieropt, cacheopt) → {jQuery.Deferred}

Source:

Fetches a non-streaming AI response for a project prompt. Responses are cached server-side per project, tier, and prompt.

Example
server.getAIResponse(123, 'Summarise this project').done(resp => {
    console.log(resp);
}).catch(function() {
    // something went wrong
});
Parameters:
Name Type Attributes Default Description
projectID number

The project ID.
prompt string

The prompt to send.
tier string <optional>
 'balanced'

Model tier: 'fast', 'balanced', or 'powerful'.
cache bool <optional>
 true

If false, the query will include a timestamp to bypass caching.
Returns:
Type
jQuery.Deferred

getAPIDebugMode(debug) → {jQuery.Deferred}

Source:

Gets the debug mode of the API.

Parameters:
Name Type Description
debug bool

Whe true the server API is in debug mode.
Returns:
Type
jQuery.Deferred

getHotalertHistory(name, project, filteropt, cacheopt) → {jQuery.Deferred}

Source:

Asynchronously fetches stats about the Hot Alerts status history pertaining to the given Project. Requires a single bool Variable in the dataset that has been assigned to the hotalert category.

Examples
server.getHotalertHistory('myquery', proj).done(function (hotalertHistory) {
   // hotalertHistory in here
}).catch(function() {
   // Something went wrong
});;
hotalertHistory = {
   "dates": [
      "2021-03-01",
      "2021-03-02",
      "2021-03-03",
   ],
   "history": {
      "Open": [
         100,
         99,
         97
      ],
      "Pending": [
         0,
         1,
         1
      ],
      "Closed": [
         0,
         0,
         2
      ]
   }
};
Parameters:
Name Type Attributes Default Description
name string

Name of the dataset
project object

Project to use
filter string <optional>

Filter to apply
cache bool <optional>
 true

If false, the query will include a timestamp to override any server-side caching.
Returns:

The response object passed to the done handler is a JSON object of a Hotalert History object containing the following keys:

key type description
dates array An array of dates that contain HotAlerts.
history object An object whose keys match the possible statuses of a HotAlert for this Project. Each key's value consists of an array of counts, one for each of the dates in the dates array.
Type
jQuery.Deferred

getHotAlertResponses(name, project, filteropt, groupsopt, cacheopt) → {jQuery.Deferred}

Source:

Asynchronously fetches an array of responses that triggered a Hot Alert. Requires a single bool Variable in the dataset that has been assigned to the hotalert category. This method returns responses that have the Variable set to true (1 in MySQL).

This method is a special-case of the getResponses method. It exists because its API endpoint is assigned to the hotalert API category, rather than the more generic responses category. Also it limits the returned response data to those variables that have no assigned category, or are in one or more of the following categories: response_date, respondent, hotalert.

So a user could be allowed to call it to see HotAlert data, but not have access to the full getResponses endpoint's data.

Examples
server.getHotAlertResponses("myquery", proj).done(function(hotalerts) {
   // Hot alerts in here
}).catch(function() {
   // Something went wrong
});
hotalerts = {
   "total": "12345",
   "truncated": false,
   "rows": [
      {
         "foo": 45,
         "bar": "Some hotalert data",
         "baz": 271,
         "sat1": 8,
         "status": "Open|Resolved|Closed",
         "status_changed": "2021-02-19 12:02:04.25409345+00:00|2021-02-19 12:01:16.679823054+00:00|2021-02-19 12:02:10.119221324+00:00"
      }
   ]
};
Parameters:
Name Type Attributes Default Description
name string

Name of the dataset
project object

Project to use
filter string <optional>
 null

Filter to apply to the Responses
groups array | string <optional>
 null

Group by expressions
cache bool <optional>
 true

If false, the query will include a timestamp to override any server-side caching.
Returns:

The response object passed to the done handler is a JSON object that contains the following keys:

key type description
sql string If the server is running in debug mode this shows the SQL that was used to generate the resultset.
total number Total number of records in the dataset - required by some UI widgets to determine paging. Not necessarily the number of rows returned.
group string CSV of the names of the variables that were grouped, as provided on the group parameter.
rows object An array of objects. Each object repressnts a single response. The response properties are in alphabetical order.
truncated boolean If true the number of rows generated exceeded the maximum number of rows that can be send by the server. In this case the rows key contains the maximum allowed, and this key is set to true.
Type
jQuery.Deferred

getHotalertStats(name, project, filteropt, cacheopt) → {jQuery.Deferred}

Source:

Asynchronously fetches stats about the Hot Alerts pertaining to the given Project.

Examples
server.getHotalertStats('myquery', proj).done(function (hotalertStats) {
   // hotalertStats in here
}).catch(function() {
   // Something went wrong
});;
hotalertStats = [
   {
      "category": "null",
      "statusID": 0,
      "total": 40
   },
   {
      "category": "Pending",
      "statusID": 0,
      "total": 16
   },
   {
      "category": "Resolved",
      "statusID": 0,
      "total": 12
   },
   {
      "category": "Closed",
      "statusID": 0,
      "total": 16
   }
];
Parameters:
Name Type Attributes Default Description
name string

Name of the dataset
project object

Project to use
filter string <optional>

Filter to apply to the Responses
cache bool <optional>
 true

If false, the query will include a timestamp to override any server-side caching.
Returns:

The response object passed to the done handler is a JSON arry of Hotalert Stats objects containing the following keys:

key type description
category string Each possible Hotalert Status appears in its own stats Category.
pstatusID number ID of the related Hotalert Status
total number The total number of Notes in this stats Category,
Type
jQuery.Deferred

getInfo(cacheopt) → {jQuery.Deferred}

Source:

Asynchronously fetches metadata about the API server, including the maximum number of result rows that will be returned, the backend database engine used, and a list of supported aggregator functions that may be used with the getResponsesAggregate method.

Examples
server.getInfo().done(info => {
    // info in here
}}.catch(function() {
    // something went wrong
})
info = {
   "databaseType": "sqlite3",
   "maxResults": 10000,
   "aggregators": [
     {
     "name": "Average",
     "function": "avg",
     "type": "float",
     "description": "Calculates the average for each of the given columns"
     },
     {
     "name": "Count",
     "function": "count",
     "type": "int",
     "description": "Counts all non-null responses for the given columns"
     },
     ...
   ]};
});
Parameters:
Name Type Attributes Default Description
cache bool <optional>
 true

If false, the query will include a timestamp to override any server-side caching by the client.
Returns:
Type
jQuery.Deferred

getNotes(name, project, participantID, cacheopt) → {jQuery.Deferred}

Source:

Asynchronously fetches an array of notes associated with the given Participant.

Examples
server.getNotes('myquery', proj, participantID).done(function (notes) {
   // Notes in here
}).catch(function() {
   // Something went wrong
});;
notes = [
   {
      "id": 1,
      "participant_id": 1,
      "user": "Joe Bloggs",
      "type": "comment",
      "value": "test",
      "status_id": 10,
      "created": "2021-02-19T12:01:13.280330725Z"
   },
   {
      "id": 2,
      "participant_id": 1,
      "user": "Joe Bloggs",
      "type": "status-change",
      "value": "Open",
      "status_id": 11,
      "created": "2021-02-19T12:01:16.679823054Z"
   }
   ...
];
Parameters:
Name Type Attributes Default Description
name string

Name of the dataset
project object

Project to use
participantID number

ID of the Participant to inspect
cache bool <optional>
 true

If false, the query will include a timestamp to override any server-side caching.
Returns:

The response object passed to the done handler is a simple JSON array of Note objects.

Type
jQuery.Deferred

getNoteStatuses(name, project, cacheopt) → {jQuery.Deferred}

Source:

Asynchronously fetches an array of Note Statuses that apply to the given Project.

Examples
server.getNoteStatuses('myquery', proj).done(function (noteStatuses) {
   // noteStatuses in here
}).catch(function() {
   // Something went wrong
});;
noteStatuses = [
   {
      "id": 29,
      "project_id": 1,
      "value": "Open",
      "seq": 0
   },
   {
      "id": 30,
      "project_id": 1,
      "value": "Pending",
      "seq": 1
   },
   {
      "id": 31,
      "project_id": 1,
      "value": "Resolved",
      "seq": 2
   },
   {
      "id": 32,
      "project_id": 1,
      "value": "Closed",
      "seq": 3
   }
];
Parameters:
Name Type Attributes Default Description
name string

Name of the dataset
project object

Project to use
cache bool <optional>
 true

If false, the query will include a timestamp to override any server-side caching.
Returns:

The response object passed to the done handler is a JSON arry of NoteStatus objects containing the following keys:

key type description
id number ID of the NoteStatus
project_id number ID of the related Project
value number The text label associated with the NoteStatus
seq number A sequence number that indicates the logical progression of a Note's status. Dropdowns should display statuses in ascending order of this sequence.
Type
jQuery.Deferred

getPFI(project, cacheopt) → {jQuery.Deferred}

Source:

Asynchronously fetches the PFI associated with the given Project for the logged-in User. PFIs are returned as a single object whose value key is a collection of PFIs separated by pipe characters.

Examples
server.getPFI(project).done(function (data) {
   // PFI in here
}).catch(function() {
   // Something went wrong
});;
data = {
   "pfi": {
      "participant_id": "user@example.com",
      "user": "user@example.com",
      "type": "pfi",
      "value": "This is PFI one|This is PFI 2|This is PFI three!",
      "status_id": 0,                                                   // This is always zero for a PFI
      "created": "2023-09-28T14:40:00Z"
   },
   "business_unit": "My Business Unit",
   "operating_company": "My Company",
   "job_title": "My Job Title"
},
Parameters:
Name Type Attributes Default Description
project object

Project to use
cache bool <optional>
 true

If false, the query will include a timestamp to override any server-side caching.
Returns:

The response object passed to the done handler is a simple JSON object containing the User's PFIs for this Project.

Type
jQuery.Deferred

getPFIs(project, cacheopt) → {jQuery.Deferred}

Source:

Asynchronously fetches all PFIs in the system. PFIs are returned as an array of PFI objects.

Examples
server.getPFI(project).done(function (pfis) {
   // PFIs in here
}).catch(function() {
   // Something went wrong
});;
pfis = [
{
   "participant_id": "user@example.com",
   "user": "user@example.com",
   "type": "pfi",
   "value": "This is PFI one|This is PFI 2|This is PFI three!",
   "status_id": 0,                                                   // This is always zero for a PFI
   "created": "2023-09-28T14:40:00Z"
}.
{
   "participant_id": "user2@example.com",
   "user": "user2@example.com",
   "type": "pfi",
   "value": "This is my action|This is anothe one",
   "status_id": 0,                                                   // This is always zero for a PFI
   "created": "2023-09-29T17:40:23Z"
}.
],
Parameters:
Name Type Attributes Default Description
project object

Project to use
cache bool <optional>
 true

If false, the query will include a timestamp to override any server-side caching.
Returns:

The response object passed to the done handler is a simple JSON object containing the User's PFIs for this Project.

Type
jQuery.Deferred

getPresentationTemplate(name) → {object}

Source:

Returns the requested presentation template

Parameters:
Name Type Description
name string

Name of the template to fetch
Returns:

Template object

Type
object

getProjectCategories(project, offsetopt, limitopt, filteropt, cacheopt) → {jQuery.Deferred}

Source:

Asynchronously fetches the coding categories of every coded Response.

This method is a special-case of the getResponses method. The column set is fixed server-side, so the coding variable can stay marked as not exportable - keeping it out of getResponses and every CSV export - while still being readable here.

Examples
server.getProjectCategories(proj).done(function(responses) {
   // Category data in here
}).catch(function() {
   // Something went wrong
});
responses = {
   "total": 1234,
   "rows": [
   {
      "coding": "{\"comm1\":{\"+Staff were helpful\":{}}}",
      "id": 1,
      "month": "2026-04-18 06:00:37"
   },
   ...
   ],
   "truncated": false
};
Parameters:
Name Type Attributes Default Description
project object

Project to inspect
offset number <optional>
 0

Offset of first Response to fetch (for server-side paging)
limit number <optional>
 Number.MAX_SAFE_INTEGER

Maximum number of Responses to return (for server-side paging)
filter string <optional>

Filter to apply to the Responses. This can only ever narrow the resultset - the server ANDs it onto its own clauses rather than replacing them.
cache bool <optional>
 true

If false, the query will include a timestamp to override any server-side caching.
Returns:

The response object passed to the done handler has the same keys as getResponses. Each row holds the coding variable and the Project's own date variable - whichever variable the Project places in the response_date category - so callers never need to name either column.

Type
jQuery.Deferred

getProjects(ids, cacheopt) → {jQuery.Deferred}

Source:

Asynchronously fetches metadata about one or more Projects. The response also includes information about all the Variables associated with the Project.

Examples
server.getProjects([1]).done(projects => {
    // projects in here
}).catch(function() {
    // something went wrong
});
projects = {
   "client": "Project Client",
   "id": 1,
   "name": "Project Demo",
   "stopwords": "Project,Demo",
   "vars": {
      "var1": {
      "categories": [
         "respondent"
      ],
      "comments": "",
      "exportable": true,
      "falsevalue": "No",
      "id": 1,
      "label": "Project Variable 1",
      "name": "var1",
      "project": 1,
      "truevalue": "Yes",
      "type": "int"
      },
      ...
   ]
   };
});
Parameters:
Name Type Attributes Default Description
ids Array.<number>

IDs of the Project(s) to fetch
cache bool <optional>
 true

If false, the query will include a timestamp to override any server-side caching.
Returns:
Type
jQuery.Deferred

getProjectVar(varName, varName) → {any|undefined}

Source:

Returns the value of the given variable or undefined if it doesn't exist.

Parameters:
Name Type Description
varName Object

Project to search.
varName string

Name of the date variable to format
Returns:

Value of requested variable.

Type
any | undefined

getQueryParameter(param) → {string}

Source:

Returns the given parameter from the URL query string (as IE11 doesn't support URLSearchParams)

Parameters:
Name Type Description
param string
Returns:
Type
string

getResponses(project, propsopt, sortopt, offsetopt, limitopt, sampleopt, filteropt, cacheopt) → {jQuery.Deferred}

Source:

Asynchronously fetches an array of Survey Responses.

Examples
server.getResponses(proj).done(function(responses) {
   // Response data in here
}).catch(function() {
   // Something went wrong
});
responses = {
   "total": 12345,
   "rows": [
   {
      "accountnumber": 1,
      "allowcontact": 1,
      "branch": "Branch 1",
      "comm1": "A Comment",
      "comm2": null,
      "comm3": "Another Comment",
      "hadproblem": 1,
      "id": 1,
      "imp1": 3,
      "imp2": 7,
      "imp3": 8,
      "merchant": "Company Ltd.",
      "ovsat": 10,
      "purchased": 0,
      "region": "A Region",
      "respondentcompany": "Respondent Ltd.",
      "respondentname": "John Smith",
      "sat1": 7,
      "sat2": 7,
      "sat3": 8,
      "satindex": 68.90479780129151,
      "touchpointdate": "2020-01-18 06:00:37"
   },
   ...
   ],
   "truncated": false
};
Parameters:
Name Type Attributes Default Description
project object

Project to inspect
props Array.<string> <optional>
 null

Array of properties to return in each Response. Default is to fetch all properties.
sort string <optional>
 null

Order in which to return the Responses
offset number <optional>
 0

Offset of first Response to fetch (for server-side paging)
limit number <optional>
 Number.MAX_SAFE_INTEGER

Maximum number of Responses to return (for server-side paging)
sample number <optional>
 0

Request a random sample of Responses
filter string <optional>

Filter to apply to the Responses
cache bool <optional>
 true

If false, the query will include a timestamp to override any server-side caching.
Returns:

The response object passed to the done handler is a JSON object that contains the following keys:

key type description
sql string If the server is running in debug mode this shows the SQL that was used to generate the resultset.
total number Total number of records in the dataset - required by some UI widgets to determine paging. Not necessarily the number of rows returned.
rows object An array of objects. Each object repressnts a single response. The response properties are in alphabetical order.
truncated boolean If true the number of rows generated exceeded the maximum number of rows that can be send by the server. In this case the rows key contains the maximum allowed, and this key is set to true.
Type
jQuery.Deferred

getResponsesAggregate(name, project, aggregator, varNamesopt, filteropt, groupsopt, sortopt, rollupopt, cubeopt, havingopt, rollingopt, baseopt, splitsopt, cacheopt, anonymizeopt) → {jQuery.Deferred}

Source:

Asynchronously fetches the result of applying an aggregate function, like AVG or COUNT, to one or more Variables. Different backend database engines support different aggregators. The getInfo method returns a list of supported aggregators. The function property of each supported aggregator from getInfo may be provided in the aggregator property here.

Examples
server.getResponsesAggregate("myquery", proj, "avg", "ovsat", null, "region").done(function(responses) {
   // Response data in here
}).catch(function() {
   // Something went wrong
});
responses = {
   "name": "avg",
   "tag": "myquery",
   "vars": "ovsat",
   "group": "region",
   "truncated": false,
   "rows": [
      {
         "ovsat": 6.925230769230769,
         "region": "East Region"
      },
      {
         "ovsat": 8.563069685386651,
         "region": "North Region"
      },
      {
         "ovsat": 7.721746031746032,
         "region": "South Region"
      },
      {
         "ovsat": 7.334545454545455,
         "region": "West Region"
      }
   ]
};
Parameters:
Name Type Attributes Default Description
name string

Name of the dataset (included in the returned results in the response's tag key)
project object

Project to use
aggregator string

Aggregator function to apply (if the aggregator requires a value then append it after a ':' e.g. lte:4)
varNames string | array <optional>
 null

Survey variable(s) to inspect
filter string <optional>
 null

Filter to apply to the Responses
groups string | array <optional>
 null

Survey variable(s) to group by
sort string <optional>
 null

Sort order to apply
rollup boolean <optional>
 false

When true, and we are grouping, then the results will include summary rows
cube boolean <optional>
 false

When true, and we are grouping, then the results will include all combinations of summary rows
having string <optional>
 null

Adds an SQL HAVING clause to the resultset
rolling string <optional>
 null

Rolling period of the form number[d|w|m|y](varName) e.g. 3m(date) or ytd(varName,startMonth)
base string <optional>
 null

Base expression to to be used (only applicable to the prop aggregator) e.g. var1=1 AND var2=1
splits string <optional>
 null

Split ranges to to be used (only applicable to the split aggregator) e.g. 25,50,75,100 to create 4 ranges: 0-25, 25-50, 50-75, 75-100
cache bool <optional>
 true

If false, the query will include a timestamp to override any server-side caching.
anonymize bool <optional>
 false

If true, and the Sieve is in Auto mode, the Sieve will always be switched OFF for aggregator queries, but results outside the scope of the Sieve will be anonymized.
Returns:

The response object passed to the done handler is a JSON object that contains the following keys:

key type description
sql string If the server is running in debug mode this shows the SQL that was used to generate the resultset.
name string The name of the aggregator function.
tag string The value of the name parameter.
vars string CSV of the names of the variables that were inspected, as provided on the varNames parameter.
group string CSV of the names of the variables that were grouped, as provided on the group parameter.
rows object An array of objects. Each object repressnts a single response. The response properties are in alphabetical order.
truncated boolean If true the number of rows generated exceeded the maximum number of rows that can be send by the server. In this case the rows key contains the maximum allowed, and this key is set to true.
anonymize boolean If true the Sieve will NOT anonymize responses, but any Sieved fields will be set to blank.
Type
jQuery.Deferred

getResponsesDistinct(project, varName, filteropt, groupsopt, cacheopt) → {jQuery.Deferred}

Source:

Asynchronously fetches an array of distinct response values for a given variable. This is often used to dynamically populate a dropdown.

Examples
server.getResponsesDistinct(proj, "region").done(function(responses) {
   // Response data in here
}).catch(function() {
   // Something went wrong
});
responses = {
   "total": 4,
   "rows": [
      {
      "region": "West Region"
      },
      {
      "region": "North Region"
      },
      {
      "region": "South Region"
      },
      {
      "region": "East Region"
      }
   ],
   "truncated": false
};
Parameters:
Name Type Attributes Default Description
project object

Project to use
varName string

Survey variable to inspect
filter string <optional>
 null

Filter to apply to the Responses
groups array | string <optional>
 null

Group by expressions
cache bool <optional>
 true

If false, the query will include a timestamp to override any server-side caching.
Returns:

The response object passed to the done handler is a JSON object that contains the following keys:

key type description
total number Total number of records in the dataset - required by some UI widgets to determine paging. Not necessarily the number of rows returned.
rows object An array of objects. Each object repressnts a single response. The response properties are in alphabetical order.
truncated boolean If true the number of rows generated exceeded the maximum number of rows that can be send by the server. In this case the rows key contains the maximum allowed, and this key is set to true.
Type
jQuery.Deferred

getResponsesThemesByFrequency(name, project, filteropt, cacheopt) → {jQuery.Deferred}

Source:

Asynchronously fetches a list of themes by combining all the given text-based Project Response variables (typically comment responses). Returns a list of themes and the IDs of the associated responses.

Examples
server.getResponsesThemesByFrequency("myquery", proj).done(function(themes) {
   // Themes data in here
}).catch(function() {
   // Something went wrong
});
themes = 'These are the main themes contained in the comments.'};
Parameters:
Name Type Attributes Default Description
name string

Name of the dataset (included in the tag key in the returned results)
project object

Project to use
filter string <optional>
 null

Filter to apply to the responses before determining the themes
cache bool <optional>
 true

If false, the query will include a timestamp to override any server-side caching.
Returns:
Type
jQuery.Deferred

getResponsesThemesByImpact(name, project, varName, filteropt, cacheopt) → {jQuery.Deferred}

Source:

Asynchronously fetches a list of themes by combining all the given text-based Project Response variables (typically comment responses). Returns a list of themes, the number of Fairly/Very Satisifed responses, and the IDs of the associated responses.

Examples
server.getResponsesThemesByImpact("myquery", proj).done(function(themes) {
   // Themes data in here
}).catch(function() {
   // Something went wrong
});
themes = 'These are the main themes contained in the comments.'};
Parameters:
Name Type Attributes Default Description
name string

Name of the dataset (included in the tag key in the returned results)
project object

Project to use
varName string

Overall sat variable to use to calculate the impact
filter string <optional>
 null

Filter to apply to the responses before determining the themes
cache bool <optional>
 true

If false, the query will include a timestamp to override any server-side caching.
Returns:
Type
jQuery.Deferred

getResponsesWordCount(name, project, varNames, filteropt, cacheopt) → {jQuery.Deferred}

Source:

Asynchronously fetches a list of word counts by combining all the given text-based Project Response variables (typically comment responses). The analysis will exclude any stopwords defined in the Project.

Examples
server.getResponsesWordCount("myquery", proj, ["comm1", "comm2"]).done(function(wordcounts) {
   // Word count data in here
}).catch(function() {
   // Something went wrong
});
wordcounts = {
   "name": "wc",
   "tag": "myquery",
   "vars": "comm1,comm2",
   "group": "",
   "truncated": false,
   "rows": [
      {
         "foo": 45,
         "bar": 5,
         "baz": 271,
      }
   ]
};
Parameters:
Name Type Attributes Default Description
name string

Name of the dataset (included in the tag key in the returned results)
project object

Project to use
varNames string | array

Survey variable(s) to inspect
filter string <optional>
 null

Filter to apply to the Responses
cache bool <optional>
 true

If false, the query will include a timestamp to override any server-side caching.
Returns:

The response object passed to the done handler is a JSON object that contains the following keys:

key type description
sql string If the server is running in debug mode this shows the SQL that was used to generate the resultset.
name string The name of the aggregator function - always wc.
tag string The value of the name parameter.
vars string CSV of the names of the variables that were inspected, as provided on the varNames parameter.
group string CSV of the names of the variables that were grouped, as provided on the group parameter.
rows object An array of objects. Each object repressnts a single response. The response properties are in alphabetical order.
truncated boolean If true the number of rows generated exceeded the maximum number of rows that can be send by the server. In this case the rows key contains the maximum allowed, and this key is set to true.
Type
jQuery.Deferred

getSqlDateFormat(varName, format) → {string|null}

Source:

Returns the SQL needed to format the given date column.

Parameters:
Name Type Description
varName string

Name of the date variable to format
format string

Format string
Returns:

SQL function needed to format the given variable

Type
string | null

getSurvey(surveyID, cacheopt) → {jQuery.Deferred}

Source:

Asynchronously fetches one of more Surveys from Surveys 6.

Examples
server.getSurveys(surveyID).done(function(responses) {
   // Summary data in here
}).fail(function() {
   // Something went wrong
});
{
 Survey Object
},
Parameters:
Name Type Attributes Default Description
surveyID array

Encrypted ID of the survey to fetch.
cache bool <optional>
 true

If false, the query will include a timestamp to override any server-side caching.
Returns:
Type
jQuery.Deferred

getSurveyCompletesByDay(surveyID, cacheopt) → {jQuery.Deferred}

Source:

Asynchronously fetches a summary of the Survey Response rates from Surveys 6.

Examples
server.getSurveyCompletesByDay(proj).done(function(responses) {
   // Summary data in here
}).catch(function() {
   // Something went wrong
});
[
 {
     "count": 47,
     "date": "2024-11-14"
 },
 {
     "count": 41,
     "date": "2024-11-15"
 },
 {
     "count": 15,
     "date": "2024-11-16"
 },
 ...
],
Parameters:
Name Type Attributes Default Description
surveyID string

ID of the survey to inspect (encrypted)
cache bool <optional>
 true

If false, the query will include a timestamp to override any server-side caching.
Returns:
Type
jQuery.Deferred

getSurveyResponsesSummary(surveyID, cacheopt) → {jQuery.Deferred}

Source:

Asynchronously fetches a summary of the Survey Response rates from Surveys 6.

Examples
server.getSurveyResponsesSummary(proj).done(function(responses) {
   // Summary data in here
}).catch(function() {
   // Something went wrong
});
{
 "results": [
     {
         "completed": 212,
         "notStarted": 1339,
         "paused": 73,
         "site": "Not Known",
         "total": 1624,
         "usablePaused": 0
     },
     "totals": [
     {
         "completed": 212,
         "notStarted": 1339,
         "paused": 73,
         "total": 1624,
         "usablePaused": 0
     }
 ],
},
Parameters:
Name Type Attributes Default Description
surveyID string

ID of the survey to inspect (encrypted)
cache bool <optional>
 true

If false, the query will include a timestamp to override any server-side caching.
Returns:
Type
jQuery.Deferred

getUser(cacheopt) → {jQuery.Deferred}

Source:

Asynchronously fetches information about the currently logged-in user, including name, email, groups, roles and visible projects.

Examples
server.getUser().done(user => {
    // user in here
}}.catch(function() {
    // something went wrong
})
user = {
   "username": "demouser@example.com",
   "name": "Demo User",
   "given_name": "Demo",
   "family_name": "User",
   "email": "demouser@example.com",
   "email_verified": true,
   "o": "TLF Research",
   "access_control": "none",
   "groups": [
      "/TLF Research"
   ],
   "roles": [
      "manage_users_basic",
      "manage_users",
      "offline_access",
      "uma_authorization"
   ],
   "projects": [
   {
      "client": "Building Client",
      "id": 1,
      "name": "Building Demo",
      "stopwords": "Building"
   },
   {
      "client": "Catalyst Perception",
      "id": 2,
      "name": "Catalyst Perception",
      "stopwords": ""
   }]
};
Parameters:
Name Type Attributes Default Description
cache bool <optional>
 true

If false, the query will include a timestamp to override any server-side caching.
Returns:
Type
jQuery.Deferred

getUserNoteStats(name, project, cacheopt) → {jQuery.Deferred}

Source:

Asynchronously fetches stats about Users' Notes pertaining to the given Project.

Parameters:
Name Type Attributes Default Description
name string

Name of the dataset (included in the tag key in the returned results)
project object

Project to use
cache bool <optional>
 true

If false, the query will include a timestamp to override any server-side caching.
Returns:
Type
jQuery.Deferred

parseResponse(response) → {object}

Source:

Scans the given server response rows and converts any numeric strings to actual numbers.

Parameters:
Name Type Description
response
Returns:
Type
object

postAIAttachment(project, file, optionsopt) → {Promise.<object>}

Source:

Uploads a file to attach to an AI chat session and resolves with its metadata.

The returned 'id' is passed in the attachments array of postAIResponseStream. The 'inline' flag says whether the file's bytes will travel with the turn or whether the model will read it from the server a portion at a time, which is worth showing to the user: it explains why a large spreadsheet behaves differently from a screenshot.

Uses fetch rather than jQuery so that upload progress and cancellation are available. Note that 'credentials: include' is required here: fetch does not honour the xhrFields setting that the jQuery calls in this file rely on.

Example
const controller = new AbortController();
const meta = await server.postAIAttachment(project, file, {signal: controller.signal});
Parameters:
Name Type Attributes Description
project object

The project the chat session belongs to.
file File

The file to upload.
options object <optional>

Optional settings.

Properties
Name Type Attributes Description
signal AbortSignal <optional>

Signal to abort the upload.
Returns:

Resolves with {id, name, mime, size, kind, inline, readable}.

Type
Promise.<object>

postAIResponseStream(prompt, promptData, options, sessionID, cacheopt) → {EventSource}

Source:

Fetches a response from an LLM using a POST request via the native fetch API. Note: This returns the EventSource instance directly, allowing the caller to manage it.

Parameters:
Name Type Attributes Default Description
prompt string

The prompt to send in the request body.
promptData object

Contains configuration for the request.

Properties
Name Type Attributes Description
attachments Array.<string> <optional>

IDs of files attached to this turn, from postAIAttachment. Only new attachments need listing - those sent on earlier turns stay bound to the session.
options object

An object containing callbacks and an optional AbortSignal.

Properties
Name Type Attributes Description
onMessage function

Called for each data chunk received.
onError function

Called if an error occurs.
ondone function

Called when the stream is successfully closed by the server.
signal AbortSignal <optional>

An optional signal to abort the request.
sessionID string

The chat session ID.
cache boolean <optional>
 true

If false, the query will include a timestamp to override caching.
Returns:

The EventSource instance. The caller must add event listeners.

Type
EventSource

restoreChat(project, history)

Source:

Restores a chat history for a given project.

Parameters:
Name Type Description
project object
history object
Returns:

saveNote(name, project, participantID, note, cacheopt) → {jQuery.Deferred}

Source:

Asynchronously saves a new Note in the given Project that is associated with the given Response.

A Note is an object with the following structure:

key type description
author string The Note author's full name.
value string The body text of the Note.
type string The Note's type. Must be one of comment or status-change.
status number The current status of the Note. Must be the ID of a Note Status as defined in the note_status table in the database.
Examples
const note = {
   author: "Joe Bloggs",
   value: "This is a new note",
   type: "comment"
   status: 3, // Resolved
};
server.saveNote('new-note', proj, participantID, note).done(function () {
   // Dispatch a custom event to tell other widgets that a new Note is available
   window.dispatchEvent(new CustomEvent('new-note', {detail: note}));
}).catch(function() {
   // Something went wrong
});;
Parameters:
Name Type Attributes Default Description
name string

Name of the dataset (included in the tag key in the returned results)
project object

Project to use
participantID number

ID of the Participant to associate with this Note
note object

Note to be created
cache bool <optional>
 true

If false, the query will include a timestamp to override any server-side caching.
Returns:
Type
jQuery.Deferred

setAPIDebugMode(debug) → {jQuery.Deferred}

Source:

Sets the debug mode of the API.

Parameters:
Name Type Description
debug bool

When set to '1' the API's debug mode will be switched on; if '0' it's switched off.
Returns:
Type
jQuery.Deferred

setUnauthorizedHandler(callback)

Source:

Sets a handler that is triggered if an API call is unauthorized. May be used to update the UI to indicate to the user that the API is not available. Set to null to disable.

Parameters:
Name Type Description
callback function | null

Function to be invoked if the IDP rejects an API call

updatePFIs(project) → {jQuery.Deferred}

Source:

Asynchronously updates the PFIs associated with the given Project for the logged-in User. PFIs are encoded as a single string that is a collection of PFIs separated by pipe characters.

Example
server.updatePFIs(project, "This is PFI one|This is PFI 2|This is PFI three!");
Parameters:
Name Type Description
project object

Project to use
Returns:
Type
jQuery.Deferred

(inner) getProjVar(project, varName) → {any|undefined}

Source:

Returns the value of the given variable or undefined if it doesn't exist.

Parameters:
Name Type Description
project Object

Project to search.
varName string

Name of the date variable to format
Returns:

Value of requested variable.

Type
any | undefined

Documentation generated by JSDoc 3.6.11 on Fri Aug 14 2026 17:53:48 GMT+0100 (British Summer Time) using the docdash theme.