REST API Integrations

GWE exposes a RESTful endpoint to allow you to control workflows by starting a new request, doing actions for an existing request or simply getting more information about a request. To take advantage of this integration you need to configure the ARCHIBUS REST service and the GWE REST service.

Prerequisites

Enable REST API in ARCHIBUS

To use the REST capabilities of ARCHIBUS you need to configure the authentication mechanism with a 3rd party identity provider like Okta.
You can read more about how to configure it in ARCHIBUS’ own guide.

Configure GWE REST Controller

If you followed the installation instructions you should already have the rest-servlet.xml file modified to include GWE’s REST controller. However, if you missed that step, you can read it again here.

Endpoints

There is one endpoint that supports 3 http methods in GWE, authenticated with ARCHIBUS’ standard OAuth 2.0 config.
Once you’ve obtained a JWT from your identity provider you can use it to call the GWE endpoint.

The endpoint is

/api/v1/gwe/request

1. Creating Requests

HTTP Method: POST

Headers:

{
    "Content-Type": "application/json",
    "Authorization": "Bearer [jwt]"
}

Body example:

{
    "wf_type": "TECH INCIDENT",
    "user_name": "AFM",
    "description": "Requested created via REST API call",
    "comments": "A request comment",
    "cost_estimated": 25.3,
    "date_required": "2025-10-16",
    "time_required": "18:56:01"
}

In the example above we have 2 required fields in order to create a new request:

wf_type identifies the workflow we want to create a new request for
user_name will be the requestor

Successful response

{
    "request": {
        "wf_requests.project_type": "N/A",
        "wf_requests.status1": "Not Reviewed",
        "wf_requests.status2": "Not Reviewed",
        "wf_requests.status3": "Not Reviewed",
        "wf_requests.comments": "A request comment",
        "wf_requests.time_requested": "11:58:31",
        "wf_requests.requestor": "AFMDEMO5",
        "wf_requests.priority": "Low",
        "wf_requests.request_id.key": 330,
        "wf_requests.status": "CREATED",
        "wf_requests.description": "Requested created via REST API call",
        "wf_requests.issue_type": "Bug",
        "wf_requests.contract_amount": 0.0,
        "wf_requests.date_required": "2025-10-16",
        "wf_requests.contract_type": "Lease",
        "wf_requests.time_required": "18:56:01",
        "wf_requests.wf_type": "TECH INCIDENT",
        "wf_requests.date_requested": "2025-10-03",
        "wf_requests.skill": "Developer",
        "wf_requests.request_id": 330,
        "wf_requests.cost_final": 0.0,
        "wf_requests.block_id": "2",
        "wf_requests.satisfaction_survey": 0,
        "wf_requests.cost_estimated": 25.3
    },
    "pkey_value": 330,
    "status": "success",
    "next_actions": {
        "AFMDEMO5": [
            "Submit",
            "Cancel"
        ]
    },
    "wf_type": "TECH INCIDENT"
}

The response contains the created request with all of its fields, the primary key value of the request set in pkey_value, the next actions available on the workflow and who can make those actions (usernames).

Error response

{
  "code": -1,
  "messageForDeveloper": "Required fields missing: [wf_type, user_name]",
  "messageForUser": "Required fields missing: [wf_type, user_name]"
}

{
  "code": 1,
  "messageForDeveloper": "Operation failed: Could not find user account information for user: [AFMX] - Please check the spelling of the user name.",
  "messageForUser": null
}

{
  "code": -1,
  "messageForDeveloper": "A value for one of the fields, [Requested By] is not correct.  The value must exist in the validating table, the [Employees] table\nUnable to execute statement: INSERT INTO wf_requests (cost_estimated, comments, description, time_required, block_id, requestor, status, date_required, wf_type) VALUES (25.3, 'A request comment', 'Requested created via REST API call', '1899-12-30 18:56:01', '1', 'AFM_USER', 'CREATED', '2025-10-16', 'TECH INCIDENT'), database=[data]",
  "messageForUser": null
}

2. Performing Actions

HTTP Method: PATCH

Headers:

{
    "Content-Type": "application/json",
    "Authorization": "Bearer [jwt]"
}

Body example:

{
    "wf_type": "TECH INCIDENT",
    "user_name": "AFMDEMO5",
    "pkey_value": 330,
    "actionName": "Submit",
    "fields": {
        "description": "Request updated via REST API call",
        "comments": "Anonther request comment",
        "cost_estimated": 42.0,
        "date_required": "2025-10-18",
        "time_required": "16:45:00"
    }
}

In the example above we have 4 required fields in order to perform a workflow action:

wf_type identifies the workflow we want to perform an action on
user_name is the user performing the action
pkey_value is the identifier for the request we are trying to update
actionName is the name of the action we want to perform

In the fields property you can update any request field’s value with a few exceptions.

🚫

Do not attempt to update the following fields’ values directly: request_id, status, block_id, wf_type.

Successful response

{
    "request": {
        "wf_requests.project_type": "N/A",
        "wf_requests.status1": "Not Reviewed",
        "wf_requests.status2": "Not Reviewed",
        "wf_requests.status3": "Not Reviewed",
        "wf_requests.comments": "Anonther request comment",
        "wf_requests.time_requested": "12:50:07",
        "wf_requests.requestor": "AFMDEMO5",
        "wf_requests.priority": "Low",
        "wf_requests.request_id.key": 330,
        "wf_requests.status": "REQUESTED",
        "wf_requests.description": "Request updated via REST API call",
        "wf_requests.issue_type": "Bug",
        "wf_requests.contract_amount": 0.0,
        "wf_requests.date_required": "2025-10-18",
        "wf_requests.contract_type": "Lease",
        "wf_requests.time_required": "16:45:00",
        "wf_requests.wf_type": "TECH INCIDENT",
        "wf_requests.date_requested": "2025-10-03",
        "wf_requests.skill": "Developer",
        "wf_requests.request_id": 330,
        "wf_requests.cost_final": 0.0,
        "wf_requests.block_id": "4",
        "wf_requests.satisfaction_survey": 0,
        "wf_requests.cost_estimated": 42.0
    },
    "next_actions": {
        "AFM_USER": [
            "Approve",
            "Maintenance Request",
            "Building Alarm",
            "Reject"
        ],
        "AFMDUP": [
            "Approve",
            "Maintenance Request",
            "Building Alarm",
            "Reject"
        ]
    }
}

Error response

{
  "code": -1,
  "messageForDeveloper": "Required fields missing: [user_name, pkey_value, wf_type, actionName]",
  "messageForUser": "Required fields missing: [user_name, pkey_value, wf_type, actionName]"
}

{
  "code": -1,
  "messageForDeveloper": "No action [Submit] found for status [].",
  "messageForUser": "No action [Submit] found for status []."
}

{
  "code": -1,
  "messageForDeveloper": "Action [Submit] is not external",
  "messageForUser": "Action [Submit] is not external"
}

⚠️

All workflow actions peformed via REST API must be marked as external actions.

e.g.

3. Getting Request Info

HTTP Method: GET

Headers:

{
    "Content-Type": "application/json",
    "Authorization": "Bearer [jwt]"
}

Body example:

{
    "wf_type": "TECH INCIDENT",
    "pkey_value": 330
}

In the example above we have 2 required fields in order to find information about a request:

wf_type identifies the workflow we want to find the request for
pkey_value is the identifier for the request we are trying to find

Successful response

{
    "request": {
        "wf_requests.project_type": "N/A",
        "wf_requests.status1": "Not Reviewed",
        "wf_requests.status2": "Not Reviewed",
        "wf_requests.status3": "Not Reviewed",
        "wf_requests.comments": "Anonther request comment",
        "wf_requests.time_requested": "12:50:07",
        "wf_requests.requestor": "AFMDEMO5",
        "wf_requests.priority": "Low",
        "wf_requests.request_id.key": 330,
        "wf_requests.status": "REQUESTED",
        "wf_requests.description": "Request updated via REST API call",
        "wf_requests.issue_type": "Bug",
        "wf_requests.contract_amount": 0.0,
        "wf_requests.date_required": "2025-10-18",
        "wf_requests.contract_type": "Lease",
        "wf_requests.time_required": "16:45:00",
        "wf_requests.wf_type": "TECH INCIDENT",
        "wf_requests.date_requested": "2025-10-03",
        "wf_requests.skill": "Developer",
        "wf_requests.request_id": 330,
        "wf_requests.cost_final": 0.0,
        "wf_requests.block_id": "4",
        "wf_requests.satisfaction_survey": 0,
        "wf_requests.cost_estimated": 42.0
    },
    "next_actions": {
        "AFM_USER": [
            "Approve",
            "Maintenance Request",
            "Building Alarm",
            "Reject"
        ],
        "AFMDUP": [
            "Approve",
            "Maintenance Request",
            "Building Alarm",
            "Reject"
        ]
    }
}

Error response

{
  "code": -1,
  "messageForDeveloper": "Required fields missing: [pkey_value, wf_type]",
  "messageForUser": "Required fields missing: [pkey_value, wf_type]"
}

{
  "code": -1,
  "messageForDeveloper": "Required request body is missing: public org.springframework.http.ResponseEntity<java.util.Map<java.lang.String, java.lang.Object>> com.archibus.gwe.rest.GWERestController.findRequest(java.util.Map<java.lang.String, java.lang.Object>)",
  "messageForUser": null
}

{
  "code": -1,
  "messageForDeveloper": "Request with id [3324532] not found for workflow type [TECH INCIDENT].",
  "messageForUser": "Request with id [3324532] not found for workflow type [TECH INCIDENT]."
}

Notes

Depending on the ARCHIBUS version, the messageForDeveloper field might be missing from the responses.
In newer version of ARCHIBUS, it was removed in favor of messageForUser.

Rule Chains Parameters