JSON API Tool

Introduction

The JSON API Tool enables users to make JSON web service calls within a Joget DX process, allowing data retrieval and storage into Joget's form data or workflow variables. 

JSON Tool Properties

Configure JSON API

To configure JSON API, drag and drop the Tool element onto the canvas in Process Builder,  click on it, and select Mapping.

When adding JSON API in the field Tools, you will see the following fields available for configuration:

• JSON URL: Enter the URL for the JSON web service call.
• Call Type 

  Select the call type:

  • GET
  • POST

  GET requests include all required data in the URL. GET is less secure than POST because the data sent is part of the URL. It's saved in browser history, and the server logs it in plaintext.

  In contrast, HTTP POST requests supply additional data from the client (browser) to the server in the message body. POST is safer than GET because the parameters are not stored in browser history or web server logs. See Get vs. Post for more information.

• Body Type: Select the POST method:
  • Request Parameters
    

    Field	Description
    Name	Name (or Type) of the Request Header
    Value	Link or Value of the Request Header

  • Request Parameters as JSON Payload
    When POST Method is set to POST Parameters, these parameters will be sent as a UrlEncodedFormEntity.
    When the POST Method is set to POST Parameters as JSON Payload, these parameters will be sent as a StringEntity in the form of an escaped JSON string.

• • Custom JSON Payload
    Write your own JSON to be the payload. It will be sent as a StringEntity.
    This option is available only when Custom JSON Payload is selected.

• Request Headers: Add custom headers for the request.
• No Response Expected: Check if no response is expected, disabling data storage options (store to form, store to workflow variable).
• Debug Mode: Enable debug messages in the server log for troubleshooting.

Store to form

The Store to Form feature in the JSON API Tool allows you to save data retrieved from JSON web service calls directly into Joget forms. You can configure the target form, specify the base JSON object name for multi-row data, and map JSON properties to form fields. This capability enables seamless integration of external data into your Joget applications, enhancing data management and usability.

Fields to configure:

• Form: Select the target form to store retrieved data.
• Base JSON Object Name for Multirow Data: Define the base object name for multi-row data arrays.
• Field Mapping: Map JSON data properties to form fields.
  
  • Field Name: Form field ID.
  • JSON Object Name: JSON property name.

Store to workflow variable

The Store to Workflow Variable feature in the JSON API Tool enables you to map and store JSON data properties into workflow variables within Joget. This functionality is important for processes that depend on dynamic data from external sources. By mapping JSON properties to workflow variables, you ensure that the process logic can utilize this data effectively, facilitating better decision-making and automation.

Fields to configure:

• Workflow Variable Mapping: Map JSON data properties to workflow variables.
  
  • Workflow Variable: JSON Object Name.
  • JSON Object Name: JSON property name.

Notes on JSON returned data

The API Domain Whitelist setting in General Settings needs to be configured to allow JSON API requests. If a request is from a non-whitelisted domain, the response will be an HTTP 400 Bad Request. To enable API calls, enter an asterisk " * " into the API Domain Whitelist field in General Settings.

The returned data may be saved as form data or added to be saved into the process's workflow variable.

Sample JSON API POST Call: http://localhost:8080/jw/web/json/apps/published/userviews 

Sample JSON Returned Results:

{
    "apps": [
        {
            "name": "App Center",
            "userviews": [
                {
                    "name": "Joget DX",
                    "id": "v",
                    "version": 1,
                    "url": "/jw/web/userview/appcenter/v"
                },
                {
                    "name": "Joget DX Platform",
                    "id": "v2",
                    "version": 1,
                    "url": "/jw/web/userview/appcenter/v2"
                }
            ],
            "id": "appcenter",
            "version": 1
        },
        {
            "name": "Customer Relationship Management",
            "userviews": [
                {
                    "imageUrl": "/jw/web/app/crm/resources/crm_icon.png",
                    "name": "Customer Relationship Management",
                    "id": "crm_userview_sales",
                    "version": 1,
                    "url": "/jw/web/userview/crm/crm_userview_sales"
                }
            ],
            "id": "crm",
            "version": 1
        }
    ]
}

Troubleshoot

If you encounter an error like the one below, you can resolve the issue by Set Up SSL on Tomcat.

javax.net.ssl.SSLHandshakeException: PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target

The error above indicates that the Joget instance has no SSL cert installed or an invalid SSL cert (e.g., expired cert, improper SSL cert installation, etc.). Typically, public services will enforce mandatory HTTPS; this includes GitHub APIs.

The Joget server requires a valid SSL cert installed into the web app server's Java keystore.

Here are some general guides you can see:

• Set Up SSL on Tomcat
• SSL/TLS Configuration How-To
• How to Install an SSL/TLS Certificate In Tomcat

SSL setup steps may differ depending on several factors, such as your chosen SSL provider, the proxy server used, if any (e.g., Apache HTTPD), operating system, etc.

Related documentation

Additional resources provide information and guides to enhance your understanding and implementation. These resources cover JSON API examples, plugins from the Joget Marketplace, configuration guides based on returned JSON data structures, and sample integration scenarios. Utilizing these resources can significantly aid in troubleshooting, optimizing, and expanding the capabilities of your Joget applications.

• List of JSON API
• JSON Form Options Plugin From Joget Marketplace  
• Configure JSON Tool Based On Returned JSON Data Structure
• Sample JSON API Integration
• Single Sign On - SSO

Download sample app