Introduction
The Enhanced JSON API plugin includes bundles built from the default JSON API, with added features such as support for system proxy settings, API tokens, customizable socket timeout retries, response formatting, additional PUT and PATCH request call. The default JSON API consists of:
Plugin Info
Plugins Available in the Bundle:
- Enhanced JSON API Form Load Binder
- Enhanced JSON API Form Options Binder
- Enhanced JSON API Form Store Binder
- Enhanced JSON API List Binder
- Enhanced JSON Tool
This plugin bundle is compatible with Joget DX 8 and onwards.
Expected Outcome
To be able to work with JSON API calls through form binder, form options binder, list binder and process tool.
Get Started
Steps
Where to get the plugin
Refer to Source Code and Plugin Download.
How to install and use the plugin
This plugin is identical to the default bundled JSON API. For more information on each of the existing features, you can refer to each of the KB below:
You can upload the demo app to explore each of the tool. The new features will be explained below.
Proxy Settings and API token with cache feature
If you do not have a proxy server, you can try mitmproxy - an interactive HTTPS proxy to test out the features.
After installing mitmproxy, run this command at terminal:
Start proxy server
mitmweb--listen-port 9090
A website will open, showing all the request flows that the proxy server will be capturing.
Figure 1: mitmproxy is running
Now we want to pass all Joget traffic to the proxy server, we can modify Joget's tomcat.sh file.
Insert the following code into the "export JAVA_OPTS" line:
-Dhttp.proxyHost=127.0.0.1 -Dhttp.proxyPort=9090 -Dhttps.proxyHost=127.0.0.1 -Dhttps.proxyPort=9090
By using the code above, we are configuring Joget to route network requests through local host proxy server with port 9090.
Run Joget with the newest tomcat.sh file. Navigate to the Process Builder of the demo app. We will be using a simple public ip address API (https://api.ipify.org/?format=json) to act as the access token request. Then we will take the access token value and in the request header of the next request. The URL only acts as an example, you can use any URL based on your own preference.
Figure 2: Enhanced JSON Tool in Process Builder
Click on Run Process. After the process has run successfully, check on mitmproxy to see the requests. The configured response value of the access token request has been successfully sent in the next request as "accessToken" request header.
Figure 3: First access token request
Figure 4: Second request with access token header
The access token cache expiry time has been set to 1 minute. If you immediately make another request, the access token will be retrieved from cache instead of making another call. After the cache expires, the access token request will be made again to retrieve a new value.
Figure 5: Access token in cache
Enhanced JSON API Properties
Enhanced JSON API
Authentication
Figure 6: Enhanced JSON API (Authentication)
| Name | Description |
|---|---|
| Retrieve and Use Access Token | If checked, access token will be included in the request headers. Use "{accessToken}" to access the value in the request headers. |
| Token URL | URL to retrieve the token from. |
| Request Type | Select the call type:
|
| Access Token JSON Field Name | The field name of the request call to retrieve access token from. |
| Store Access Token in Cache | If checked, access token will be stored in cache. If token is not expired, it will retrieve from cache instead of performing another request call. |
| Access Token Cache Expiry Time (minutes) | The duration set for the cache to expire before making another request becomes necessary. |
Request
Figure 7: Enhanced JSON API (Request)
| Name | Description |
|---|---|
| JSON URL | URL to be called. |
| Call Type | Select the call type:
|
| Request Headers | Add name(s) and value(s) to the request header. |
Response
Figure 8: Enhanced JSON API (Response)
| Name | Description | ||||||
|---|---|---|---|---|---|---|---|
| Connection Timeout (seconds) | Specifies the maximum time (in seconds) that the client will wait to establish a connection with the server. If the connection cannot be established within this time, an error will be thrown and logged. | ||||||
| Socket Timeout (seconds) | Specifies the maximum time (in seconds) that the client will wait for a server response after the connection is established. If no response is received within this time, an error will be thrown and logged. | ||||||
| Debug Mode | Show relevant debug entries in the server log for debugging purposes. | ||||||
| Response Type | Types of response format
| ||||||
| Format Response | Header. If Response Type is JSON, this section will be visible. | ||||||
| Enable Response Formatting | When checked, you can start writing a BeanShell script to format/post-process the JSON response. | ||||||
| Script | The "Enable Response Formatting" property must be enabled in order to write the BeanShell script here. Injected Variables:
Expected Return Object: It is expected to return a Map object that would later on be processed as configured to store to form and/or workflow variables. Example: Return the response only for the first item in a JSON array with the object name "apps". return data.get("apps")[0];
| ||||||
| Store to Form | Header. If Response Type is JSON, this section will be visible. | ||||||
| Form | Select the target form to store data. | ||||||
| Base JSON Object Name for Multirow Data | Name of the object that contains an array to be based on. | ||||||
| Field Mapping | Mapping with JSON data with Form fields.
| ||||||
| Store to Workflow Variable | Header. If Response Type is JSON, this section will be visible. | ||||||
| Workflow Variable Mapping |
| ||||||
| Store Attachment | Header. If Response Type is File, this section will be visible. | ||||||
| Form | Recommended to use a child form with foreign key to main record as in a single JSON call, data may be returned successfully but fails in parsing to JSON format. | ||||||
| File Upload Field | Fill in to use as foreign key to main record. Leave it blank to save form record ID into column "ID". When it is blank and there are multiple logs, logs will be overwritten and only the last entry will be visible. | ||||||
| Store Response Status | Header. | ||||||
| Workflow Variable to Store Response Status | Workflow variable name to store response status value. | ||||||
| Form | Recommended to use a child form with foreign key to main record as in a single JSON call, data may be returned successfully but fails in parsing to JSON format. | ||||||
| Field Mapping |
|
Source Code and Plugin Download
- You can find the latest release at https://github.com/jogetoss/enhanced-json-api/releases.
- Upload the plugin to your Joget by navigating to Settings > Manage Plugins > Upload Plugin as admin.
