Grade API

Introduction

The Grade API allows you to interact with grade levels and their associated users within the Joget built-in directory manager. You can add, assign, update, delete, and retrieve grade information through this API.

Plugin information

This API is a part of the Joget platform and does not require a separate plugin. However, it interacts directly with the Joget built-in directory manager.

Get started

Prerequisites

• You should have access to the Joget API and directory manager.
• You need appropriate permissions to manage grades and users within Joget.

Where to get the plugin

No additional plugin is required. The functionality is built into the Joget platform.

How to install

This API is automatically available as part of the Joget platform; no installation is needed.

How to use it

1. Drag and drop the Grade API from the Palette to the Canvas.
2. Select the endpoints

 

List of API Endpoints

Add a grade

Add a new grade.

URL: /grade

HTTP Method: POST

Body Parameters

Parameter	Description
id	Grade ID.
name	Grade name.
description	Description of grade.
organization
id	ID of the organization to which this grade belongs.

Sample Response

{
  "id": "apiTestGrade",
  "name": "API Test Grade",
  "description": "This is a grade created by API.",
  "organization": {
    "id": "ORG-001"
  }
}

 

Assign a user to a grade

Assign a Joget user to a grade.

URL: /grade/assignUser/{grade}/{username}

HTTP Method: POST

Path Parameters

Parameter	Description
grade	Grade ID.
username	Username of Joget user.

Sample Response

{
  "userId": "cat",
  "startDate": null,
  "endDate": null,
  "employeeCode": "",
  "gradeId": "apiTestGrade",
  "departmentId": null,
  "organizationId": "ORG-001"
}

 

Delete a grade

Delete a grade via grade ID.

URL: /grade/{id}

HTTP Method: DELETE

Path Parameter

Parameter	Description
id	Grade ID.

Sample Response

{
  "date": "Wed Aug 28 15:43:58 SGT 2019",
  "code": "200",
  "message": "Successful operation"
}

 

Find grades

Gets all grades from all organizations by default.

Able to filter or sort the returned results via parameters.

URL: /grade/find

HTTP Method: GET

Query String Parameters

Parameter	Description
nameFilter	Filters the response via grade ID.
organizationId	Filter grades that belong to an organization via organization ID.
sort	Grade data column to sort. Must be used in conjunction with sortDescending parameter.
sortDescending	Sort the specified sort parameter value in ascending or descending order. Expect a boolean value. Must be used in conjunction with sort parameter.
startOffset	Starting position of records to start query. Expect an integer.
pageSize	Number of results to return. Expect an integer.

Sample Response

[
  {
    "id": "G-001",
    "name": "Board Members",
    "description": "",
    "organization": {
      "id": "ORG-001"
    }
  },
  {
    "id": "G-002",
    "name": "Managers",
    "description": "",
    "organization": {
      "id": "ORG-001"
    }
  },
    .....
]

 

Get grade by ID

Get details of a grade via grade ID.

URL: /grade/{id}

HTTP Method: GET

Path Parameter

Parameter	Description
id	Grade ID.

Sample Response

{
  "id": "G-001",
  "name": "Board Members",
  "description": "",
  "organization": {
    "id": "ORG-001"
  }
}

 

Unassign a user from a grade

Unassign a Joget user from a grade.

URL: /grade/unassignUser/{grade}/{username}

HTTP Method: DELETE

Path Parameters

Parameter	Description
grade	Grade ID.
username	Username of Joget user.

Sample Response

{
  "date": "Thu Dec 05 03:29:56 SGT 2019",
  "code": "200",
  "message": "Successful operation"
}

 

Update a grade

Update the details of a grade.

URL: /grade

HTTP Method: PUT

Body Parameters

Parameter	Description
id	Grade ID.
name	Grade name.
description	Description of grade.
organization
id	ID of the organization to which this grade belongs.

Sample Response

{
  "id": "apiTestGrade",
  "name": "API Test Grade",
  "description": "This grade is updated via API.",
  "organization": {
    "id": "ORG-001"
  }
}