Department API

Introduction

The Department API allows you to manage departments and their users within the Joget built-in directory manager. You can add, update, delete departments, and assign or unassign users to these departments programmatically.

Plugin information

The Department API is essential for automating department management in Joget applications. It enables the integration of department-related operations within your custom workflows.

Get started

Prerequisites

• You must have access to a Joget environment with the API enabled.
• Basic knowledge of RESTful API usage and JSON format.

Where to get the plugin

The Department API functionality is built into Joget; no separate plugin is required.

How to install

The Department API is pre-installed with Joget. No additional installation steps are necessary.

How to use it

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

 

List of API Endpoints

Add a new department

Add a new department.

URL: /department

HTTP Method: POST

Body Parameters

Parameter	Description
id	Department ID.
name	Department name.
description	Description of department.
organization
id	ID of the organization to which this department belongs.

Sample Response

{
  "id": "apiTestDept",
  "name": "API TEST Department",
  "description": "This is a department created by API.",
  "organization": {
    "id": "ORG-001"
  }
}

 

Assign user to department

Assign a Joget user to a department.

URL: /department/assignUser/{department}/{username}

HTTP Method: POST

Path Parameters

Parameter	Description
department	Department ID.
username	Username of Joget user.

Sample Response

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

 

Delete department

Delete a department via department ID.

URL: /department/{id}

HTTP Method: DELETE

Path Parameters

Parameter	Description
id	Department ID.

Sample Response

{
  "date": "Wed Aug 28 01:29:38 SGT 2019",
  "code": "200",
  "message": "Successful operation"
}

 

Find departments

Gets all departments from all organizations by default. Able to filter or sort the returned results via parameters.

URL: /department/find

HTTP Method: GET

Query String Parameters

Parameter	Description
nameFilter	Filters the response via department ID.
organizationId	Filter departments that belong to an organization via organization ID.
sort	Department 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": "D-001",
    "name": "CEO Office",
    "description": "",
    "organization": {
      "id": "ORG-001"
    }
  },
  {
    "id": "D-002",
    "name": "Human Resource and Admin",
    "description": "",
    "organization": {
      "id": "ORG-001"
    }
  },
    .....
]

 

Get department by ID

Get details of a department via department ID.

URL: /department/{id}

HTTP Method: GET

Path Parameters

Parameter	Description
id	Department ID.

Sample Response

{
  "id": "D-001",
  "name": "CEO Office",
  "description": "",
  "organization": {
    "id": "ORG-001"
  }
}

 

Unassign user from department

Unassign a Joget user from a department.

URL: /department/unassignUser/{department}/{username}

HTTP Method: DELETE

Path Parameters

Parameter	Description
department	Department ID.
username	Username of Joget user

 

Sample Response

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

 

Update department

Update the details of a department.

URL: /department

HTTP Method: PUT

Body Parameters

Parameter	Description
id	Department ID.
name	Department name.
description	Description of department.
organization
id	ID of the organization to which this department belongs.

Sample Response

{
  "id": "apiTestDept",
  "name": "API TEST Department",
  "description": "I update this department description via API.",
  "organization": {
    "id": "ORG-001"
  }
}