You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
This module contains an example Webform configuration demonstrating integration with the Liberty Create Low-code API.
1
+
This module contains an example Webform configuration demonstrating integration with a REST API created on the Netcall Liberty Create Low-code platform.
2
2
3
3
## Liberty Create API
4
-
When we think of APIs, we usually think of it to have a fixed data structure. The Liberty Create API, however, does not refer to one or more APIs with fixed data structures. Instead, API designers can create necessary APIs from a drag-and-drop UI. This means, there is no common API spec that we can target for Drupal Webform integration.
4
+
Liberty Create users can create custom APIs from a drag-and-drop UI. Due to the custom nature of these APIs, we cannot provide a single integration for Drupal Webforms. This means when faced with an integration task, Drupal site builders would have to study every such API method and come up with suitable Webform configurations.
5
5
6
-
In the rest of this README, we describe an **example** Liberty Create API for CRM case creation and then explain how API integration is achieved with Drupal Webform.
6
+
Caselink 360 is a CRM app created on the Liberty Create platform. It comes with a published API reference. This makes it possible for us to provide an example Webform integration with one of Caselink 360's REST API methods. This API method creates CRM case records.
7
+
8
+
The rest of this README explains the Webform configuration process with the hope that this explanation would be useful when integrating Drupal Webforms with other REST APIs built on the Liberty Create platform.
9
+
10
+
The example Webform provided in this module creates new CRM case records using the Caselink 360 app's `caselink_360_create_update_case` REST API method. First we take a look at a sample API request, then a sample API response, and finally explain the Webform configuration process.
7
11
8
12
## Example API request
9
-
Let's look at an example REST API request first:
13
+
Below we look at a REST API request to the `caselink_360_create_update_case` API method that creates a CRM case record:
14
+
10
15
```
11
16
POST https://example-build.oncreate.app/api/REST/case_to_crm/0.1 HTTP/1.1
What follows is an example response from the previous API call to create a CRM case.
58
+
What follows is an example response from the previous API call to create a CRM case record:
59
+
55
60
```
56
61
{
57
62
"payload":{
@@ -69,94 +74,101 @@ What follows is an example response from the previous API call to create a CRM c
69
74
"data":{
70
75
"source_system":"Some Text 1",
71
76
"source_ref":"Some Text 2",
72
-
"date_time_created":"1703505600",
73
-
"liberty_create_case_reference":"GE\/1"
77
+
"case_datetime_created":"1703505600",
78
+
"ch_case_ref":"GE\/1"
74
79
}
75
80
}
76
81
]
77
82
}
78
83
}
79
84
```
80
85
81
-
###Webform integration basics
82
-
So this is how we setup the integration:
83
-
- Under the "Settings > Emails/Handlers" tab of a Webform, add a "Remote post" Webform handler. This handler comes bundled with the Webform module.
84
-
- Under the "General" tab of the handler configuration dialog, expand the "Completed" fieldset.
85
-
- In the "Completed URL" field, enter the API endpoint URL. The example Webform config bundled with this module uses "https://example-build.oncreate.app/api/REST/case_to_crm/0.1" as this URL. Adjust it accordingly for your target endpoint.
86
-
- In the "Completed custom data" field, map API fields with suitable Webform tokens. Refer to the example config below to get a better idea. This bit is in YAML format:
86
+
## Webform integration basics
87
+
This is how we setup API integration for the `caselink_360_create_update_case` API method:
88
+
1. Under the "Settings > Emails/Handlers" tab of a Webform, add a "Remote post" Webform handler. This handler comes bundled with the Webform module. Note down the handler id which is usually autogenerated but can be edited manually if wished.
89
+
2. Under the "General" tab of the handler configuration dialog, expand the "Completed" fieldset.
90
+
3. In the "Completed URL" field, enter the API endpoint URL. The example Webform config bundled with this module uses "https://example-build.oncreate.app/api/REST/case_to_crm/0.1". Adjust it accordingly for your target endpoint.
91
+
4. In the "Completed custom data" field, map API fields with suitable Webform tokens. Refer to the example config below to get a better idea. This bit is in YAML format:
87
92
```
88
93
payload:
89
-
# client_unique_identifier is a required field.
94
+
# client_unique_identifier is a required field. Its value should vary between requests.
# For file fields, we use inline YAML syntax to avoid indentation issues. This is because "file_details_for_liberty_create_api", our custom file token, gets replaced with several *other* tokens before the token value insertion starts.
# For file fields, we use inline YAML syntax to avoid indentation issues. This is because file_details_for_liberty_create_api, our custom file token, gets replaced with several *other* tokens before the token value insertion round starts.
This assumes that the [token_environment Drupal module](https://www.drupal.org/project/token_environment) is enabled and the following environment variables are present with their corresponding values:
140
-
- DRUPAL_LIBERTY_CREATE_API_AUTH_KEY
141
-
- DRUPAL_LIBERTY_CREATE_API_USERNAME
142
-
- DRUPAL_LIBERTY_CREATE_API_USER_KEY
146
+
This assumes that the [token_environment Drupal module](https://www.drupal.org/project/token_environment) is enabled and the DRUPAL_LIBERTY_CREATE_API_AUTH_KEY environment variable is present with its corresponding value.
147
+
148
+
Note that the token_environment module must be explicitly told that the DRUPAL_LIBERTY_CREATE_API_AUTH_KEY environment variable should be made available as a Drupal token. This is configured from "/admin/config/system/token-environment".
149
+
150
+
10. The [webform_queued_post_handler Drupal module](https://packagist.org/packages/cyberwoven/webform_queued_post_handler) provides an alternative to the "Remote post" handler. This handler is called "Async remote post" and uses Drupal's queue to manage API requests which is more reliable. Items in Drupal's queue are usually processed during cron runs. If you decide to use this handler instead, you may also find the [queue_ui](https://www.drupal.org/project/queue_ui) contrib module useful.
151
+
152
+
### Note
153
+
If you install this module, almost all the above steps would be taken care of you except:
154
+
- You would have to provide the right API endpoint URL referred to in step 3 above.
155
+
- Make the API token value available as the DRUPAL_LIBERTY_CREATE_API_AUTH_KEY environment variable as mentioned in step 9.
143
156
144
-
Note that the token_environment module must be explicitly told that the above environment variables should be made available as Drupal tokens. This is configured from "/admin/config/system/token-environment".
145
-
- The [webform_queued_post_handler Drupal module](https://packagist.org/packages/cyberwoven/webform_queued_post_handler) provides an alternate to the "Remote post" handler. This handler is called "Async remote post" and uses Drupal's queue to manage API requests. Items in Drupal's queue are usually processed during cron runs. If you decide to use this handler instead, you may also find the [queue_ui](https://www.drupal.org/project/queue_ui) contrib module useful.
157
+
It is unlikely you would want to use the Caselink 360 integration Webform as is. Treat it more as an example to build up on rather than an end product.
146
158
147
159
## Inspecting API responses
148
160
To inspect API responses, add the following "Value" type Webform elements to your Webform:
149
-
- "crm_response" whose value should be `[webform:handler:async_remote_post:completed:payload:result]; [webform:handler:async_remote_post:completed:payload:error_code]; [webform:handler:async_remote_post:completed:payload:error_desc]`.
150
-
- "crm_result" whose value should be `[webform:handler:async_remote_post:completed:payload:data:0:result]; [webform:handler:async_remote_post:completed:payload:data:0:error_code]; [webform:handler:async_remote_post:completed:payload:data:0:error_desc]`
151
-
- "crm_case_ref" whose value should be `[webform:handler:async_remote_post:completed:payload:data:0:data:0:liberty_create_case_reference]`.
161
+
- "crm_response" whose value should be `[webform:handler:remote_post:completed:payload:result]; [webform:handler:remote_post:completed:payload:error_code]; [webform:handler:remote_post:completed:payload:error_desc]`.
162
+
- "crm_result" whose value should be `[webform:handler:remote_post:completed:payload:data:0:result]; [webform:handler:remote_post:completed:payload:data:0:error_code]; [webform:handler:remote_post:completed:payload:data:0:error_desc]`
163
+
- "crm_case_ref" whose value should be `[webform:handler:remote_post:completed:payload:data:0:data:0:ch_case_ref]`.
152
164
153
165
This will ensure that API responses are stored alongside Webform submission values. This makes it easier to inspect these from the "Results" tab of Webforms.
154
166
155
-
As you can see, the three above field values are using multiple tokens and these tokens are referring to "async_remote_post" which is the handler id. Everything after ":completed:" in the token mirrors the API response. Change all these if necessary.
167
+
As you can see, the three above field values are using multiple tokens and these tokens are referring to `remote_post` which is a handler id. This can vary dependencing on what handler id is in use. Everything after ":completed:" in the token mirrors the API response. Change all these if necessary.
156
168
157
169
## Summary
158
-
- Liberty Create APIs will vary from organisation to organisation. There is no one-size fits all solution. You can study the example Webform config provided with this module to get an idea about the integration process.
159
-
- Use the "Remote post" or "Async remote post" Webform handler to make HTTP POST requests to any Liberty Create REST API endpoint URLs.
170
+
- Liberty Create APIs will vary from organisation to organisation. There is no one-size fits all solution. You can study the example Webform config provided with this module to get an idea about the integration process. This example creates CRM case records in the Caselink 360 Liberty Create app.
171
+
- Use the "Remote post" or "Async remote post" Webform handler to make HTTP POST requests to any Liberty Create REST API endpoint URL.
160
172
- Use the "Completed custom data" settings of the above handlers to map Webform fields to REST API fields.
161
173
- Use the "Custom options" settings of the handlers to provide API authentication details.
162
174
- Use the crm_response, crm_result, and crm_case_ref *Value* type Webform fields to capture API responses.
Copy file name to clipboardExpand all lines: modules/localgov_forms_example_liberty_create_integration/config/optional/webform.webform.caselink_api_integration_example.yml
+18-14Lines changed: 18 additions & 14 deletions
Original file line number
Diff line number
Diff line change
@@ -4,12 +4,12 @@ dependencies: { }
4
4
weight: 0
5
5
open: null
6
6
close: null
7
-
uid: 3
7
+
uid: 1
8
8
template: false
9
9
archive: false
10
-
id: liberty_create_api_example
11
-
title: 'Liberty Create API integration example'
12
-
description: ''
10
+
id: caselink_api_integration_example
11
+
title: 'Liberty Create Caselink 360 API integration example'
12
+
description: '<p>Example Webform that passes form submission date to the Liberty Create "Caselink 360 - create / update case" API method.</p>'
0 commit comments