Process API

Introduction

The Process API allows interaction with process instances and workflow variables for a specific process within your Joget application. It provides various methods to control and retrieve information about process activities, including aborting, completing, or cloning instances.

Plugin information

This documentation covers the available API endpoints for managing and interacting with process instances in your Joget application. Each endpoint provides a method for manipulating a specific part of the process.

Get started

Prerequisites

• You have a Joget application with processes configured.
• You have administrative access or proper API keys set up for the operations.

Where to get the plugin

The Process API is part of the core Joget platform, so no additional plugin is required.

How to use it

Below is a guide on using the Process API to manage and interact with processes in your Joget application.

1. Drag and drop the Process API from the Palette to the Canvas.
2. Select Process
3. Enter Short Description (optional)
4. Select the endpoints

• Process: Select any process present in the current app for interaction with API.
• Short Description: Any description

 

List of API Endpoints

Abort activity instance

Abort an activity instance in a running process instance.

URL: /process/*yourProcessId*/abortActivity/{processId}/{activityId}

HTTP Method: POST

Path Parameters

Parameter	Description
processId	Process Instance ID.
activityId	Activity Instance ID.

Sample Response

{
  "date": "Thu Aug 29 18:33:39 SGT 2019",
  "code": "200",
  "message": "Successful operation"
}

 

Abort process instance

Abort a process instance.

URL: /process/*yourProcessId*/abortProcess/{processId}

HTTP Method: POST

Path Parameters

Parameter	Description
processId	Process Instance ID.

Sample Response

{
  "date": "Thu Aug 29 18:35:31 SGT 2019",
  "code": "200",
  "message": "Successful operation"
}

 

Complete activity instance

Complete an activity instance to continue the flow of a process instance.

URL: /process/*yourProcessId*/completeActivity/{processId}/{activityId}

HTTP Method: POST

Path Parameters

Parameter	Description
processId	Process Instance ID.
activityId	Activity Instance ID.

Sample Response

{
  "date": "Thu Aug 29 18:41:53 SGT 2019",
  "code": "200",
  "message": "Successful operation"
}

 

Clone running process instance

Essentially, cloning a running process instance along with its state and workflow variable(s) to a new process instance.

An option is available to abort the original running process instance simultaneously.

URL: /process/*yourProcessId*/copyProcess/{processId}

HTTP Method: POST

Path Parameters

Parameter	Description
processId	Process Instance ID.

Query String Parameters

Parameter	Description
abortCurrent	Abort the original running process instance. Expect a boolean.

Sample Response

{
  "processId": "152_expenseclaim_process1",
  "recordId": "747ada41-a7e8-4537-a060-ae7daface7b5",
  "activities": [
    "393_152_expenseclaim_process1_new_claim"
  ]
}

 

Get Activity instance detail

Get details of an activity instance in a process instance.

URL: /process/*yourProcessId*/getActivityDetail/{processId}/{activityId}

HTTP Method: GET

Path Parameters

Parameter	Description
processId	Process Instance ID.
activityId	Activity Instance ID.

Sample Response

{
  "finishTime": "",
  "variables": {
    "SelectApprover": "admin",
    "status": ""
  },
  "serviceLevelMonitor": "-",
  "dueDate": "",
  "activityName": "HOD Approve",
  "activityDefId": "approve_claim",
  "processVersion": "7",
  "participant": "approver",
  "activityId": "384_149_expenseclaim_process1_approve_claim",
  "processId": "149_expenseclaim_process1",
  "processName": "Expense Approval Process",
  "createdTime": "Wed Aug 28 15:03:15 SGT 2019",
  "assignee": [
    "admin"
  ],
  "processDefId": "expenseclaim#7#process1"
}

 

Get activity instance workflow variables

Get the workflow variables and their values from an activity instance.

URL: /process/*yourProcessId*/getActivityVariables/{processId}/{activityId}

HTTP Method: GET

Path Parameters

Parameter	Description
processId	Process Instance ID.
activityId	Activity Instance ID.

Sample Response

{
  "SelectApprover": "admin",
  "status": "",
    .....
}

 

Get process instance detail

Get details of a process instance.

URL: /process/*yourProcessId*/getProcessDetail/{processId}

HTTP Method: GET

Path Parameters

Parameter	Description
processId	Process Instance ID.

Sample Response

{
  "requester": "admin",
  "startedTime": "",
  "finishTime": "",
  "variables": {
    "SelectApprover": "admin",
    "status": ""
  },
  "serviceLevelMonitor": "-",
  "processId": "149_expenseclaim_process1",
  "dueDate": "",
  "packageId": "expenseclaim",
  "name": "Expense Approval Process",
  "processDefId": "expenseclaim#7#process1",
  "version": "7",
  "states": "open.running"
}

 

Get process instance workflow variables

Get the workflow variables and their values from a process instance.

URL: /process/*yourProcessId*/getVariables/{processId}

HTTP Method: GET

Path Parameters

Parameter	Description
processId	Process Instance ID.

Sample Response

{
  "SelectApprover": "admin",
  "status": "",
    .....
}

 

List activity instances

List all activity instances of a process instance.

URL: /process/*yourProcessId*/listActivities/{processId}

HTTP Method: GET

Path Parameters

Parameter	Description
processId	Process Instance ID.

Query String Parameters

Parameter	Description
sort	Activity list 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

[
  {
    "dateCreated": "28-08-2019 03:03 PM",
    "serviceLevelMonitor": "-",
    "name": "HOD Approve",
    "id": "384_149_expenseclaim_process1_approve_claim",
    "state": "open.not_running.not_started"
  },
    .....
]

 

List completed process instances

List all completed process instance(s) of the specified process.

URL: /process/*yourProcessId*/listCompleted

HTTP Method: GET

Query String Parameters

Parameter	Description
sort	Completed processes list 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

[
  {
    "startedTime": "25-04-2019 08:14 PM",
    "requesterId": "admin",
    "serviceLevelMonitor": "-",
    "due": "-",
    "name": "Expense Approval Process",
    "id": "44_expenseclaim_process1",
    "state": "closed.aborted",
    "version": "1"
  },
    .....
]

 

List running process instances

List all running process instance(s) of the specified process.

URL: /process/*yourProcessId*/listRunning

HTTP Method: GET

Query String Parameters

Parameter	Description
sort	Running processes list 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

[
  {
    "startedTime": "26-08-2019 07:29 PM",
    "requesterId": "admin",
    "serviceLevelMonitor": "-",
    "due": "-",
    "name": "Expense Approval Process",
    "id": "149_expenseclaim_process1",
    "state": "open.running",
    "version": "7"
  },
    .....
]

 

Reassign activity instance

Explicitly set a user to replace an existing assignee of an activity instance via username.

URL: /process/*yourProcessId*/reassignActivity/{processId}/{activityId}

HTTP Method: POST

Path Parameters

Parameter	Description
processId	Process Instance ID.
activityId	Activity Instance ID.

Query String Parameters

Parameter	Description
assignee	Username of the original user assigned to the task.
replacement	Username of the user to replace the assignee.

Sample Response

{
  "date": "Thu Aug 29 19:27:03 SGT 2019",
  "code": "200",
  "message": "Successful operation"
}

 

Reevaluate activity instance

Update/Replace the assignee(s) of an activity instance according to the current participant mapping of the specified process.

URL: /process/*yourProcessId*/reevaluateActivity/{processId}/{activityId}

HTTP Method: POST

Path Parameters

Parameter	Description
processId	Process Instance ID.
activityId	Activity Instance ID.

Sample Response

{
  "date": "Thu Aug 29 19:32:19 SGT 2019",
  "code": "200",
  "message": "Successful operation"
}

 

Set activity instance workflow variables

Set the values of an activity instance's workflow variable(s).

URL: /process/*yourProcessId*/setActivityVariables/{processId}/{activityId}

HTTP Method: POST

Path Parameters

Parameter	Description
processId	Process Instance ID.
activityId	Activity Instance ID.

Query String Parameters

The parameters required here are highly dependent on the app/process design.

Parameter	Description
variables	Workflow variables and their values.

Sample Response

{
  "date": "Thu Aug 29 21:32:19 SGT 2019",
  "code": "200",
  "message": "Successful operation"
}

 

Start activity of a process instance

Start an activity instance in a process instance.

Option available to simultaneously abort the current running activity instance in the specified process instance.

URL: /process/*yourProcessId*/startActivity/{processId}/{activityDefId}

HTTP Method: POST

Path Parameters

Parameter	Description
processId	Process Instance ID. Expect the ID of an existing process instance.
activityDefId	Activity Definition ID.

Query String Parameters

Parameter	Description
abortCurrent	Abort the current running activity instance in the process instance. Expect a boolean.

Sample Response

{
  "processId": "152_expenseclaim_process1",
  "recordId": "747ada41-a7e8-4537-a060-ae7daface7b5",
  "activities": [
    "394_152_expenseclaim_process1_approve_claim"
  ]
}

 

Start process by current user

Start a new process instance of the specified process as the currently logged in user.

URL: /process/*yourProcessId*/startProcess

HTTP Method: POST

Query String Parameters

Parameter	Description
processInstanceId	Process Instance ID of a process that has been created but not started.
recordId	Populate the process instance's starting activity form with an existing record.

Body Parameters

The workflow variable(s) parameter required here highly depends on the app/process design. Example:

{
  "additionalProp1": "string",
  "additionalProp2": "string",
  "additionalProp3": "string"
}

Sample Response

{
  "processId": "153_expenseclaim_process1",
  "recordId": "747ada41-a7e8-4537-a060-ae7daface7b5",
  "activities": [
    "395_153_expenseclaim_process1_new_claim"
  ]
}

 

Start process by username

Start a new process instance of the specified process on behalf of a user via username.

URL: /process/*yourProcessId*/startProcessByUser/{username}

HTTP Method: POST

Path Parameters

Parameter	Description
username	Username of a Joget user.

Query String Parameters

Parameter	Description
processInstanceId	Process Instance ID of a process that has been created but not started.
recordId	Populate the process instance's starting activity form with an existing record.

Body Parameters

The workflow variable(s) parameter required here highly depends on the app/process design. Example:

{
  "additionalProp1": "string",
  "additionalProp2": "string",
  "additionalProp3": "string"
}

Sample Response

{
  "processId": "154_expenseclaim_process1",
  "recordId": "747ada41-a7e8-4537-a060-ae7daface7b5",
  "activities": [
    "396_154_expenseclaim_process1_new_claim"
  ]
}