diff --git a/openapi/components/examples/problem-internalServerError.yaml b/openapi/components/examples/problem-internalServerError.yaml index decc86f1..3a6d2920 100644 --- a/openapi/components/examples/problem-internalServerError.yaml +++ b/openapi/components/examples/problem-internalServerError.yaml @@ -2,4 +2,4 @@ value: type: about:blank title: Internal Server Error status: 500 - detail: An unexpected error occured when accessing resource with ID=1. This error has been logged. + detail: An unexpected error occurred when accessing resource with ID=1. This error has been logged. diff --git a/openapi/components/requestBodies/pastoral-partial-item.yaml b/openapi/components/requestBodies/pastoral-partial-item.yaml new file mode 100644 index 00000000..a98297e8 --- /dev/null +++ b/openapi/components/requestBodies/pastoral-partial-item.yaml @@ -0,0 +1,118 @@ +description: | + Pastoral record +content: + application/json: + schema: + type: object + properties: + heading: + description: Pastoral record title. + type: string + maxLength: 255 + occurredOn: + description: The date on which this is occurred in the format configured in your Admin area. This also accepts RFC3339 format such as 2021-06-22T01:23:45+10:00 + type: string + format: date + example: 2021-06-22T01:23:45+10:00 + nullable: true + typeId: + description: The ID of a pastoral type to associate with this pastoral record. + type: integer + nullable: false + subtypeId: + description: | + The ID of a pastoral sub-type to associate to this pastoral record.\ + The sub-type must already be associated with the type provided as typeId.\ + This can be null, if the pastoral type does not have any sub-type.\ + This cannot be null, if the pastoral type has sub-type(s). + type: integer + nullable: true + severityId: + description: | + The ID of a pastoral severity to associate with this pastoral record.\ + Required only if Allow specification of severity on pastoral records config is ON. + type: integer + nullable: true + body_public: + description: | + General content of this pastoral record in raw HTML.\ + The following tokens will be substituted with the students details on creation: [firstname], [preferredname], [surname], [fullname], [year], [house]. + type: string + maxLength: 65535 + nullable: true + body_private: + description: | + Confidential content of this pastoral record in raw HTML.\ + The following tokens will be substituted with the students details on creation: [firstname], [preferredname], [surname], [fullname], [year], [house]. + type: string + maxLength: 65535 + nullable: true + actions[]: + description: | + An array of IDs of pastoral action.\ + Available only if Enable Pastoral Actions config is ON. + type: array + nullable: true + items: + type: integer + tags: + description: | + Comma separated IDs of existing Pastoral Record Tags.\ + If non numerical string is provided, it'll be silently discarded.\ + To provide a name to create a new tag, use tagNames instead. + type: string + nullable: true + tagNames: + description: | + Comma separated names of Pastoral Record Tags.\ + If Allow Staff to Create Pastoral Care Tags config is ON, attempts to create a new tag, if not alraeady exists.\ + The max length of a tag name is 255 chars. + type: string + nullable: true + points: + description: Points of this pastoral record. + type: number + format: float + minimum: -100000 + maximum: 100000 + nullable: true + role: + description: | + An array of pairs of a role and its access level to this pastoral record in the format of:\ + `$roleId => $accessLevel` + * `$roleId` is one of the following: + * The ID of a role of Staff Role Type with Access Pastoral Care permission + * 'role-type-parent' (requires Allow Parent Pastoral Access config enabled) + * 'role-type-student' (requires Allow Student Pastoral Access config enabled) + * `$accessLevel` is an integer representation of access level of the $roleId + * 0 - Deny + * 1 - General + * 2 - General + Confidential + type: array + nullable: true + group: + description: | + An array of pairs of a pastoral group and its access level to this pastoral record in the format of:\ + `$pastoralGroupId => $accessLevel` + * `$pastoralGroupId` is the ID of a pastoral group to set access level to + * `$accessLevel` is an integer representation of access level of the $roleId + * 0 - Deny + * 1 - General + * 2 - General + Confidential + type: array + nullable: true + user: + description: | + An array of pairs of a user and its access level to this pastoral record in the format of:\ + `$userId => $accessLevel` + * `$userId` is ID of a user to set access level to. The user must be one of: + * a staff with pastoral access + * a parent of the student (requires Allow Parent Pastoral Access enabled) + * `$accessLevel` is an integer representation of access level of the $roleId + * 0 - Deny + * 1 - General + * 2 - General + Confidential + type: array + nullable: true + required: + - id diff --git a/openapi/components/schemas/pastoral-item.yaml b/openapi/components/schemas/pastoral-item.yaml index fd569111..2aacad54 100644 --- a/openapi/components/schemas/pastoral-item.yaml +++ b/openapi/components/schemas/pastoral-item.yaml @@ -115,7 +115,7 @@ items: sequence: description: The order in which this pastoral severity will display in a pastoral severity list. type: integer - occuredOn: + occurredOn: description: The date on which this is occurred as a RFC3339 string. type: string format: date-time diff --git a/openapi/components/schemas/pastoral-partial-item.yaml b/openapi/components/schemas/pastoral-partial-item.yaml new file mode 100644 index 00000000..65fefa85 --- /dev/null +++ b/openapi/components/schemas/pastoral-partial-item.yaml @@ -0,0 +1,287 @@ +title: a partial Pastoral Record +description: A partial pastoral record. +readOnly: true +type: array +items: + properties: + id: + $ref: ./id.yaml + externalId: + description: The ID of SIS data corresponding to this pastoral record, if External Pastoral Synchronisation is ON. + type: string + nullable: true + student: + title: User + description: Short fields for users + type: object + properties: + id: + $ref: ./id.yaml + externalId: + $ref: ./externalId.yaml + title: + type: string + nullable: true + description: The user's title (Mr., Ms., etc.). + example: Ms + firstName: + type: string + nullable: true + description: | + The user's first name. + + Schoolbox doesn't distinguish between a person's actual first name + and any other names, and in any case is not the definitive source of + naming information; therefore in practice this will usually be the + user's given name. + example: Rebecca + lastName: + type: string + nullable: true + description: The user's surname. + example: White + preferredName: + type: string + nullable: true + description: The user's preferred name. + _links: + type: object + properties: + profile: + type: string + format: uri-reference + avatar: + type: string + format: uri-reference + nullable: true + heading: + description: Heading of the pastoral record. + type: string + type: + description: Type of the pastoral record. + type: object + properties: + id: + description: The ID of the pastoral type associated to this pastoral record. + type: integer + name: + description: The name of the pastoral type. + type: string + icon: + description: The name of the icon associated to the pastoral type. + type: string + colour: + description: The colour of the icon associated to the pastoral type. + type: string + sentiment: + type: string + sequence: + description: The order in which this pastoral type will display in a pastoral type list. + type: integer + subType: + description: Sub-type of the pastoral record. + type: object + properties: + id: + description: The ID of the pastoral sub-type associated to this pastoral record. + type: integer + name: + description: The name of the pastoral sub-type. + type: string + icon: + description: The name of the icon associated to the pastoral sub-type. + type: string + colour: + description: The colour of the icon associated to the pastoral sub-type. + type: string + sentiment: + type: string + sequence: + description: The order in which this pastoral sub-type will display in a pastoral sub-type list. + type: integer + severity: + description: Severity of the pastoral record. + type: object + properties: + id: + description: The ID of the pastoral severity of this pastoral record. + type: integer + name: + description: The name of the pastoral severity. + type: string + color: + description: The colour associated to the pastoral severity. + type: string + sequence: + description: The order in which this pastoral severity will display in a pastoral severity list. + type: integer + occurredOn: + description: The date on which this is occurred as a RFC3339 string. + type: string + format: date-time + points: + nullable: true + description: Points of this pastoral record. + type: integer + tags: + description: List of tag names. + type: array + items: + properties: + id: + description: The ID of the pastoral tag. + type: integer + name: + description: The name of the pastoral tag. + type: string + bodyPublic: + description: | + General content of this pastoral record in raw HTML. + type: string + bodyPrivate: + description: | + Confidential content of this pastoral record in raw HTML. + type: string + attachmentsPublic: + description: | + Files attached to General content. + type: array + items: + $ref: ./file.yaml + attachmentsPrivate: + description: | + Files attached to Confidential content. + type: array + items: + $ref: ./file.yaml + commentsPublic: + description: | + General comments. + type: array + items: + $ref: ./discussionComment-read.yaml + commentsPrivate: + description: | + Confidential comments + type: array + items: + $ref: ./discussionComment-read.yaml + recordActions: + nullable: true + description: An array of pastoral actions. + type: array + items: + properties: + id: + description: The ID of the pastoral action. + type: integer + name: + description: The name of the pastoral action. + type: string + completed: + description: Whether the action is completed. + type: boolean + updatedAt: + description: The last modified date of the action as a RFC3339 string. + type: string + format: date-time + updatedBy: + $ref: ./userAuthor.yaml + createdBy: + $ref: ./userAuthor.yaml + createdAt: + type: string + format: date-time + description: | + The date as a RFC3339 string. + updatedBy: + $ref: ./userAuthor.yaml + updatedAt: + type: string + format: date-time + description: | + The date as a RFC3339 string. + _links: + type: object + example: + id: 77 + externalId: null + student: + id: 25 + _links: + profile: /search/user/25 + avatar: /portrait.php?id=25&size=square64 + title: Ms + firstName: Jana + preferredName: null + lastName: Reed + fullName: Ms Jana Reed + isDeleted: false + externalId: 507 + heading: Academic Achievement Award - Semester 2 + type: + id: 1 + name: Academic + colour: null + icon: null + sentiment: neutral + sequence: 1 + subType: + id: 1 + name: Award/Achievement + colour: rgba(182, 74, 74, 1.000) + icon: achievement + sentiment: neutral + sequence: 1 + severity: + id: 1 + name: Low + sequence: 1 + color: rgba(0, 128, 0, 1.000) + points: 50 + tags: + - id: 26 + name: test tag A + - id: 27 + name: test tag B + bodyPrivate: null + bodyPublic: Public body\nPublic body. + attachmentsPrivate: [] + attachmentsPublic: + - hash: 723b6e31c2979b33deea852cdbbad9c4b0e00b96 + mime: image/jpeg + type: image + size: 279489 + _links: + fetch: /storage/fetch.php?hash=723b6e31c2979b33deea852cdbbad9c4b0e00b96 + icon: /static/images/mime/application-image-jpg.svg + image: /storage/image.php?hash=723b6e31c2979b33deea852cdbbad9c4b0e00b96 + commentsPrivate: [] + commentsPublic: [] + recordActions: [] + createdBy: + id: 22 + _links: + profile: /search/user/165 + avatar: /portrait.php?id=165&size=square64 + title: + firstName: Jack + preferredName: null + lastName: Coles + fullName: Jack Coles + isDeleted: false + createdAt: 2022-11-14T15:08:21+11:00 + updatedBy: + id: 22 + _links: + profile: /search/user/165 + avatar: /portrait.php?id=165&size=square64 + title: + firstName: Jack + preferredName: null + lastName: Coles + fullName: Jack Coles + isDeleted: false + updatedAt: 2022-11-14T15:08:21+11:00 + _links: + read: /pastoral/student/25/record/77 diff --git a/openapi/openapi.yaml b/openapi/openapi.yaml index e54b7f66..5eed7cfa 100644 --- a/openapi/openapi.yaml +++ b/openapi/openapi.yaml @@ -290,6 +290,9 @@ paths: /pastoral/record/insert: $ref: 'paths/pastoral@record@insert.yaml' + /pastoral/record/{id}/update: + $ref: 'paths/pastoral@record@update.yaml' + /api/curriculum/usage/{id}: $ref: 'paths/api@curriculum@usage@{id}.yaml' diff --git a/openapi/paths/pastoral@record@update.yaml b/openapi/paths/pastoral@record@update.yaml new file mode 100644 index 00000000..f8a6d799 --- /dev/null +++ b/openapi/paths/pastoral@record@update.yaml @@ -0,0 +1,28 @@ +patch: + operationId: pastoral.patchRecordUpdate + tags: [pastoral] + summary: Partially update a pastoral record + parameters: + - $ref: ../components/parameters/id.yaml + description: | + Updates an existing pastoral record with a partial set of changes for brevity, such as updating a heading without needing to specify everything about the pastoral record explicitly. + Only some fields are supported by this endpoint, described below. Any fields outside of this set are disregarded. + Any fields omitted remain unchanged. Note that for updating Pastoral Actions you need to enable the config setting in admin. + + #### Availability + This is accessible only when Pastoral module is enabled. + #### Permission + This endpoint is available for: + * Users with Pastoral Moderator service permission + * Users with a role of Staff role type with Access Pastoral Care permission + responses: + '200': + description: Successfully updated a pastoral record + content: + application/json: + schema: + $ref: ../components/schemas/pastoral-partial-item.yaml + default: + $ref: ../components/responses/problem.yaml + requestBody: + $ref: ../components/requestBodies/pastoral-partial-item.yaml