Totara 17.0 API reference documentation

Endpoint

All requests to the external API are made through a single endpoint:

https://YOUR-SITE-URL/api/graphql.php

Requests are made via the HTTP POST method with a JSON-encoded body:

$ curl 'https://YOUR-SITE-URL/api/graphql.php' \
    -X POST \
    -H 'Authorization: Bearer YOUR-API-BEARER-TOKEN' \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json' \
    --data-binary '{ "query": "query { totara_webapi_status { status } }", "variables": "{}" }'

See the Authentication section below for how to obtain a valid Bearer token.

The expected response for this request would be the following JSON object:

{
  "data": {
    "totara_webapi_status": {
      "status": "ok"
    }
  }
}

Authentication

The external API uses OAuth 2.0 via the client credentials grant type to authenticate requests. This involves three steps as outlined below.

1. Register a client

To register a client, log in to your Totara site as a Site Administrator and navigate to Site Administration > Development > API > Clients.

Click the Add client button and provide information to describe the purpose of your client.

Make a note of the client id and secret for step 2.

2. Request a token

To programmatically request a token, call the OAuth 2.0 token endpoint as follows, passing the client_id and client_secret obtained during step 1:

curl -X POST 'https://YOUR-SITE-URL/totara/oauth2/token.php' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'grant_type=client_credentials&client_id=CLIENT_ID_HERE&client_secret=CLIENT_SECRET_HERE'

The response will be:

{
  "token_type": "Bearer",
  "expires_in": 3600,
  "access_token": "YOUR-API-BEARER-TOKEN"
}

3. Submit a request with a valid token

Copy the value from the "access_token" property in the response into the 'Authorization: Bearer' header of your request.

Request format

A simple GraphQL request might look like this:

query my_query {
  totara_webapi_status {
    status
  }
}

This request consists of the following.

The query keyword

This indicates this is a read-only request. 'mutation' is used for requests which write data. The keyword is optional, but when provided the specific actions within the request must match the keyword given.

Request name (my_query)

Optional string to allow the request author to describe the purpose of the request. It is not used by the server.

Query or mutation name (totara_webapi_status)

Within the outer curly braces you must specify at least one query or mutation to execute (typically just one but requesting multiple is allowed).

The available queries and mutations are specified in the reference documentation.

Response structure

In GraphQL it is up to the query author to specify the data they want to receive in the response.

The curly braces and field names within them specify the data structure. They must match the structure of the type that is returned by that query or mutation.

Types can be complex (contain properties that represent other types), so additional curly braces are used to obtain properties of subresources in one request. For example, to get a list of course names and the name of each course's category:

query get_courses {
  get_courses {
    fullname
    category {
      name
    }
  }
}

Arguments and variables

Some queries and mutations have optional or required arguments which require additional data to be passed with the request.

User-provided data is kept separate from the body of the request as variables. Variables are passed as a separate JSON object with the query. To make use of variables, the structure of the query changes slightly:

Query

query get_course($courseid: core_id!) {
  core_course(courseid: $courseid) {
    fullname
  }
}

Variables

{
  "courseid": 2
}

In this example the ‘core_course’ query has an argument 'courseid'. It must be of the type 'core_id' and it is required (the ! suffix is used when a field must be provided). Available arguments are listed in the reference documentation for a query or mutation. Although values can also be hardcoded in the query, it is good practice to use variables to support argument validation and query reuse.

Variables are represented by strings starting with the dollar sign ($). Any $variable specified within the body of the request must be defined in the round brackets after the outer query name. When defining a variable you must specify its type. Variables will be validated according to their type before query execution. Complex types (types with properties made of other types) are allowed but must be defined in the schema.

The variables object that is passed with the request must have keys that match the variable names and give values that are compatible with the specified type for that variable.

Field arguments

Like queries and mutations, fields can support arguments. For example, here the argument on the timestamp field determines how the field is formatted in the response:

query test {
 totara_webapi_status {
   status
   timestamp(format: DATETIMELONG)
  }
}

Aliases

You can prefix a query, mutation or field with a different name and the server will return it as the key you specify. This can be used to return data to match a certain structure, or to differentiate if you are requesting the same field multiple times.

query test {
  my_query_name: totara_webapi_status {
    status
    long_year: timestamp(format: DATETIMELONG)
    short_year: timestamp(format: DATETIMESHORT)
  }
}

would return:

{
  "data": {
    "my_query_name": {
      "status": "ok",
      "long_year": "27/05/2022, 10:51",
      "short_year": "27/05/22, 10:51"
    }
  }
}

For more information on the GraphQL language see this Introduction to GraphQL.

API schema

You can perform introspection against the external API directly.

Alternatively, you can download the current external API schema for your site here: https://YOUR-SITE-URL/totara/api/documentation/schema.php

Core

Types

Boolean

Description

The Boolean scalar type represents true or false.

Example
true
Types

Int

Description

The Int scalar type represents non-fractional signed whole numeric values. Int can represent values between -(2^31) and 2^31 - 1.

Example
123
Types

String

Description

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Example
"xyz789"
Types

core_date

Description

Represents standard unix timestamps stored in database.

For input, use either an integer timestamp, numeric string or an ISO-8601 string.

Output can usually be selected via format argument. See core_date_format enum for the list of supported formats.

Example
"2022-04-17"
Types

core_date_format

Description

List of supported output formats for core_date scalar.

The actual format used for userdate() is: get_string('strftime' . strtolower($arg['format']), 'langconfig')

Values
Enum Value Description

TIMESTAMP

 A standard UNIX timestamp value. 0 will be replaced with null.

ISO8601

 ISO-8601 time string in current user timezone, null if no date. Example output: 2022-09-01T12:06:53+1200

DAYDATETIME

 Datetime string in the format: Thursday, 1 September 2022, 12:05 PM

TIME

 Time string in the format: 12:08 PM

TIMESHORT

 Time string in the format: 12:08

DATE

 Date string in the format: 1 September 2022

DATESHORT

 Date string in the format: 1 September

DATELONG

 Date string in the format: 1/09/2022

DATETIME

 Datetime string in the format: 1 September 2022, 12:12 PM

DATETIMESHORT

 Datetime string in the format: 1/09/22, 12:12

DATETIMELONG

 Datetime string in the format: 1/09/2022, 12:10

DATETIMESECONDS

 Datetime string in the format: 1 Sep 2022 at 12:12:07
Example
"TIMESTAMP"
Types

core_format

Description

Rich-text output format. Note that some rich-text formats may not be renderable in other formats.

Values
Enum Value Description

RAW

 Outputs the stored value unchanged. Most commonly used when editing a value.

HTML

 Outputs the stored value for display within an HTML page. Handles escaping of HTML entities.

PLAIN

 Outputs the stored value in a way suitable for plain-text display.

MARKDOWN

 Outputs the stored value in Markdown format.

JSON_EDITOR

 Outputs the stored value in a JSON structure, suitable for use by a compatible JSON editor (e.g. Weka).

MOBILE

 Outputs the stored value in a format suitable for use within the Totara mobile app.
Example
"RAW"
Types

core_id

Description

Represents database id fields (numeric string). 0 is converted to NULL.

Example
4
Types

core_pagination_input

Description

Contains pagination information needed to load the next page of a query. Note this input type supports both cursor-based and offset-based (page-based) pagination. The method to use will depend on the implementation by the query.

Fields
Input Field Description
cursor - String

Next cursor. Opaque string obtained from the next_cursor property of core_pageable_result. Used by the query to identify which records to return.
limit - param_integer

Number of items to return.
page - param_integer

Page number (only used by offset-based cursors).
Example
{"cursor": "eyJsaW1pdCI6MSwiY29sdW1ucyI6eyJpZCI6M319", "limit": 20, "page": 3}
Types

core_sort_direction_enum

Description

Options available when specifying the direction of a sort.

Values
Enum Value Description

ASC

 Sort column in ascending order. This refers to 0, 1, 2, 3 for numbers and A, B, C, D for strings.

DESC

 Sort column in descending order. This refers to 3, 2, 1, 0 for numbers and D, C, B, A for strings.
Example
"ASC"
Types

core_sort_input

Description

Input type for specifying sorting of arbitrary data.

Fields
Input Field Description
column - String!

String containing either a single field or a comma-separated list of fields to be sorted by. Allowed fields are defined in the specific data provider and should be documented in the query, but typically column options will align with existing type field names.
direction - core_sort_direction_enum

The sort direction of the column or columns.
Example
{"column": "timemodified", "direction": "ASC"}
Types

param_email

Description

Input parameter equivalent to PARAM_EMAIL, '' is converted to NULL.

Example
"test@example.com"
Types

param_integer

Description

Input parameter equivalent to PARAM_INT, '' is converted to NULL.

Example
123
Types

param_username

Description

Input parameter equivalent to PARAM_USERNAME, '' is converted to NULL.

Example
"testuser"

Hierarchies

Types

totara_hierarchy_framework

Description

Hierarchy framework interface. Defines standard fields available in all hierarchy frameworks. A framework is a collection of hierarchy items arranged in a tree.

Fields
Field Name Description
id - core_id! Internal database id of the framework.
fullname - String! Full name of the framework.
Arguments
format - core_format

Output format this field should be formatted for.
idnumber - String Unique reference used to represent the framework across multiple systems.
shortname - String The short name of the framework. Only used as additional information if admin setting 'showhierarchyshortnames' is enabled.
Arguments
format - core_format

Output format this field should be formatted for.
description - String Rich-text description of the framework.
Arguments
format - core_format

Output format this field should be formatted for.
Possible Types
totara_hierarchy_framework Types

totara_hierarchy_organisation_framework

totara_hierarchy_position_framework

Example
{
  "id": 7,
  "fullname": "Example hierarchy framework",
  "idnumber": "HFW123",
  "shortname": "example_hierarchy_framework",
  "description": "This is an example hierarchy framework."
}
Types

totara_hierarchy_item

Description

Hierarchy item interface. Defines standard fields available in all hierarchy items. A hierarchy item is a single node in a tree-like hierarchy of items.

Fields
Field Name Description
id - core_id! Internal database id of the hierarchy item.
fullname - String! Full name of the hierarchy item.
Arguments
format - core_format

Output format this field should be formatted for.
idnumber - String Unique reference used to represent the hierarchy item across multiple systems.
shortname - String The short name of the hierarchy item. Only used as additional information if admin setting 'showhierarchyshortnames' is enabled.
Arguments
format - core_format

Output format this field should be formatted for.
description - String Rich-text description of the hierarchy item.
Arguments
format - core_format

Output format this field should be formatted for.
frameworkid - core_id The internal database id of the hierarchy framework this item belongs to.
framework - totara_hierarchy_framework The hierarchy framework this item belongs to.
path - String! An ordered list of parent database ids for this hierarchy item, indicating the hierarchy of parent items. Includes the current item and separated by forward slashes, e.g. item with id=6 might be: /1/4/6 This is a computed value.
visible - Boolean! Flag determining whether the hierarchy item is visible to end users or not.
parentid - core_id The id of this hierarchy item's immediate parent in the framework hierarchy. Set to 0 if this is a top-level item.
parent - totara_hierarchy_item The parent item in the hierarchy. Null if a top-level item.
children - [totara_hierarchy_item!]! Collection of hierarchy items that are immediately below this one in the framework hierarchy. Empty if this item has no children.
typeid - core_id The id of the hierarchy item type, or 0 if this is a generic item.
type - totara_hierarchy_type Hierarchy item type object.
Possible Types
totara_hierarchy_item Types

totara_hierarchy_organisation

totara_hierarchy_position

Example
{
  "id": 9,
  "fullname": "Example hierarchy item",
  "idnumber": "HI567",
  "shortname": "example_hierarchy_item",
  "description": "This is an example hierarchy item.",
  "frameworkid": 5,
  "framework": {"id": 8, "fullname": "Example hierarchy framework"},
  "path": "/1/2/45",
  "visible": true,
  "parentid": 4,
  "parent": {"id": 16, "fullname": "Example hierarchy item"},
  "children": [
    {"id": 5, "fullname": "Example hierarchy item"},
    {"id": 7, "fullname": "Another example hierarchy item"}
  ],
  "typeid": 14,
  "type": {"id": 3, "fullname": "Example hierarchy type"}
}
Types

totara_hierarchy_organisation

Description

Organisation item object.

The organisation structure defines the regions, departments, groups, areas, or teams that a company has defined.

Fields
Field Name Description
id - core_id! Internal database id of the organisation.
fullname - String! Full name of the organisation.
Arguments
format - core_format

Output format this field should be formatted for.
idnumber - String Unique reference used to represent the organisation across multiple systems.
shortname - String The short name of the organisation. Only used as additional information if admin setting 'showhierarchyshortnames' is enabled.
Arguments
format - core_format

Output format this field should be formatted for.
description - String Rich-text description of the organisation.
Arguments
format - core_format

Output format this field should be formatted for.
frameworkid - core_id The internal database id of the organisation framework this organisation belongs to.
framework - totara_hierarchy_organisation_framework The organisation framework this organisation belongs to.
path - String! An ordered list of parent database ids for this organisation, indicating the hierarchy of parent items. Includes the current item and separated by forward slashes, e.g. item with id=6 might be: /1/4/6 This is a computed value.
visible - Boolean! Flag determining whether the organisation is visible to end users or not.
parentid - core_id The id of this organisation's immediate parent in the framework hierarchy. Set to 0 if this is a top-level organisation.
parent - totara_hierarchy_organisation The parent organisation in the hierarchy. Null if a top-level item.
children - [totara_hierarchy_organisation!]! Collection of organisations that are immediately below this one in the framework hierarchy. Empty if this organisation has no children.
typeid - core_id The id of the organisation type, or 0 if this is a generic organisation.
type - totara_hierarchy_organisation_type Organisation type object.
Example
{
  "id": 27,
  "fullname": "Sales and Marketing",
  "idnumber": "SM1",
  "shortname": "sales",
  "description": "Sales and marketing are based in our US office.",
  "frameworkid": 6,
  "framework": {"id": 7, "fullname": "Global company organisation structure"},
  "path": "/4/22/27",
  "visible": true,
  "parentid": 4,
  "parent": {"id": 22, "fullname": "Head Office"},
  "children": [
    {"id": 45, "fullname": "US sales team"},
    {"id": 37, "fullname": "Europe sales team"}
  ],
  "typeid": 7,
  "type": {"id": 3, "fullname": "Organisational units"}
}
Types

totara_hierarchy_organisation_framework

Description

Organisation framework object. An organisation framework is a collection of organisations arranged in a tree.

Fields
Field Name Description
id - core_id! Internal database id of the organisation framework.
fullname - String! Full name of the organisation framework.
Arguments
format - core_format

Output format this field should be formatted for.
idnumber - String Unique reference used to represent the organisation framework across multiple systems.
shortname - String Short name of the organisation framework, only used if admin setting 'showhierarchyshortnames' is enabled.
Arguments
format - core_format

Output format this field should be formatted for.
description - String Rich-text description of the organisation framework.
Arguments
format - core_format

Output format this field should be formatted for.
Example
{
  "id": 7,
  "fullname": "Global company organisation structure",
  "idnumber": "MAIN1",
  "shortname": "global_structure",
  "description": "This is the main organisation framework for organisations for our company."
}
Types

totara_hierarchy_organisation_reference

Description

Input for identifying an organisation.

The organisation must be identified by providing one of the following:

  • The organisation's internal database id
  • The organisation's idnumber

An organisation reference must uniquely identify a single organisation to be valid.

Fields
Input Field Description
id - core_id

Identify an organisation by internal database id.
idnumber - String

Identify an organisation by its idnumber. idnumber is a unique reference used to represent the organisation across multiple systems.
Example
{"id": 4, "idnumber": "org1"}
Types

totara_hierarchy_organisation_type

Description

Organisation type object. An organisation type is a user-defined classification which can be assigned to organisations leading to certain custom fields being available on that organisation.

Fields
Field Name Description
id - core_id! Internal database id of the organisation type.
fullname - String! Organisation type full name.
Arguments
format - core_format

Output format this field should be formatted for.
idnumber - String Unique reference used to represent the organisation type across multiple systems.
shortname - String The short name of the organisation type. Only used as additional information if admin setting 'showhierarchyshortnames' is enabled.
Arguments
format - core_format

Output format this field should be formatted for.
description - String Rich-text description of the organisation type.
Arguments
format - core_format

Output format this field should be formatted for.
Example
{
  "id": 3,
  "fullname": "Organisational units",
  "idnumber": "ORG1",
  "shortname": "org_units",
  "description": "This type defines organisation units with specific business functions."
}
Types

totara_hierarchy_position

Description

Position item object.

The position structure defines the job roles that a company has defined.

Fields
Field Name Description
id - core_id! Internal database id of the position.
fullname - String! Full name of the position.
Arguments
format - core_format

Output format this field should be formatted for.
idnumber - String Unique reference used to represent the position across multiple systems.
shortname - String The short name of the position. Only used as additional information if admin setting 'showhierarchyshortnames' is enabled.
Arguments
format - core_format

Output format this field should be formatted for.
description - String Rich-text description of the position.
Arguments
format - core_format

Output format this field should be formatted for.
frameworkid - core_id The internal database id of the position framework this position belongs to.
framework - totara_hierarchy_position_framework The position framework this position belongs to.
path - String! An ordered list of parent database ids for this position, indicating the hierarchy of parent items. Includes the current item and separated by forward slashes, e.g. item with id=6 might be: /1/4/6 This is a computed value.
visible - Boolean! Flag determining whether the position is visible to users or not.
parentid - core_id The id of this position's immediate parent in the framework hierarchy. Set to 0 if this is a top-level position.
parent - totara_hierarchy_position The parent position in the hierarchy. Null if a top-level item.
children - [totara_hierarchy_position!]! Collection of positions that are immediately below this one in the framework hierarchy. Empty if this position has no children.
typeid - core_id The id of the position type, or 0 if this is a generic position.
type - totara_hierarchy_position_type Position type object.
Example
{
  "id": 27,
  "fullname": "Senior project manager",
  "idnumber": "PM3",
  "shortname": "senior_project_manager",
  "description": "A grade 3 project manager.",
  "frameworkid": 6,
  "framework": {"id": 7, "fullname": "Active company roles"},
  "path": "/4/22/27",
  "visible": true,
  "parentid": 4,
  "parent": {"id": 22, "fullname": "Project Manager"},
  "children": [],
  "typeid": 7,
  "type": {"id": 3, "fullname": "Managerial roles"}
}
Types

totara_hierarchy_position_framework

Description

Position framework object. A position framework is a collection of positions arranged in a tree.

Fields
Field Name Description
id - core_id! Internal database id of the position framework.
fullname - String! Full name of the position framework.
Arguments
format - core_format

Output format this field should be formatted for.
idnumber - String Unique reference used to represent the position framework across multiple systems.
shortname - String Short name of the position framework, only used if admin setting 'showhierarchyshortnames' is enabled.
Arguments
format - core_format

Output format this field should be formatted for.
description - String Rich-text description of the position framework.
Arguments
format - core_format

Output format this field should be formatted for.
positions - [totara_hierarchy_position!]! Positions that belong to this position framework.
Example
{
  "id": 7,
  "fullname": "Active company roles",
  "idnumber": "ACTIVEROLES",
  "shortname": "active_roles",
  "description": "This is the main position framework for active positions used by our company.",
  "positions": [totara_hierarchy_position]
}
Types

totara_hierarchy_position_reference

Description

Input for identifying a position.

The position must be identified by providing one of the following:

  • The position's internal database id
  • The position's idnumber

A position reference must uniquely identify a single position to be valid.

Fields
Input Field Description
id - core_id

Identify a position by internal database id.
idnumber - String

Identify a position by its idnumber. idnumber is a unique reference used to represent the position across multiple systems.
Example
{"id": 4, "idnumber": "pos1"}
Types

totara_hierarchy_position_type

Description

Position type object. A position type is a user-defined classification which can be assigned to positions leading to certain custom fields being available on that position.

Fields
Field Name Description
id - core_id! Internal database id of the position type.
fullname - String! Position type full name.
Arguments
format - core_format

Output format this field should be formatted for.
idnumber - String Unique reference used to represent the position type across multiple systems.
shortname - String The short name of the position type. Only used as additional information if admin setting 'showhierarchyshortnames' is enabled.
Arguments
format - core_format

Output format this field should be formatted for.
description - String Rich-text description of the position type.
Arguments
format - core_format

Output format this field should be formatted for.
Example
{
  "id": 3,
  "fullname": "Managerial roles",
  "idnumber": "MAN1",
  "shortname": "manager_roles",
  "description": "This type defines positions with line management responsibility."
}
Types

totara_hierarchy_type

Description

Hierarchy type interface. Defines standard fields available in all hierarchy types. A hierarchy type is a user-defined classification which can be assigned to hierarchy items leading to certain custom fields being available on that item.

Fields
Field Name Description
id - core_id! Internal database id of the hierarchy type.
fullname - String! Type full name.
Arguments
format - core_format

Output format this field should be formatted for.
idnumber - String Unique reference used to represent the type across multiple systems.
shortname - String The short name of the type. Only used as additional information if admin setting 'showhierarchyshortnames' is enabled.
Arguments
format - core_format

Output format this field should be formatted for.
description - String Rich-text description of the type.
Arguments
format - core_format

Output format this field should be formatted for.
Possible Types
totara_hierarchy_type Types

totara_hierarchy_organisation_type

totara_hierarchy_position_type

Example
{
  "id": 3,
  "fullname": "Example hierarchy type",
  "idnumber": "HTY123",
  "shortname": "example_hierarchy_type",
  "description": "This is an example hierarchy type."
}

Job assignments

Mutations

totara_job_create_job_assignment

Description

Creates a new job assignment.

Response

Returns a totara_job_create_job_assignment_result!

Arguments
Name Description
input - totara_job_create_job_assignment_input! Input object specifying data for creating the new job assignment.

Example

Query
mutation totara_job_create_job_assignment($input: totara_job_create_job_assignment_input!) {
  totara_job_create_job_assignment(input: $input) {
    job_assignment {
      ...totara_job_job_assignmentFragment
    }
  }
}
Variables
{"input": totara_job_create_job_assignment_input}
Response
{
  "data": {
    "totara_job_create_job_assignment": {
      "job_assignment": totara_job_job_assignment
    }
  }
}
Mutations

totara_job_delete_job_assignment

Description

Mutation to delete a job assignment.

Response

Returns a totara_job_delete_job_assignment_result!

Arguments
Name Description
target_job - totara_job_job_assignment_reference! Input provided for identifying the job assignment.

Example

Query
mutation totara_job_delete_job_assignment($target_job: totara_job_job_assignment_reference!) {
  totara_job_delete_job_assignment(target_job: $target_job) {
    job_assignment_id
  }
}
Variables
{"target_job": totara_job_job_assignment_reference}
Response
{"data": {"totara_job_delete_job_assignment": {"job_assignment_id": 4}}}
Mutations

totara_job_update_job_assignment

Description

Updates a specific target job assignment with new properties.

Response

Returns a totara_job_update_job_assignment_result!

Arguments
Name Description
target_job - totara_job_job_assignment_reference! The job assignment that should be updated.
input - totara_job_update_job_assignment_input! Input object specifying data for updating the job assignment.

Example

Query
mutation totara_job_update_job_assignment(
  $target_job: totara_job_job_assignment_reference!,
  $input: totara_job_update_job_assignment_input!
) {
  totara_job_update_job_assignment(
    target_job: $target_job,
    input: $input
  ) {
    job_assignment {
      ...totara_job_job_assignmentFragment
    }
  }
}
Variables
{
  "target_job": totara_job_job_assignment_reference,
  "input": totara_job_update_job_assignment_input
}
Response
{
  "data": {
    "totara_job_update_job_assignment": {
      "job_assignment": {
        "id": 7,
        "idnumber": "PM3",
        "fullname": "Senior project manager",
        "user": {"fullname": "John Smith"}
      }
    }
  }
}

Types

totara_job_create_job_assignment_input

Description

Input data for creating a job assignment.

Fields
Input Field Description
idnumber - String!

Unique reference used to represent the job assignment across multiple systems.
fullname - String

The full name of the job assignment.
user - core_user_user_reference!

The user to create the job assignment for.
start_date - core_date

Date that the user started in this job assignment.
end_date - core_date

Date that the user ends in this job assignment.
position - totara_hierarchy_position_reference

Position (job role) that applies to this job assignment.
organisation - totara_hierarchy_organisation_reference

Organisation in which the user holds this job assignment.
manager - totara_job_job_assignment_reference

Job assignment that defines the management relationship.
appraiser - core_user_user_reference

Appraiser for this assignment.
temp_manager - totara_job_job_assignment_reference

Job assignment that defines the temporary management relationship.
temp_manager_expiry_date - core_date

Date the temporary manager assignment will expire.
Example
{
  "idnumber": "xyz789",
  "fullname": "xyz789",
  "user": core_user_user_reference,
  "start_date": "2022-04-17",
  "end_date": "2022-04-17",
  "position": totara_hierarchy_position_reference,
  "organisation": totara_hierarchy_organisation_reference,
  "manager": totara_job_job_assignment_reference,
  "appraiser": core_user_user_reference,
  "temp_manager": totara_job_job_assignment_reference,
  "temp_manager_expiry_date": "2022-04-17"
}
Types

totara_job_create_job_assignment_result

Description

Mutation result type returned after creating a job assignment. Returns information about the job assignment that was created.

Fields
Field Name Description
job_assignment - totara_job_job_assignment! The newly created job assignment.
Example
{"job_assignment": totara_job_job_assignment}
Types

totara_job_delete_job_assignment_result

Description

Mutation result type returned after deletion of a job assignment.

Fields
Field Name Description
job_assignment_id - core_id! Database id of the job assignment.
Example
{"job_assignment_id": 4}
Types

totara_job_job_assignment

Description

Job assignment type object, containing information about an individual job assignment.

Fields
Field Name Description
id - core_id! Internal database id of the job assignment.
userid - core_id! User id of the user the job assignment is associated with.
user - core_user! User record of the user the job assignment is associated with.
fullname - String The full name of the job assignment. Used when job assignment is displayed and for selecting job assignments in dialogs.
Arguments
format - core_format

Output format this field should be formatted for.
shortname - String The short name of the job assignment. Only used as additional information.
Arguments
format - core_format

Output format this field should be formatted for.
idnumber - String! Used when syncing job assignment data from external sources. Must be unique for each user (but two users could have the same job assignment idnumber).
description - String Rich-text description of the job assignment.
Arguments
format - core_format

Output format this field should be formatted for.
startdate - core_date

Date that the user started in this job assignment. This date can be used in dynamic audience rules.

This date is not used by the system to determine if the job assignment is active.
Arguments
format - core_date_format

Output date format this field should be formatted using.
enddate - core_date

Date that the user ends in this job assignment. This date can be used in dynamic audience rules.

This date is not used by the system to determine if the job assignment is active.
Arguments
format - core_date_format

Output date format this field should be formatted using.
positionid - core_id Internal database id of the position for this assignment.
position - totara_hierarchy_position Position (job role) object for this job assignment.
organisationid - core_id Internal database id of the organisation for this job assignment.
organisation - totara_hierarchy_organisation Organisation object for this job assignment.
managerjaid - core_id Internal database id of the manager job assignment.
managerja - totara_job_job_assignment Job assignment object that defines the management relationship.
tempmanagerjaid - core_id Internal database id of the temporary manager job assignment. Temporary manager has the same rights as a normal manager, until the expiry date is reached.
tempmanagerja - totara_job_job_assignment Job assignment object that defines the temporary management relationship.
tempmanagerexpirydate - core_date Date the temporary manager assignment will expire.
Arguments
format - core_date_format

Output date format this field should be formatted using.
appraiserid - core_id Internal database id of the user assigned as the appraiser for this job assignment.
appraiser - core_user Appraiser user object for this job assignment.
staffcount - Int! Number of staff assigned to the user via this job assignment. E.g. the number of other job assignments which list this assignment as 'managerja'.
tempstaffcount - Int! Number of staff assigned to the user to temporarily manage via this job assignment. E.g. the number of other job assignments which list this assignment as 'tempmanagerja'.
Example
{
  "id": 4,
  "userid": 4,
  "user": {"username": "joe.smith"},
  "fullname": "Senior Project Manager",
  "shortname": "senior_pm",
  "idnumber": "PM3",
  "description": "Grade 3 project manager.",
  "startdate": "2022-04-17",
  "enddate": "2022-04-17",
  "positionid": 4,
  "position": {"idnumber": "pos1"},
  "organisationid": 4,
  "organisation": {"idnumber": "org2"},
  "managerjaid": 4,
  "managerja": {"idnumber": "managerjob1"},
  "tempmanagerjaid": 4,
  "tempmanagerja": {"idnumber": "tempmanagerjob1"},
  "tempmanagerexpirydate": "2022-04-17",
  "appraiserid": 4,
  "appraiser": {"email": "appraiser@example.com"},
  "staffcount": 10,
  "tempstaffcount": 3
}
Types

totara_job_job_assignment_reference

Description

Input for identifying a job assignment.

The job assignment must be identified by providing one of the following:

  • The job assignment's internal database id
  • The job assignment's idnumber

A job assignment reference must uniquely identify a single job assignment record to be valid.

Fields
Input Field Description
id - core_id

Identify a job assignment by internal database id.
idnumber - String

Identify a job assignment by its idnumber.

Idnumber is a unique reference used to represent a job assignment across multiple systems.
Example
{"id": 4, "idnumber": "job1"}
Types

totara_job_update_job_assignment_input

Description

The input data for updating the job assignment.

Fields
Input Field Description
idnumber - String

Unique reference used to represent the job assignment across multiple systems.
fullname - String

The full name of the job assignment.
start_date - core_date

Date that the user started in this job assignment.
end_date - core_date

Date that the user ends in this job assignment.
position - totara_hierarchy_position_reference

Position (job role) for the user.
organisation - totara_hierarchy_organisation_reference

Organisation in which the user works.
manager - totara_job_job_assignment_reference

Job assignment that defines the management relationship.
appraiser - core_user_user_reference

Appraiser for this assignment.
temp_manager - totara_job_job_assignment_reference

Job assignment that defines the temporary management relationship.
temp_manager_expiry_date - core_date

Date the temporary manager assignment will expire.
Example
{
  "idnumber": "PM3",
  "fullname": "Senior Project Manager",
  "start_date": "2020-07-15",
  "end_date": "2025-03-26",
  "position": {"idnumber": "pos1"},
  "organisation": {"idnumber": "org1"},
  "manager": {"idnumber": "managerjob1"},
  "appraiser": {"username": "jane.doe"},
  "temp_manager": {"idnumber": "tempmanagerjob1"},
  "temp_manager_expiry_date": "2025-04-16"
}
Types

totara_job_update_job_assignment_result

Description

Mutation result type returned after updating a job assignment. Returns the job assignment that was updated.

Fields
Field Name Description
job_assignment - totara_job_job_assignment! The updated job assignment.
Example
{
  "job_assignment": {
    "id": 7,
    "idnumber": "PM3",
    "fullname": "Senior project manager",
    "user": {"fullname": "John Smith"}
  }
}

Multitenancy

Types

totara_tenant_tenant_reference

Description

Input for identifying a tenant.

The tenant must be specified by providing one of the following:

  • The tenant's internal database id
  • The tenant's idnumber

A tenant reference must uniquely identify a single tenant to be valid.

Fields
Input Field Description
id - core_id

Identify a tenant by the internal database id of the tenant.
idnumber - String

Identify a tenant by the idnumber of the tenant. This is a unique reference used to represent the tenant across multiple systems.
Example
{"id": 5, "idnumber": "tenant1"}

User

Queries

core_user_users

Description

Return a paginated list of users in the system. Deleted users are excluded and multitenancy restrictions apply.

Response

Returns a core_user_users_result!

Arguments
Name Description
query - core_user_users_query Sort and pagination information to control the data returned.

Example

Query
query core_user_users($query: core_user_users_query) {
  core_user_users(query: $query) {
    items {
      ...core_userFragment
    }
    total
    next_cursor
  }
}
Variables
{"query": core_user_users_query}
Response
{
  "data": {
    "core_user_users": {
      "items": [
        {
          "username": "test",
          "firstname": "Test",
          "lastname": "User",
          "email": "testuser@example.com"
        },
        {
          "username": "another",
          "firstname": "Another",
          "lastname": "User",
          "email": "anotheruser@example.com"
        }
      ],
      "total": 47,
      "next_cursor": "eyJsaW1pdCI6MSwiY29sdW1ucyI6eyJpZCI6M319"
    }
  }
}

Mutations

core_user_create_user

Description

Create a new user.

Response

Returns a core_user_user_result!

Arguments
Name Description
input - core_user_create_user_input! Input object specifying data for the new user.

Example

Query
mutation core_user_create_user($input: core_user_create_user_input!) {
  core_user_create_user(input: $input) {
    user {
      ...core_userFragment
    }
  }
}
Variables
{"input": core_user_create_user_input}
Response
{
  "data": {
    "core_user_create_user": {
      "user": {
        "id": 4,
        "username": "jsmith",
        "email": "jsmith@example.com",
        "firstname": "John",
        "lastname": "Smith",
        "custom_fields": [{"shortname": "employeeid", "data": "EM12345"}]
      }
    }
  }
}
Mutations

core_user_delete_user

Description

Delete the target user.

Response

Returns a core_user_delete_user_result!

Arguments
Name Description
target_user - core_user_user_reference! Target user which is being deleted.

Example

Query
mutation core_user_delete_user($target_user: core_user_user_reference!) {
  core_user_delete_user(target_user: $target_user) {
    user_id
  }
}
Variables
{"target_user": core_user_user_reference}
Response
{"data": {"core_user_delete_user": {"user_id": 4}}}
Mutations

core_user_update_user

Description

Update the specified target user with new properties.

Response

Returns a core_user_user_result!

Arguments
Name Description
target_user - core_user_user_reference! User to be updated.
input - core_user_update_user_input! Input object specifying data for updating the user.

Example

Query
mutation core_user_update_user(
  $target_user: core_user_user_reference!,
  $input: core_user_update_user_input!
) {
  core_user_update_user(
    target_user: $target_user,
    input: $input
  ) {
    user {
      ...core_userFragment
    }
  }
}
Variables
{
  "target_user": core_user_user_reference,
  "input": core_user_update_user_input
}
Response
{
  "data": {
    "core_user_update_user": {
      "user": {
        "id": 4,
        "username": "jsmith",
        "email": "jsmith@example.com",
        "firstname": "John",
        "lastname": "Smith",
        "custom_fields": [{"shortname": "employeeid", "data": "EM12345"}]
      }
    }
  }
}

Types

core_user

Description

User type object, containing information about an individual user.

Fields
Field Name Description
id - core_id! Internal database id of the user.
idnumber - String The id number of the user.
username - String Username for the user. This field is used in combination with the password for logging in with some authentication types.
Arguments
format - core_format

Output format this field should be formatted for.
fullname - String! Full name of the user. This field combines other name fields as specified by the site display settings.
Arguments
format - core_format
firstname - String First name of the user.
Arguments
format - core_format

Output format this field should be formatted for.
lastname - String Last name of the user.
Arguments
format - core_format

Output format this field should be formatted for.
middlename - String Middle name of the user.
Arguments
format - core_format

Output format this field should be formatted for.
alternatename - String Alternate name of the user.
Arguments
format - core_format

Output format this field should be formatted for.
email - String Email address of the user.
address - String The user's address.
Arguments
format - core_format

Output format this field should be formatted for.
phone1 - String Primary phone number of the user.
Arguments
format - core_format

Output format this field should be formatted for.
phone2 - String Secondary phone number of the user.
Arguments
format - core_format

Output format this field should be formatted for.
department - String Department the user belongs to.
Arguments
format - core_format

Output format this field should be formatted for.
institution - String Institution (organisation) the user belongs to.
Arguments
format - core_format

Output format this field should be formatted for.
city - String City where the user is located.
Arguments
format - core_format

Output format this field should be formatted for.
country - String Country of the user, displayed as a string, for example 'New Zealand'.
description - String Description field for the user's profile.
Arguments
format - core_format

Output format this field should be formatted for.
descriptionformat - core_format Format of the description field, as stored in the database.
profileimageurl - String URL pointing to the main version of the user's profile image.
profileimageurlsmall - String URL pointing to a small version of the user's profile image.
profileimagealt - String Alternate text description of the profile image, for accessibility purposes.
Arguments
format - core_format

Output format this field should be formatted for.
lang - String Language of the user, for example 'en_us'.
theme - String Theme setting for the user or an empty string if the user is using the site default theme.
suspended - Boolean Whether this user is marked as suspended. Suspended users are unable to log in.
timezone - String

Timezone of the user, as a string, for example 'Pacific/Auckland'.

Note that if the admin setting 'forcetimezone' is configured, its value will be used here instead.
interests - String Comma-separated string of interests the user has or null if no interests are assigned.
firstaccess - core_date Timestamp of when this user first accessed the site (or null if never).
Arguments
format - core_date_format

Date format that firstaccess should be returned in.
lastaccess - core_date Timestamp of when this user last accessed the site (or null if never).
Arguments
format - core_date_format

Date format that lastaccess should be returned in.
url - String URL for the user's profile.
Arguments
format - core_format

Output format this field should be formatted for.
skype - String Skype username for the user's profile.
Arguments
format - core_format

Output format this field should be formatted for.
custom_fields - [core_user_custom_field!] Custom fields are additional fields that can be defined by a Site Administrator to allow additional specific data to be connected to users.
Example
{
  "id": 4,
  "idnumber": "RW1234",
  "username": "rebecca.woodhouse",
  "fullname": "Rebecca Woodhouse",
  "firstname": "Rebecca",
  "lastname": "Woodhouse",
  "middlename": "Jane",
  "alternatename": "Becky",
  "email": "rebecca.woodhouse@example.com",
  "address": "1 Civic Square, London, England",
  "phone1": "+64 4 555 1234",
  "phone2": "+64 21 555 1234",
  "department": "Marketing",
  "institution": "Acme Inc.",
  "city": "London",
  "country": "United Kingdom",
  "description": "I have an interest in agile project management and software development.",
  "descriptionformat": "PLAIN",
  "profileimageurl": "https://YOUR-SITE-URL/theme/image.php/ventura/core/1661990216/u/f1",
  "profileimageurlsmall": "https://YOUR-SITE-URL/theme/image.php/ventura/core/1661990216/u/f2",
  "profileimagealt": "Picture of Rebecca Woodhouse",
  "lang": "en",
  "theme": "ventura",
  "suspended": true,
  "timezone": "Europe/London",
  "interests": "abc123",
  "firstaccess": "2022-04-17",
  "lastaccess": "2022-04-17",
  "url": "https://www.example.com/~rwoodhouse/",
  "skype": "rebecca.woodhouse",
  "custom_fields": [
    {"shortname": "worklocation", "data": "Remote"},
    {"shortname": "employeeid", "data": "456789"}
  ]
}
Types

core_user_create_user_input

Description

Input provided when creating a user.

Fields
Input Field Description
username - String!

Username for the user. This field is used in combination with the password for logging in with some authentication types. Username must be unique on the site.
email - param_email!

Email address of the user. Must be unique unless 'allowaccountssameemail' setting is enabled (not recommended).
password - String!

Initial password for user. This will only be used with certain auth methods such as 'manual'.
firstname - String!

First name of the user.
lastname - String!

Last name of the user.
idnumber - String

The id number of the user.
firstnamephonetic - String

Optional phonetic spelling of the user's first name.
lastnamephonetic - String

Optional phonetic spelling of the user's last name.
middlename - String

Middle name of the user.
alternatename - String

Alternate name of the user.
city - String

City where the user is located. If not provided the system will use the admin setting 'defaultcity' if set.
description - String

Rich-text description field for the user's profile.
descriptionformat - core_format

Format of the description field for the user's profile. See core_format for options.
url - String

URL for the user's profile.
skype - String

Skype username for the user's profile.
institution - String

Institution (organisation) the user belongs to, for the user's profile. This is not connected to job assignment organisation.
department - String

Department the user belongs to.
phone1 - String

Primary phone number of the user.
phone2 - String

Secondary phone number of the user.
address - String

The user's address.
country - String

ISO-3166 two-letter country code of the user, e.g. 'NZ'. Country code list: https://en.wikipedia.org/wiki/List_of_ISO_3166_country_codes.
timezone - String

Timezone of the user, as a string, for example 'Pacific/Auckland'. If not provided the value from the admin setting 'timezone' will be used instead. We recommend using location-based timezones rather than UTC+1 etc. A list of available timezones can be found at https://www.php.net/manual/en/timezones.php.

Note that if the admin setting 'forcetimezone' is configured, any value provided here will be stored but not displayed/used - the forcetimezone value will be used instead.
lang - String

Language of the user, for example 'en_us'. Valid options depend on the site's installed language packs.
theme - String

Theme setting for the user. If the Totara system setting for 'allow user themes' is enabled, then a valid theme name will be accepted from this request, e.g. 'ventura'. If the system setting is disabled, then the theme value will be ignored.
auth - String

Authentication plugin for this user, for example 'manual'. The available options will depend on which authentication plugins are installed and enabled on the site.
calendartype - String

Calendar type for this user, for example 'gregorian'. The available options will depend on which calendar plugins are installed and enabled on the site.
emailstop - Boolean

Whether this user should be completely prevented from receiving any email notifications. Default is false.
suspended - Boolean

Whether this user should be marked as suspended. Suspended users are unable to log in. Default is false.
tenant - totara_tenant_tenant_reference

A reference to a tenant that the user should be assigned to. The API client must be permitted to assign the specified tenant. If not given the user will be automatically assigned based on the API client's tenant, or to the System.

Ignored if multitenancy is disabled.
custom_fields - [core_user_custom_field_input!]

Optional array of custom profile field data (each array element describes a single custom field value for this user).
Example
{
  "username": "rebecca.woodhouse",
  "email": "rebecca.woodhouse@example.com",
  "password": "supersecret",
  "firstname": "Rebecca",
  "lastname": "Woodhouse",
  "idnumber": "RW1234",
  "firstnamephonetic": "reh BEH kuh",
  "lastnamephonetic": "WUUD hows",
  "middlename": "Jane",
  "alternatename": "Becky",
  "city": "London",
  "description": "I have an interest in agile project management and software development.",
  "descriptionformat": "PLAIN",
  "url": "https://www.example.com/~rwoodhouse/",
  "skype": "rebecca.woodhouse",
  "institution": "Acme Inc.",
  "department": "Marketing",
  "phone1": "+64 4 555 1234",
  "phone2": "+64 21 555 1234",
  "address": "1 Civic Square, London, England",
  "country": "United Kingdom",
  "timezone": "Europe/London",
  "lang": "en",
  "theme": "ventura",
  "auth": "manual",
  "calendartype": "gregorian",
  "emailstop": true,
  "suspended": true,
  "tenant": {"idnumber": "tenant1"},
  "custom_fields": [
    {"shortname": "worklocation", "data": "Remote"},
    {"shortname": "employeeid", "data": "456789"}
  ]
}
Types

core_user_custom_field

Description

Type containing read-only custom field data. Each object of this type represents the value of the field. The format of this string will depend on the custom field type it is representing but will contain the field's stored value.

Fields
Field Name Description
shortname - String! Shortname of the custom field the data relates to.
data - String! The custom field data value for this user. Returns the value stored in the database for this user and field, without any processing (such as inserting field default when value is empty, or converting of timestamps to human-readable strings).
data_format - Int

Format of the stored value of the data field. Provided at the time the data is stored, see the core_user_custom_field_input input type for more information. Currently only used by the text area custom field type when rendering in the UI.

Options are:

  • 1: HTML
  • 2: Plain text
  • 4: Markdown
  • 5: JSON
Example
{"shortname": "employeeid", "data": "EM12345", "data_format": 1}
Types

core_user_custom_field_input

Description

Input type representing a single custom field for a particular user.

Fields
Input Field Description
shortname - String!

Shortname is used to uniquely identify the custom field the data is for. It must exactly match the shortname of a custom field that exists on the site or an error will be thrown. Note if the same shortname is provided multiple times in a request (not recommended) they will be applied in order so the last one will be used.
data - String!

Represents the value for the custom field for this user. The format of this data will depend on the field type of the field specified by shortname:

  • checkbox: string of 0 (unchecked) or 1 (checked).
  • menu: A string exactly matching one of the menu options (case sensitive).
  • text: A string of plain-text.
  • textarea: A string of formatted text, in the format specified via the data_format field (see below).
  • datetime: A string in the format YYYY-MM-DD or YYYY-MM-DD-HH-MM-SS (depending on if the field uses the 'Include time?' option). If the field defines a year range, the input will be validated to ensure it falls within that range. If only YYYY-MM-DD is provided for a field where 'Include time?' is enabled, midnight will be used for the time. Stored as a unix timestamp using the timezone of the client's service account.
  • date: A string in the format YYYY-MM-DD. Stored as a timestamp so uses noon UTC for time to ensure date displayed is consistent across most timezones.
data_format - Int

Optional property, which must be provided textarea field types but should not be passed for other types. Used to record the format of the 'data' field so it can be correctly rendered. Options are:

  • 1: HTML
  • 2: Plain-text
  • 4: Markdown
  • 5: JSON
Example
{"shortname": "employeeid", "data": "EM12345", "data_format": 1}
Types

core_user_delete_user_result

Description

Mutation result type returned after deletion of a user.

Returns the id of deleted user if it was deleted successfully.

Fields
Field Name Description
user_id - core_id! Internal database id of the user that was just deleted from the system.
Example
{"user_id": 4}
Types

core_user_update_user_input

Description

Input provided when updating a user.

Fields
Input Field Description
username - param_username

Username for the user. This field is used in combination with the password for logging in with some authentication types. Username must be unique on the site.
firstname - String

First name of the user.
lastname - String

Last name of the user.
email - param_email

Email address of the user. Must be unique unless 'allowaccountssameemail' admin setting is enabled.
password - String

New password for the user. This will only be used with certain auth methods such as 'manual'.
idnumber - String

The id number of the user.
firstnamephonetic - String

Optional phonetic spelling of the user's first name.
lastnamephonetic - String

Optional phonetic spelling of the user's last name.
middlename - String

Middle name of the user.
alternatename - String

Alternate name of the user.
city - String

City where the user is located. If not provided the system will use the admin setting 'defaultcity' if set.
description - String

Rich-text description field for the user's profile.
descriptionformat - core_format

Rich-text format of the description field.
url - String

URL for the user's profile.
skype - String

Skype username for the user's profile.
institution - String

Institution (organisation) the user belongs to, for the user's profile. This is not connected to job assignment organisation.
department - String

Department the user belongs to.
phone1 - String

Primary phone number of the user.
phone2 - String

Secondary phone number of the user.
address - String

The user's address.
country - String

ISO-3166 two-letter country code of the user, e.g. 'NZ'. Country code list: https://en.wikipedia.org/wiki/List_of_ISO_3166_country_codes.
timezone - String

Timezone of the user, as a string, for example 'Pacific/Auckland'. We recommend using location-based timezones rather than UTC+1 etc. A list of available timezones can be found at https://www.php.net/manual/en/timezones.php.

Note that if the admin setting 'forcetimezone' is configured, any value provided here will be stored but not displayed/used - the forcetimezone value will be used instead.
lang - String

Language of the user, for example 'en_us'. Valid options depend on the site's installed language packs.
theme - String

Theme setting for the user. If the admin setting 'allowuserthemes' is enabled, then a valid theme name will be accepted from this request, e.g. 'ventura'. If that admin setting is disabled, then the theme value will be ignored.
auth - String

Authentication plugin for this user, for example 'manual'. The available options will depend on which authentication plugins are installed and enabled on the site.
calendartype - String

Calendar type for this user, for example 'gregorian'. The available options will depend on which calendar plugins are installed and enabled on the site.
emailstop - Boolean

Whether this user should be completely prevented from receiving any email notifications. Default is false.
suspended - Boolean

Whether this user should be marked as suspended. Suspended users are unable to log in. Default is false.
tenant - totara_tenant_tenant_reference

A reference to a tenant that the user should be assigned to. The API client must be permitted to assign the specified tenant.
custom_fields - [core_user_custom_field_input!]

Optional array of custom profile field data (each array element describes a single custom field value for this user).
Example
{
  "username": "rebecca.woodhouse",
  "firstname": "Rebecca",
  "lastname": "Woodhouse",
  "email": "rebecca.woodhouse@example.com",
  "password": "supersecret",
  "idnumber": "RW1234",
  "firstnamephonetic": "reh BEH kuh",
  "lastnamephonetic": "WUUD hows",
  "middlename": "Jane",
  "alternatename": "Becky",
  "city": "London",
  "description": "I have an interest in agile project management and software development.",
  "descriptionformat": "PLAIN",
  "url": "https://www.example.com/~rwoodhouse/",
  "skype": "rebecca.woodhouse",
  "institution": "Acme Inc.",
  "department": "Marketing",
  "phone1": "+64 4 555 1234",
  "phone2": "+64 21 555 1234",
  "address": "1 Civic Square, London, England",
  "country": "United Kingdom",
  "timezone": "Europe/London",
  "lang": "en",
  "theme": "ventura",
  "auth": "manual",
  "calendartype": "gregorian",
  "emailstop": true,
  "suspended": true,
  "tenant": {"idnumber": "tenant1"},
  "custom_fields": [
    {"shortname": "worklocation", "data": "Remote"},
    {"shortname": "employeeid", "data": "456789"}
  ]
}
Types

core_user_user_reference

Description

Input for identifying a user.

The user must be specified by providing one of the following:

  • The user's internal database id
  • The user's idnumber
  • The user's username
  • The user's email address

A user reference must uniquely identify a single user to be valid. Deleted users are excluded, as are users not accessible due to multitenancy restrictions.

Fields
Input Field Description
id - core_id

Internal database id of the user.
username - String

Username of the user.
idnumber - String

The id number of the user.
email - String

Email address of the user.
Example
{
  "id": 5,
  "username": "target.user",
  "idnumber": "EM12345",
  "email": "target.user@example.com"
}
Types

core_user_user_result

Description

Mutation result type returned after creation of a new user or updates to an existing user. Returns the user that was created or updated.

Fields
Field Name Description
user - core_user! User object for the user that was created or updated as part of the operation.
Example
{
  "user": {
    "id": 4,
    "username": "jsmith",
    "email": "jsmith@example.com",
    "firstname": "John",
    "lastname": "Smith",
    "custom_fields": [{"shortname": "employeeid", "data": "EM12345"}]
  }
}
Types

core_user_users_query

Description

Input type used when querying for a list of users. Specifies pagination and sorting information that can impact the structure of the results.

Fields
Input Field Description
pagination - core_pagination_input

Pagination information such as which page to return and the number of results requested.
sort - [core_sort_input!]

The sort order of the query. Allowed entity fields for the sort column are 'id', 'firstname', 'lastname', 'username' and 'timemodified'.
Example
{
  "pagination": {
    "cursor": "eyJsaW1pdCI6MSwiY29sdW1ucyI6eyJpZCI6M319",
    "limit": 20
  },
  "sort": [{"column": "timemodified", "direction": "ASC"}]
}
Types

core_user_users_result

Description

Result returned from the core_user_users query. Contains a page of results along with pagination information.

Fields
Field Name Description
items - [core_user!]! Array of one page of users returned by the query.
total - Int! Total number of users from this query (across all pages).
next_cursor - String! Cursor to request the next set of results for this query.
Example
{
  "items": [
    {
      "username": "test",
      "firstname": "Test",
      "lastname": "User",
      "email": "testuser@example.com"
    },
    {
      "username": "another",
      "firstname": "Another",
      "lastname": "User",
      "email": "anotheruser@example.com"
    }
  ],
  "total": 47,
  "next_cursor": "eyJsaW1pdCI6MSwiY29sdW1ucyI6eyJpZCI6M319"
}

Web API

Queries

totara_webapi_status

Description

Simple query returning "ok" to test that you are able to successfully execute GraphQL queries.

Response

Returns a totara_webapi_status

Example

Query
query totara_webapi_status {
  totara_webapi_status {
    status
    timestamp
  }
}
Response
{
  "data": {
    "totara_webapi_status": {
      "status": "ok",
      "timestamp": "2022-04-17"
    }
  }
}

Types

totara_webapi_status

Description

Type containing information about the current status of the API. status is always 'ok'. This is intended to test that you are able to successfully execute GraphQL queries.

Fields
Field Name Description
status - String! The status of the API (always returns 'ok' if working).
timestamp - core_date Timestamp of the request.
Arguments
format - core_date_format

Format of the timestamp in the response.
Example
{"status": "ok", "timestamp": "2022-04-17"}
Documentation by Anvil SpectaQL