How to Set Up JSON API Integration Using Joget

This guide focuses on Joget calling external APIs, while separating that flow from APIs exposed for external systems to call. That direction determines which Joget integration approach you should configure first.

What Does Joget API Integration Actually Include?

Joget API integration covers two directions: outbound calls from Joget to external services and inbound calls from external systems into Joget. Joget’s JSON API Tool handles outbound web service calls and can store returned data in forms or workflow variables. API Builder serves the inbound side by creating custom JSON APIs for Joget applications.

Outbound API Calls From Joget

Outbound integration starts when a Joget form submission or workflow triggers a request to an external system. That system could be a CRM, ERP, SaaS application, internal service, or custom backend.

Joget sends the request, receives the JSON response, and can use the returned data to populate records or influence later workflow steps.

APIs Exposed Through Joget

Inbound integration works in the opposite direction. External applications call APIs exposed through Joget, with API Builder providing a low-code way to create custom JSON endpoints based on OpenAPI specifications.

In Relinns’ DX9 implementations, APIs can be exposed around project requirements rather than a fixed API surface. That does not mean every HTTP method is available through every Joget integration component.

Once the integration direction is clear, the next decision is which Joget mechanism should handle it.

Which Joget API Integration Method Should You Use?

Choose the Joget integration method based on the API direction and the amount of control the project needs. Standard tooling covers common outbound requests and response mapping. Enhanced tools or custom development make more sense when the API requires custom request behavior, response transformation, specialized authentication, or recovery logic.

JSON API Tool

The JSON API Tool fits straightforward outbound integrations triggered from forms or workflows. Use it when Joget needs to send a standard request, construct a payload, and map the returned JSON into form fields or workflow variables.

Enhanced JSON API

Enhanced JSON API suits integrations that need more control over requests and responses. It supports cases where developers need extra configuration or response processing beyond standard field mapping.

We have successfully tested the Enhanced JSON API in its Joget DX9 implementations.

API Connector Builder

API Connector Builder works well when a project connects to a larger set of structured external endpoints. Developers can define reusable API integrations instead of configuring each request independently.

We have also tested API Connector Builder successfully with DX9.

API Builder

API Builder handles the inbound direction. Use it when external systems need to call APIs exposed through Joget rather than when Joget needs to call an external service.

Custom Plugins and BeanShell

Custom development becomes useful when standard configuration cannot meet the API contract. Typical reasons include custom HTTP behavior, complex transformations, or project-specific workflow logic.

Relinns' standard setup does not include PATCH by default. The team has implemented PATCH through custom development where project requirements called for it.

Choosing the right tool becomes much easier once the API contract and required Joget data are defined.

What Do You Need Before Setting Up a Joget API Integration?

Prepare the API contract before configuring Joget. You need the endpoint, HTTP method, authentication rules, headers, request structure, sample responses, and the Joget fields or workflow variables involved. A validated API request gives you a clean baseline, so failures inside Joget are easier to isolate from problems with the external service.

Before configuration, collect:

• API endpoint and required HTTP method
• Authentication method and required headers
• Request payload schema
• Query and path parameters
• A successful response example
• Expected error responses
• Joget fields or workflow variables sending data
• Joget fields or variables receiving the response
• Timeout and retry expectations
• Required plugin and Joget version

Test the request through Postman or cURL before recreating it in Joget. Use the same endpoint, credentials, headers, parameters, and payload you plan to configure.

Also keep inbound access controls separate from outbound setup. API Domain and IP whitelisting should be considered when external clients need access to Joget APIs, rather than treated as a universal prerequisite for every third-party API call.

With the API contract confirmed, you can configure the Joget request without having to guess at each field.

How Do You Set Up a JSON API Integration in Joget?

Set up an outbound Joget API integration by placing the API call at the right form or workflow event, then configure the endpoint, request method, payload, headers, runtime values, and response mapping. Joget’s JSON API Tool can call a JSON web service and store returned data in form records or workflow variables.

Choose Where the API Call Runs

Joget’s JSON Tool can run as a Process Tool or through Post Form Submission Processing. Both approaches connect business actions inside Joget with an external API.

The choice depends on the workflow.

Does the workflow need the API response before proceeding? If later process logic depends on the returned value, place the call where that response remains part of the workflow. Post-submission processing fits cases where the call belongs to actions triggered after form submission.

Configure the Endpoint and Request Method

Enter the full API endpoint and include any required path or query parameters.

Dynamic values can come from Joget Hash Variables. Joget supports form and process values through its Hash Variable mechanism, which lets the request use data available at runtime.

Check the required HTTP method against the selected integration component before configuration. The bundled DX8 JSON API Tool documentation lists GET and POST, whereas other Joget API components and enhanced tools support different methods.

Relinns does not use PATCH as a default capability in its standard setup. The team has built custom PATCH support where a project required it.

Build the JSON Request

Joget provides several ways to construct the request body for POST calls:

• Request Parameters
• POST Parameters as JSON Payload
• Custom JSON Payload

The official JSON API Tool documentation sends request parameters as URL-encoded data, whereas the JSON payload options send the body as a string. Custom JSON Payload gives you control over the JSON structure.

A payload can include Joget runtime values:

{
"customerId": "#form.customer.customerId#",
"status": "#variable.status#"
}

Joget resolves the Hash Variables when the request runs, provided those values exist in the current form or process context.

Add Headers and Authentication

Match the headers to the external API contract. A JSON API request may require:

Content-Type: application/json
Accept: application/json
Authorization: Bearer <token>

The JSON API Tool provides request-header configuration alongside its URL and body settings.

Some APIs use an API key header or Basic Authentication instead. OAuth-based integrations may require a token before the main API request. Keep the implementation tied to the authentication flow defined by the external API rather than adding auth fields the endpoint does not expect.

Map the Response Into Joget

Joget can save returned JSON data into form fields or workflow variables. The mapping connects a JSON property name with its Joget destination.

For example, an API might return:

{
"customerId": "12345",
"status": "approved"
}

The corresponding mapping could be:

Check the raw response before creating the mapping. Property names and casing need to match the returned structure.

Run the First End-to-End Test

Start with input that already produces a valid response outside Joget. Then verify the full flow:

Joget also provides Debug Mode for the JSON API Tool, which writes request and response details to the server log for troubleshooting.

Basic mappings cover many integrations, but credential handling and complex JSON structures need a more deliberate approach.

How Should You Handle Credentials and Complex JSON Responses?

Keep API credentials outside repeated request logic, and choose the response-handling method based on the JSON structure. Relinns stores credentials through Joget App Variables or server-level environment variables, depending on the project. Straightforward JSON can use Joget’s native field mapping, while complex transformations may require enhanced processing or custom code.

Store Credentials Outside Request Logic

Avoid placing API keys or tokens directly inside BeanShell scripts, payloads, or multiple tool configurations. That makes credential changes harder to manage and increases the chance of exposing sensitive values during maintenance.

Relinns typically stores credentials in:

• Joget App Variables for application-level configuration
• Server-level environment variables when credentials need tighter separation from the application

App Variables provide a practical configuration layer within Joget, but they should not be treated as a replacement for a dedicated enterprise secrets management system.

Handle Arrays With Multirow Mapping

Joget can map array-based responses into multiple form records using the Base JSON Object Name for Multirow Data setting. The base object tells Joget which array in the response it should process. (Joget JSON API Tool documentation)

For example:

{
"orders": [
{
"id": "101",
"status": "shipped"
},
{
"id": "102",
"status": "processing"
}
]
}

Setting the base object to orders lets Joget process each order as part of the multirow mapping.

Use the Right Level of Response Processing

The response structure should determine the implementation approach:

• Native mapping: flat objects and supported array structures
• Enhanced processing: filtering, restructuring, or calculated values
• BeanShell or custom plugin: project-specific transformations or processing logic

Joget’s Enhanced JSON Tool also supports response formatting through BeanShell before storing the processed data. (Enhanced JSON Tool documentation)

Complex JSON does not automatically require custom code. Start with native mapping, then move to enhanced or custom processing only when the response structure demands it.

Even a correctly mapped response still needs a clear diagnostic process when the API call fails.

How Do You Test and Troubleshoot a Joget API Integration?

Troubleshoot a Joget API integration one layer at a time. Start by confirming the external API in Postman or cURL, then inspect the request, authentication, HTTP response, returned JSON, mapping, and workflow execution. Joget’s JSON API Tool includes Debug Mode, which writes diagnostic entries to the server log.

Check Request and Endpoint Failures

Compare the Joget request with the working API request. Check:

• Endpoint URL and resource path
• HTTP method
• Query and path parameters
• JSON syntax
• Required headers

A 404 response points first to the endpoint or requested resource, so verify the URL before changing Joget mappings.

Check Authentication Failures

A 403 response can indicate an access or permission problem. Compare the Joget request with the request that works in Postman.

Inspect the API key, bearer token, token expiry, granted scope, and authentication format. Also confirm that Joget sends credentials in the request header or in the request location required by the external API.

Check Successful Requests With Missing Data

An HTTP 200 response confirms the API accepted the request, but Joget can still fail to store the expected values.

Inspect the raw JSON response and check:

• JSON property names and casing
• Form field mappings
• Workflow variable names
• Base JSON Object Name for multirow data

Joget uses the Base JSON Object Name to identify an array for multirow form mapping.

Check SSL and Connectivity Problems

For SSLHandshakeException or certificate errors, inspect the remote certificate chain and the Java keystore used by the Joget server. Joget requires the server to trust the SSL certificate used by the target endpoint.

Proxy rules, firewalls, and network restrictions also deserve inspection when the endpoint works outside the Joget server environment.

Monitor the Transaction

Relinns uses API logs to inspect transactions and the Audit Trail plugin to review form changes through snapshots and recorded inputs. Projects that need deeper visibility can add custom monitoring components.

Use this diagnostic order:

Once individual failures are traceable, production design needs to decide how Joget should handle repeated failures and retries.

Conclusion

A strong Joget API integration starts with the right integration direction, Joget component, request structure, authentication method, and response mapping. Production use also needs transaction visibility, retry logic, and a clear escalation path when external services fail.

Standard Joget tooling covers many API workflows. Custom development makes sense when projects need unsupported HTTP behavior, specialized recovery logic, or processing that standard configuration cannot handle.

If your integration needs that level of control, explore Relinns’ Joget development services for implementation and custom plugin support.