Feature: Liberty Create Caselink 360 REST API integration example

composer.json

@@ -12,5 +12,8 @@
   },
   "require-dev": {
     "geocoder-php/nominatim-provider": "^5.2"
+  },
+  "suggest": {
+    "drupal/token_environment": "^1.1.0"
   }
 }

modules/localgov_forms_example_liberty_create_integration/README.md

@@ -1,38 +1,42 @@
-This module contains an example Webform configuration demonstrating integration with the Liberty Create Low-code API.
+This module contains an example Webform configuration demonstrating integration with a REST API created on the Netcall Liberty Create Low-code platform.
 
 ## Liberty Create API
-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.
+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.
 
-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.
+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.
+
+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.
+
+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.
 
 ## Example API request
-Let's look at an example REST API request first:
+Below we look at a REST API request to the `caselink_360_create_update_case` API method that creates a CRM case record:
+
 ```
 POST https://example-build.oncreate.app/api/REST/case_to_crm/0.1 HTTP/1.1
 API-Authentication: [Token hidden]
-API-Username: [Your username]
-API-User-Token: [Token hidden]
 Content-Type: application/json
 
 {
     "payload":{
         "client_unique_identifier":"63105fe17248615689a02568ca95ff91",
-        "function":"case_to_crm_create_update_case",
+        "function":"caselink_360_create_update_case",
         "data":[
             {
                 "source_system":"Some Text 1",
                 "source_ref":"Some Text 2",
-                "date_time_created":"25/12/2023 12:00",
+                "nature_of_enquiry":"Some Text 5",
+                "case_datetime_created":"25/12/2023 12:00",
                 "resident_uprn":75,
                 "case_uprn":75,
-                "first_name":"Some Text 3",
-                "last_name":"Some Text 4",
-                "telephone_number_for_texts":"07700900000",
-                "email_address":"[email protected]",
                 "case_url":"http://www.example.com",
-                "nature_of_enquiry":"Some Text 5",
                 "disposal_date":"25/12/2023",
                 "details":"Some Long Text 1",
+                "first_name":"Some Text 3",
+                "last_name":"Some Text 4",
+                "date_of_birth":"25/12/2003",
+                "email_address":"[email protected]",
+                "phone_number":"07700900000",
                 "documents":[
                     {
                         "file":{
@@ -51,7 +55,8 @@ Content-Type: application/json
 ```
 
 ## Example API response
-What follows is an example response from the previous API call to create a CRM case.
+What follows is an example response from the previous API call to create a CRM case record:
+
 ```
 {
     "payload":{
@@ -69,94 +74,101 @@ What follows is an example response from the previous API call to create a CRM c
                 "data":{
                     "source_system":"Some Text 1",
                     "source_ref":"Some Text 2",
-                    "date_time_created":"1703505600",
-                    "liberty_create_case_reference":"GE\/1"
+                    "case_datetime_created":"1703505600",
+                    "ch_case_ref":"GE\/1"
                 }
             }
         ]
     }
 }
 ```
 
-### Webform integration basics
-So this is how we setup the integration:
-- Under the "Settings > Emails/Handlers" tab of a Webform, add a "Remote post" Webform handler.  This handler comes bundled with the Webform module.
-- Under the "General" tab of the handler configuration dialog, expand the "Completed" fieldset.
-- 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.
-- 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:
+## Webform integration basics
+This is how we setup API integration for the `caselink_360_create_update_case` API method:
+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.
+2. Under the "General" tab of the handler configuration dialog, expand the "Completed" fieldset.
+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.
+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:
   ```
   payload:
-      # client_unique_identifier is a required field.
+      # client_unique_identifier is a required field.  Its value should vary between requests.
       client_unique_identifier: "[webform:id]/[webform_submission:sid]"
       # "function" is also a required field.
-      function: case_to_crm_create_update_case
+      function: caselink_360_create_update_case
       # So is "data".
       data:
         -
           # source_system is a required field.
           source_system: "Drupal Webforms" 
           # source_ref is a required field.
           source_ref: "[webform:id]/[webform_submission:sid]"
+          # nature_of_enquiry is a required field.
+          nature_of_enquiry: "[webform:title]"
           # Everything else below is optional.
-          date_time_created: "[webform_submission:completed:custom:d/m/Y H:i]"
+          case_datetime_created: "[webform_submission:completed:custom:d/m/Y H:i]"
           resident_uprn: "[webform_submission:values:residential_address:uprn]"
           case_uprn: "[webform_submission:values:case_address:uprn]"
           first_name: "[webform_submission:values:name:first]"
           last_name: "[webform_submission:values:name:last]"
-          telephone_number_for_texts: "[webform_submission:values:phone]"
-          email_address:  "[webform_submission:values:email]"
+          phone_number: "[webform_submission:values:phone]"
+          email_address: "[webform_submission:values:email]"
+          date_of_birth: "[webform_submission:values:date_of_birth:d/m/Y]"
           case_url:  "[webform_submission:token-view-url]"
-          nature_of_enquiry: "[webform:title]"
           disposal_date: "[webform_submission:purge_date:custom:d/m/Y:clear]"
-          # 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.
-          documents: ["[webform_submission:values:files:file_details_for_liberty_create_api]", "[webform_submission:values:more_files:file_details_for_liberty_create_api]"]
           #
           # Any other Webform submission token should be placed within the "details" field below.
           details: |-
             Case address: "[webform_submission:values:case_address:clear]"
             Residential address: "[webform_submission:values:residential_address:clear]"
             Details: "[webform_submission:values:details_of_enquiry:clear]"
+          # 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.
+          documents: ["[webform_submission:values:files:file_details_for_liberty_create_api]", "[webform_submission:values:more_files:file_details_for_liberty_create_api]"]
   ```
+
   This assumes our Webform carries at least the following fields:
   - name
+  - date_of_birth
   - email
   - phone
   - residential_address
   - case_address
   - files
   - more_files
-- Uncheck everything under the "Submission data" fieldset.
-- Switch to the "Advanced" tab of the "Remote post" handler.
-- Under "Additional settings", select "POST" from the "Method" dropdown.
-- Select "JSON" from the "Post type" dropdown.
-- Try the following snippet for "Custom options":
+5. Uncheck everything under the "Submission data" fieldset.
+6. Switch to the "Advanced" tab of the "Remote post" handler.
+7. Under "Additional settings", select "POST" from the "Method" dropdown.
+8. Select "JSON" from the "Post type" dropdown.
+9. Insert the following snippet in "Custom options":
   ```
   headers:
     API-Authentication: "[env:DRUPAL_LIBERTY_CREATE_API_AUTH_KEY]"
-    API-Username: "[env:DRUPAL_LIBERTY_CREATE_API_USERNAME]"
-    API-User-Token: "[env:DRUPAL_LIBERTY_CREATE_API_USER_KEY]"
   ```
-  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:
-  - DRUPAL_LIBERTY_CREATE_API_AUTH_KEY
-  - DRUPAL_LIBERTY_CREATE_API_USERNAME
-  - DRUPAL_LIBERTY_CREATE_API_USER_KEY
+  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.
+
+  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".
+
+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.
+
+### Note
+If you install this module, almost all the above steps would be taken care of you except:
+- You would have to provide the right API endpoint URL referred to in step 3 above.
+- Make the API token value available as the DRUPAL_LIBERTY_CREATE_API_AUTH_KEY environment variable as mentioned in step 9.
 
-  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".
-- 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.
+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.
 
 ## Inspecting API responses
 To inspect API responses, add the following "Value" type Webform elements to your Webform:
-- "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]`.
-- "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]`
-- "crm_case_ref" whose value should be `[webform:handler:async_remote_post:completed:payload:data:0:data:0:liberty_create_case_reference]`.
+- "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]`.
+- "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]`
+- "crm_case_ref" whose value should be `[webform:handler:remote_post:completed:payload:data:0:data:0:ch_case_ref]`.
 
 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.
 
-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.
+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.
 
 ## Summary
-- 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.
-- Use the "Remote post" or "Async remote post" Webform handler to make HTTP POST requests to any Liberty Create REST API endpoint URLs.
+- 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.
+- Use the "Remote post" or "Async remote post" Webform handler to make HTTP POST requests to any Liberty Create REST API endpoint URL.
 - Use the "Completed custom data" settings of the above handlers to map Webform fields to REST API fields.
 - Use the "Custom options" settings of the handlers to provide API authentication details.
 - Use the crm_response, crm_result, and crm_case_ref *Value* type Webform fields to capture API responses.

modules/localgov_forms_example_liberty_create_integration/config/optional/webform.webform.liberty_create_api_example.yml → modules/localgov_forms_example_liberty_create_integration/config/optional/webform.webform.caselink_api_integration_example.yml

@@ -4,12 +4,12 @@ dependencies: {  }
 weight: 0
 open: null
 close: null
-uid: 3
+uid: 1
 template: false
 archive: false
-id: liberty_create_api_example
-title: 'Liberty Create API integration example'
-description: ''
+id: caselink_api_integration_example
+title: 'Liberty Create Caselink 360 API integration example'
+description: '<p>Example Webform that passes form submission date to the Liberty Create "Caselink 360 - create / update case" API method.</p>'
 categories:
   - Example
 elements: |-
@@ -24,6 +24,9 @@ elements: |-
     '#last__required': true
     '#suffix__access': false
     '#degree__access': false
+  date_of_birth:
+    '#type': date
+    '#title': 'Date of birth'
   email:
     '#type': webform_email_confirm
     '#title': Email
@@ -73,7 +76,7 @@ elements: |-
   case_ref:
     '#type': value
     '#title': 'CRM case reference'
-    '#value': '[webform:handler:remote_post:completed:payload:data:0:data:0:liberty_create_case_reference]'
+    '#value': '[webform:handler:remote_post:completed:payload:data:0:data:0:ch_case_ref]'
   files:
     '#type': managed_file
     '#title': Files
@@ -271,7 +274,7 @@ handlers:
     id: remote_post
     handler_id: remote_post
     label: 'Remote post'
-    notes: 'Saves everything in a Queue.  HTTP POST requests are later made by a queue worker.'
+    notes: 'Makes HTTP POST requests to the given API endpoint.'
     status: true
     conditions: {  }
     weight: 0
@@ -299,32 +302,32 @@ handlers:
         sticky: sticky
         notes: notes
         name: name
+        date_of_birth: date_of_birth
         email: email
         phone: phone
         details_of_enquiry: details_of_enquiry
-        residential_address: residential_address
         case_address: case_address
+        residential_address: residential_address
         api_response: api_response
         api_result: api_result
         case_ref: case_ref
         files: files
         more_files: more_files
+        date_of_birth_2: date_of_birth_2
       custom_data: ''
       custom_options: |-
         headers:
           API-Authentication: "[env:DRUPAL_LIBERTY_CREATE_API_AUTH_KEY]"
-          API-Username: "[env:DRUPAL_LIBERTY_CREATE_API_USERNAME]"
-          API-User-Token: "[env:DRUPAL_LIBERTY_CREATE_API_USER_KEY]"
       file_data: true
       cast: false
       debug: true
-      completed_url: 'https://example-build.oncreate.app/api/REST/case_to_crm/0.1'
+      completed_url: 'https://example-build.oncreate.app/api/REST/caselink360/1.0'
       completed_custom_data: |-
         payload:
           # client_unique_identifier is a required field.
           client_unique_identifier: "[webform:id]/[webform_submission:sid]"
           # "function" is also a required field.
-          function: case_to_crm_create_update_case
+          function: caselink_360_create_update_case
           # So is "data".
           data:
             -
@@ -333,13 +336,14 @@ handlers:
               # source_ref is a required field.
               source_ref: "[webform:id]/[webform_submission:sid]"
               # Everything else below is optional.
-              date_time_created: "[webform_submission:completed:custom:d/m/Y H:i]"
+              case_datetime_created: "[webform_submission:completed:custom:d/m/Y H:i]"
               resident_uprn: "[webform_submission:values:residential_address:uprn]"
               case_uprn: "[webform_submission:values:case_address:uprn]"
               first_name: "[webform_submission:values:name:first]"
               last_name: "[webform_submission:values:name:last]"
-              telephone_number_for_texts: "[webform_submission:values:phone]"
-              email_address:  "[webform_submission:values:email]"
+              phone_number: "[webform_submission:values:phone]"
+              email_address: "[webform_submission:values:email]"
+              date_of_birth: "[webform_submission:values:date_of_birth:d/m/Y]"
               case_url:  "[webform_submission:token-view-url]"
               nature_of_enquiry: "[webform:title]"
               disposal_date: "[webform_submission:purge_date:custom:d/m/Y:clear]"