Statement Resource

Manages learner statements.

sendStatement

Sends a statement to the LRS.

Examples

Example 1: Send Basic Statement

import XAPI, { Statement } from "@xapi/xapi";

// new XAPI() etc

const myStatement: Statement = {
  actor: {
    objectType: "Agent",
    name: "Test Agent",
    mbox: "mailto:hello@example.com"
  },
  verb: {
    id: "http://example.com/verbs/tested",
    display: {
        "en-GB": "tested"
    }
  },
  object: {
    objectType: "Activity",
    id: "https://github.com/xapijs/xapi"
  }
};

xapi.sendStatement({
  statement: myStatement
});

Example 2: Send Embedded Attachment Statement

import CryptoJS from "crypto-js";
import { arrayBufferToWordArray } from "...";

const attachmentContent: string = "hello world";
const arrayBuffer: ArrayBuffer = new TextEncoder().encode(attachmentContent);

const myStatement: Statement = {
  // actor, verb, object etc,
  attachments: [{
    usageType: XAPI.AttachmentUsages.SUPPORTING_MEDIA,
    display: {
        "en-US": "Text Attachment"
    },
    description: {
        "en-US": `The text attachment contains "${attachmentContent}"`
    },
    contentType: "text/plain",
    length: arrayBuffer.byteLength,
    sha2: CryptoJS.SHA256(arrayBufferToWordArray(arrayBuffer)).toString()
  }]
}

xapi.sendStatement({
  statement: myStatement,
  attachments: [arrayBuffer]
});

This example requires CryptoJS to generate a sha2 of the attachment data and convert the array buffer to a word array.

Parameters

Parameter

Type

Required

Description

statement

true

The statement you wish to send to the LRS.

attachments

ArrayBuffer[]

false

An array of attachment data converted to ArrayBuffer.

Returns

This method returns an AxiosPromise with the success data containing a string array of statement IDs if successful, or if unsuccessful the rejection contains an error message.

sendStatements

Sends multiple statements to the LRS.

Example 1: Send Basic Statements

import XAPI, { Statement } from "@xapi/xapi";

// new XAPI() etc

const myStatement: Statement = {
  actor: {
    objectType: "Agent",
    name: "Test Agent",
    mbox: "mailto:hello@example.com"
  },
  verb: {
    id: "http://example.com/verbs/tested",
    display: {
        "en-GB": "tested"
    }
  },
  object: {
    objectType: "Activity",
    id: "https://github.com/xapijs/xapi"
  }
};

// Define another statement
const myStatementTwo: Statement = {
  ...myStatement
};

xapi.sendStatements({
  statements: [myStatement, myStatementTwo]
});

Example 2: Send Embedded Attachment Statements

import CryptoJS from "crypto-js";
import { arrayBufferToWordArray } from "...";

const attachmentContent: string = "hello world";
const arrayBuffer: ArrayBuffer = new TextEncoder().encode(attachmentContent);

const myStatement: Statement = {
  // actor, verb, object etc,
  attachments: [{
    usageType: XAPI.AttachmentUsages.SUPPORTING_MEDIA,
    display: {
        "en-US": "Text Attachment"
    },
    description: {
        "en-US": `The text attachment contains "${attachmentContent}"`
    },
    contentType: "text/plain",
    length: arrayBuffer.byteLength,
    sha2: CryptoJS.SHA256(arrayBufferToWordArray(arrayBuffer)).toString()
  }]
}

// Define another statement
const myStatementTwo: Statement = {
  ...myStatement
};

// Send through the attachments in the same sequence as they
// appear in the statements, for brevity we are using the same
// attachment here twice

xapi.sendStatement({
  statements: [myStatement, myStatementTwo],
  attachments: [arrayBuffer, arrayBuffer]
});

This example requires CryptoJS to generate a sha2 of the attachment data and convert the array buffer to a word array.

Parameters

Parameter

Type

Required

Description

statements

true

The statements you wish to send to the LRS.

attachments

ArrayBuffer[]

false

An array of attachment data converted to ArrayBuffer.

Returns

This method returns an AxiosPromise with the success data containing a string array of statement IDs if successful, or if unsuccessful the rejection contains an error message.

getStatement

To receive a single statement, you must use the getStatement method and pass the statement ID in the query. Optionally, you can provide additional parameters to the query to change the data format returned from the LRS.

Examples

Example 1: Get Basic Statement

xapi.getStatement({
  statementId: "abcdefgh-1234"
}).then((result: AxiosResponse<Statement>) => {
  const statement: Statement = result.data;
  // do stuff with `statement`
});

Example 2: Get Embedded Attachment Statement

xapi.getStatement({
  statementId: "abcdefgh-1234",
  attachments: true
}).then((result: AxiosResponse<StatementResponseWithAttachments>) => {
  const parts: [Statement, ...Part[]] = result.data;
  const statement: Statement = parts[0];
  const attachment: unknown = parts[1];
})

Parameters

Parameter

Type

Required

Description

statementId

string

true

The identifier of the statement to request.

attachments

boolean

false

Whether to return the attachment(s) associated with the statement, if any.

format

string

false

What human readable names and descriptions are included in the statement.

  • exact format returns the statements exactly as they were received by the LRS.

  • ids only ids are returned with none of the human readable descriptions.

  • canonical format requests the LRS to return its own internal definitions of objects, rather than those provided in the statement.

Returns

This method returns an AxiosPromise with the success data containing the Statement of the supplied statementId.

When getting a statement with attachments: true, the success data is returned as an array. The first array item is of type Statement, and the following are of type Part and are the attachments supplied with the statement.

getStatements

To receive an array of statements based upon a query, you must use the getStatements method. See the GetStatementsQuery interface for a full list of ways to create your query.

Example

const myAgent: Agent = {...};

xapi.getStatements({
  agent: myAgent
}).then((result: AxiosResponse<StatementsResponse>) => {
  const statementsResponse: StatementsResponse = result.data;
  // do stuff with `statementsResponse.statements`
});

Parameters

Parameter

Type

Required

Description

agent

Agent

false

The agent to filter the query by.

verb

string

false

The verb identifier to filter the query by.

activity

string

false

The activity identifier to filter the query by.

registration

string

false

The registration to filter the query by.

related_activities

boolean

false

Whether to include any activity in the statement as part of the filter to query by.

related_agents

boolean

false

Whether to include any agent in the statement as part of the filter to query by.

since

Timestamp (ISOString)

false

Filters only statements after the given Timestamp.

until

Timestamp (ISOString)

false

Filters only statements before the given Timestamp.

limit

number

false

Number of statements to return.

ascending

boolean

false

Determines whether to return the statements in ascending order.

attachments

boolean

false

Determines whether to return the attachments for the resulting statements.

Returns

This method returns an AxiosPromise with the success data containing a StatementsResponse object.

When getting statements with attachments: true, the success data is returned as an array. The first array item is of type StatementsResponse, and the following are of type Part and are the attachments supplied with the statement.

getMoreStatements

To be used in conjunction with getStatements. If the more property is populated on your initial request, more data is available. Send the value of the more property to this method to get the next page of statements.

Example

const myAgent: Agent = {...};

xapi.getStatements({
  agent: myAgent
}).then((result: AxiosReponse<StatementsResponse>) => {
  // data
  xapi.getMoreStatements({
    more: result.data.more
  }).then((result: AxiosResponse<StatementsResponse>) => {
    // more data
  });
});

Parameters

Parameter

Type

Required

Description

more

string

true

The more property passed from the getStatements/getMoreStatements query response.

Returns

This method returns an AxiosPromise with the success data containing a StatementsResponse object or an Array containing StatementsResponse and Part if the original query has attachments: true. When working in TypeScript you may need to cast your result.data return type explicitly as StatementsResponse or StatementsResponseWithAttachments.

voidStatement

Voids a statement in the LRS by the supplied Actor.

Example

const actor: Actor = { ... };
xapi.voidStatement({
  actor: actor,
  statementId: "abcdefgh-1234"
});

Parameters

Parameter

Type

Required

Description

actor

true

The Actor who is voiding the statement e.g. an administrator.

statementId

string

true

The statement to be voided.

Returns

This method returns an AxiosPromise with the success data containing an array of statement ID strings of the void statement.

voidStatements

Voids multiple statements in the LRS by the supplied Actor.

Example

const actor: Actor = { ... };
xapi.voidStatements({
   actor: actor,
   statementIds: ["abcdefgh-1234", "ijklmnop-5678"]
});

Parameters

Parameter

Type

Required

Description

actor

true

The Actor who is voiding the statement e.g. an administrator.

statementIds

string[]

true

The statements to be voided.

Returns

This method returns an AxiosPromise with the success data containing an array of statement ID strings of the void statements.

getVoidedStatement

To receive a single voided statement, you must use the getVoidedStatement method and pass the original statement ID in the query (not the original statement's void statement id). Optionally, you can provide additional parameters to the query to change the data format returned from the LRS.

Example

xapi.getVoidedStatement({
  statementId: "abcdefgh-1234"
}).then((result: AxiosResponse<Statement>) => {
  const voidStatement: Statement = result.data;
  // do stuff with `voidStatement`
});

Parameters

Parameter

Type

Required

Description

voidedStatementId

string

true

The identifier of the voided statement to request.

attachments

boolean

false

Whether to return the attachment(s) associated with the voided statement, if any.

format

string

false

What human readable names and descriptions are included in the voided statement.

  • exact format returns the statements exactly as they were received by the LRS.

  • ids only ids are returned with none of the human readable descriptions.

  • canonical format requests the LRS to return its own internal definitions of objects, rather than those provided in the statement.

Returns

This method returns an AxiosPromise with the success data containing the Statement of the supplied voidedStatementId.

When getting a statement with attachments: true, the success data is returned as an array. The first array item is of type Statement, and the following are of type Part and are the attachments supplied with the statement.

PreviousThe XAPI ClassNextState Resource

Last updated