View source for FS 353019 GFG Gift Aid Capture and Interface

<div class="noprint">
{{#vardefine:Client|GFG}}
{{#vardefine:ClientName|Gone for Good Limited}}
{{#vardefine:System|''CALIDUS'' ePOD}}
{{#vardefine:Doc_Title|Gift Aid Capture and Interface}}
{{#vardefine:Version|1.0}}
{{#vardefine:Date|1st October 2018}}
{{#vardefine:Reference|353019}}
{{#vardefine:Year|2018}}
</div>
{{Doc_Title
|Client={{#var:ClientName}}
|System={{#var:System}}
|Title={{#var:Doc_Title}}
|Reference=FS {{#var:Reference}}
|Version={{#var:Version}}
|Date={{#var:Date}}
|Year={{#var:Year}}
}} 

<!-- TOC --> 
<div class="noprint">
= Functional Overview  =
== Client Requirement  ==
Requirement from Mike Rayner:

''CALIDUS'' ePOD to capture the Gift Aid declaration and to send the details back to UK Changes. 

This requires a Gift Aid form as UDF in ePOD with some field defaulted. 

The form data will be passed back to UK Changes.

An example Gift Aid form has been provided and is stored in the project folder and referenced below.


== Solution Overview  ==
''CALIDUS'' ePOD will capture information at the point of the customer signing for the collection, if configured to do so, through the UDF (user-Defined Forms) functionality.

In order to achieve this, C-TMS must be modified to pass through the full name of the Charity to C-ePOD when the jobs are created or modified, which C-ePOD will store on the job.

The configuration of a UDF form will now allow the creation of sub-forms.

This functionality will be modified (on device and when configuring) to allow buttons to be defined as part of the UDF, on the main UDF forms. The configuration of the buttons will allow selection of a UDF sub-form as pre-created above.

Furthermore, the definition of entry fields in UDF will be modified to default values into the Gift Aid form from the data of the collection job, without modifying that data. This will be through a new Default configuration item against each field.

The expected configuration of Terms and Conditions for Collections will be:
* Standard T&Cs
* Enter Gift Aid ID
* A button to '''Register for Gift Aid''' running the Gift Aid Registration sub-form.

The expected configuration of the Gift Aid Registration sub-form will be as required by Gone for Good Limited and is expected to contain:
* Several text labels describing the Gift Aid process:
* A checkbox to confirm Gift Aid, which must be checked.
* The charity name, defaulted from the job, required to be entered.
* Name, defaulted from the contact name on the job, required to be entered.
* 4 lines of address, defaulted from the job address, 1 line required to be entered.
* Post Code, defaulted from the job address, required to be entered, validated as a UK post code.
* Date, defaulted to the current date, required to be entered.
* A '''Confirm''' button to save the Gift Aid Registration details.
* A '''Cancel''' button to discard the Gift Aid Registration details.

{{Note}} It is expected that a single set of T&Cs for a single (collection) job group or for the site will be required. However, the application will allow for different T&Cs (and Gift Aid Registration forms) to be configured for each customer (Job Group in C-ePOD).


On signature of the collection job on the device, the terms and conditions will show:
* Any standard Terms and Conditions.
* A facility to enter an existing Gift Aid ID for the charity.
* A button to '''Register for Gift Aid'''.

Pressing the '''Register for Gift Aid''' button will open a form to enter the Gift Aid Registration details. 
Any fields with a default value will be shown with the value of the data from the job.

{{Note}} This form will not be required to be completed, and the provided '''Cancel''' button bay be used to .

Once complete and saved, the customer will sign for the collection.

The information on the device will be passed back to ''CALIDUS'' TMS. The signature and T&Cs (along with any completed Gift Aid declaration or existing Gift Aid ID) will be stored against additional order information when the collection has been confirmed as complete.

C-TMS will then forward the additional information along with the details of the completed collection to UK Changes through the standard Trip/Order XML export, which will be modified to cope with the larger data size required.


== Scope  ==
The exact format of the Gift Aid Registration form is to be confirmed, as well as the potential requirement for a different form for each customer.

Several changes to the requested Gift Aid Registration form have been made, to account for the expected use, after comparison with Charity Gift Aid Registration forms:
*	"my donation of £" to "the proceeds of my donation", as this is not a monetary gift.
*	"Title", "First/Initial" and "Surname" to "Name" (as this is how the data is stored on C-ePOD).
*	Minor formatting changes (bullets removed), required because of the capabilities of UDF on the device.

The ''CALIDUS'' ePOD application does not strongly validate addresses - the application accepts up to 5 lines of address that may be populated with any data. 


<!-- NEW PAGE --> 
= Set-up  =
== Pre-requisites  ==


== Menu Structure  ==


== Data  ==
=== C-TMS ===
The new System Parameter EPOD_OWNER_CONFIG will be set to "C" for this implementation's cost centre.

The new System Parameter EPOD_SIGNATURE_STORAGE will be set to "Y" for this implementation's cost centre

Import Decodes for name "XML_REFERENCE" will be added for the following:
* Source value "SIGNATURE", target value "Signature"
* Source value "TNCS", target value "Terms & Conditions"
Note also that source value "SIGNATORY" must be present.


=== C-ePOD ===
The EPOD Site for this implementation must have the following configured to work as expected:
* EPL_USE_OWNER_NAME will be set to "1" (Enabled/Ticked in the screen).


Table EPOD_LIST_ITEMS for the List ID of EPOD_LISTS ListName "ConfigTypeDDLData" will have the following item added.
* Description "Sub-Form" Value "SUBFORM" Default 0.


The following is the proposed Collection job Terms and Conditions:

<gallery widths=210px heights=300px perrow=3>
File:FS_353019_Admin_UDF_Config_5.png
</gallery><br />


The following is the proposed Gift Aid Registration form:

<gallery widths=210px heights=300px perrow=3>
File:FS_353019_PDA_Gift_Aid_1.png
File:FS_353019_PDA_Gift_Aid_2.png
File:FS_353019_PDA_Gift_Aid_3.png
</gallery><br />


<!-- NEW PAGE --> 
= Functional Description  =
== C-TMS ==
=== Sending Jobs to C-ePOD ===
A new System Parameter EPOD_OWNER_CONFIG will be created at Cost Centre level.

This will have description "C - Send Customer Name and ID or Lots Installed in Owner Name and ID. L or other value - Send Lots Installed in Owner Name only"

Database procedure DP_EPOD_WEBSERVICE.epod_out will be modified to check this parameter when in MODE2 (general EPOD mode) for the cost centre. 

If set to value "C", the process will add 2 XML nodes, with data set from ORG_CUSTOMER:
* EPL_OWNER_ID, set to value LOTS_INSTALLED if present or CUSTOMER_ID.
* EPL_OWNER_NAME, set to value CUSTOMER_NAME

If set to "L" or any other value, the process will add 1 XML node, with data set from ORG_CUSTOMER, as it does now:
* EPL_OWNER_NAME, set to value LOTS_INSTALLED

{{Note}} No branches of this package need to be modified.


=== Database Changes ===
The SCH_ORD_REFERENCE table will be modified with the following additional field:
* SUB_REF_VALUE2 - a CLOB (character large object)


=== Receiving Updates from C-ePOD ===
A new System Parameter EPOD_SIGNATURE_STORAGE will be created at Cost Centre level.

This will have description "Y - Store Signature, Signatory and T&Cs against the order when complete. N or other value - Do not store."


The Job Update message back from C-ePOD already includes the following:
* EPL_JOB_SIGNATURE - a base64-encoded image of the signature.
* EPL_JOB_SIGNATORY - the name of the customer signing for the goods.
* EPL_TNCS - The terms and Conditions, plus all other related information (in this case, the Gift Aid Registration form).

XML_REFERENCE import decodes will be added for the following:
* Source value "SIGNATURE", target value "Signature"
* Source value "TNCS", target value "Terms & Conditions"
Note also that source value "SIGNATORY" must be present.

Database procedure DP_EPOD_WEBSERVICE.epod_job_in will be modified to store values in these references on SCH_ORD_REFERENCE only if the new system parameter EPOD_SIGNATURE_STORAGE is set to "Y" and the mode is "MODE2".

In this case, the procedure will check the value is populated on the 3 fields below and store them if populated on SCH_ORD_REFERENCE:
* EPL_JOB_SIGNATURE - store in new field SUB_REF_VALUE2, for SUB_REF_NAME "SIGNATURE". SUB_REF_VALUE should be set to "Stored".
* EPL_JOB_SIGNATORY - store in new field SUB_REF_VALUE, for SUB_REF_NAME "SIGNATORY". SUB_REF_VALUE2 should be omitted.
* EPL_TNCS - store in new field SUB_REF_VALUE2, for SUB_REF_NAME "TNCS". SUB_REF_VALUE should be set to "Stored".


=== Exporting Trip/Order XML ===
The standard Trip/Order XML export will be modified to handle the large data being sent (potentially greater than 32Kb per line).
The process will create Insert files for each CLOB required, with placeholders in the master file. After creation of the master file, the process will merge the contents of each insert file with the master file.


The existing procedure GEN_ORDER_SUB will be amended to process the CLOB data differently when new field SUB_REF_VALUE2 has been populated.

A count will be initiated to record each time the new field is populated. Currently information is written to the outbound file using the put_line command.

To store the CLOB data, a new process will be called to create a new file, referencing the count. The PUT_RAW command will be used to write the CLOB data to the new file. 

 UTL_FILE.OPEN_FILE ({FILE}||COUNT);
 UTL_FILE.PUT_RAW (cp_file_handle2, sch_ord_referenves.sub_ref_value2);
 UTL_FILE.FFLUSH (cp_file_handle2);
 UTL_FILE.CLOSE_FILE (({FILE}||COUNT);


Within the GEN_ORDER_SUB process, the  <SUB_REFERENCE> tag will point to the new file {FILE}||COUNT.

Unix commands will replace the file reference with the contents of the relevant file when building the XML to send out.

Once the Unix process has completed and the files are merged, the Insert files (containing the CLOB data) will be removed from the file system.


== C-ePOD ==
=== Database/DAL ===
A new field will be added to EPOD_JOB:
* EPL_OWNER_ID, added as nvarchar(12)

This field will be added to all stored procedures in the database that require them.

This field is required on the device.

This field is required to be set on jobs imported through the standard XML import (flat file or webservice). The Import XSD will be modified to show these fields. This field is not required to be provided.

This field is required to be contained within the Export.

This field is not required to be used when filtering data for selection.

Standard XML Interface documentation will be modified as part of this change.


=== Server ===
The export to TTM from EPOD will be modified to use Owner ID before Owner Name.

Method EPOD_JOB.ToXElementTTM will be modified to achieve this.

Currently, the Owner Name is only used if configured to do so (with EPOD_SITE.EPL_USE_OWNER_NAME).

In this section, the value in EPL_OWNER_ID will be used if present and populated with a non-blank/null value, instead on EPL_OWNER_NAME.

If EPL_OWNER_ID is not present, the code will continue as it does now.


=== Admin ===
The existing UDF Configuration screen UDF_Config.aspx will be modified to:
* Allow creation of sub-forms
* Allow default values
* Allow Button-type fields to be defined.

[[File:FS_353019_Admin_UDF_Config_1.png|border|600px]]

The UDF type "SUBFORM" description "Sub-Form" will be added to the list items for:
* Finding created UDF.
* Creating a new UDF.
* Modifying an existing UDF.
This is populated on database table EPOD_LIST_ITEMS for the List ID of EPOD_LISTS ListName "ConfigTypeDDLData".

[[File:FS_353019_Admin_UDF_Config_4.png|border|600px]]

<gallery widths=210px heights=300px perrow=3>
File:FS_353019_Admin_UDF_Config_2.png|''New Button Type''
File:FS_353019_Admin_UDF_Config_3.png|''New Default parameter''
</gallery><br />


When creating or modifying UDF for types that are not "SUBFORM", a field type of "BT" (description "Button") may be selected.

When selecting Button types, the following parameters are valid - all others will be disabled:
* ID
* LABEL
* ACTION
* REQUIRED

Parameter "Action" values for Button types will be a drop-down list of Sub-Form UDFs in the system for that site (EPOD_UDF_CONFIG where EPL_KEY_VAL begins with the user's logged-in Site ID).

The drop-down list will show "None" as a default option. All other options will be populated with the following from EPOD_UDF_CONFIG:
* Value as EPL_CONFIG_ID.
* Descriptive text as EPL_DESCRIPTION

Button types will saved in the standard UDF Field XML notation, as per the following example:
        <FIELD ID="{UDF Field ID}">
            <TEXT>{UDF Text}</TEXT>
            <FORMAT>BT</FORMAT>
            <REQUIRED>{UDF Required}</REQUIRED>
            <ACTION>{UDF Form ID}</ACTION>
        </FIELD>
The curly brackets identify the fields from the configuration screen.


Parameter "Default" values will be set from a predefined list of values stored in EPOD_LIST_ITEMS, for a new List on EPOD_LISTS.
For this change, the following fields are required:
* Owner Name (value PDAJOB.EPL_OWNER_NAME)
* Customer Name (value PDAJOB.EPL_CUSTOMER_NAME)
* Address 1 (value PDAJOB.EPL_ADDRESS_1)
* Address 2 (value PDAJOB.EPL_ADDRESS_1)
* Address 3 (value PDAJOB.EPL_ADDRESS_1)
* Address 4 (value PDAJOB.EPL_ADDRESS_1)
* Post Code (value PDAJOB.EPL_POSTCODE)
* Current Date (value PDAJOB.EPL_END_ACTUAL_DATE)
{{Note}} This will be the same list as the list of Data-bound field values, developed recently. Any new values above should be added to this list.

Default parameters will saved in the standard UDF Field XML notation with a tag VALUE, as per the following example:
        <FIELD ID="">
            <TEXT></TEXT>
            <SUBTEXT></SUBTEXT>
            <GROUP></GROUP>
            <POST></POST>
            <FORMAT></FORMAT>
            <REQUIRED></REQUIRED>
            <VALUE></VALUE>
        </FIELD>

The UDF Preview panel of the Create/Edit pop-up will be modified to support the new Button types.
Button fields (as opposed to Buttons on the form) will be displayed on a new line like normal fields. The button text will be the value in the Label. The button will be formatted to the same look and feel as Form buttons.

As part of product changes to this screen, the following changes will also be made to this preview form at this time, to more closely match the layout on the actual device:
*	No colon after each label.
*	Text fields 50% width float right.
*	Text/Numeric fields on the same line as the label.
*	Form title in a header at the top of the form, formatted as 95% width, white text on blue background.
*	Check Boxes having ticks to the left.
*	Leaving space at the bottom of the screen window and showing the form buttons at all times (if present).
*	General font: smaller in the screen window.
*	Sub-label present, half-size, under the appropriate field, float left 70% width.
*	Post-text present, half-size, under the appropriate field, float right 30% width.

The user control UDFRender will be modified to achieve these preview changes

<gallery widths=210px heights=300px perrow=3>
File:FS_353019_Admin_UDF_Config_5.png|''New Preview style''
</gallery><br />


The Configurable POD/POC report (ConfigPOD.aspx) will be modified to ignore Button field types - they will not be part of the completion document produced, which includes the data entered on the sub-form


=== Device ===
The following field will be added to the Job table EPOD_JOB:
* EPL_OWNER_ID - nvarchar(12)

The Data Access Layer object PDA_JOB will be modified to receive this field in the import from the server when requesting loads or receiving an update response. If not present, this should be defaulted to blank.


The Signature screen (Signature.js) will be modified to set the End Date and Time (EPL_END_ACTUAL_DATE and Time of EPOD_JOB) to the current date and time at the point of entering the screen. This will not be saved at this time. The setting of the End Date and Time after confirmation of the signature should remain.


UDF objects will be modified to support the following:
* Data-bound Default Values in tag "VALUE".
* Button fields.
The UDF Object (in method createUDFields2 of styling.js) will be changed to support these requirements.

Currently, the UDF object supports putting in the value from already-entered UDF forms, but not from the format itself. This will be modified to add the value from the format XML, so support defaulting from within the UDF format design.
The VALUE tag within the completed or saved UDF form takes precedence over the value in the UDF format.

Additionally, the processing of this VALUE tag will support data-bound defaults.

The value of the VALUE tag will be checked to see if it exactly matches the following:
* Starts with "PDA"
* Then has any number of alphanumeric and underscore characters only
* Then has one "."
* Then has alphanumeric text and underscore characters only.

This will be checked with a regexp pattern as follows:
 (PDA[a-zA-Z0-9_]+\.)?[a-zA-Z0-9_]+
Should this wholly match with no other characters, then the field value is considered data-bound.

In this case, the process will get the value from the data field (the text after the ".") from the data object (the text before the "."). If the data object or data field does not exist, then this will be caught and the value will be set to "". 

{{Note}} This is very similar to the existing data-bound field functionality.


The UDF Object supports many field types. This will be extended to support the Button field types "BT".

For Button field types, the process will get the UDF configuration indicated by the value in the ACTION tag (through the instantiation of the object PDA_UDF_CONFIG). If this configuration is not found, then the button will not be added. If found, then the Button field will be added like other fields, in the next row, utilising the standard button styling on the device style.

The child tags of the FIELD tag will be stored as now in the fieldObj properties of the object created. The UDF Form format (PDA_UDF_CONFIG.EPL_UDF_FIELDS) will be stored in this object, under the ACTION property.

A button click event handler will be added to, on clicking the button, check the VALUE and ACTION property values of fieldObj. These will be passed to a new generic function to display a pop-up UDF entry form.

The new function will be similar to existing forms already in place in the product - this change will centralise this into a single function that can be used for those forms that require it (popup.js). The existing areas that can be copied are:
* Pre/Post Service UDF (in SM_Service.js)
* Pre-Job UDF (in PreJobUDF.js)
* Container and Product UDF (in ColDel.js)

The function should receive parameters of the data objects in use (in this case, PDALOAD and PDAJOB) as well as the UDF Format and the completed UDF Form (if already completed).

The function will create a new full-screen window for the form entry. 
{{Note}} It is important to ignore any button field specified in a sub-form - these can only be displayed in a main form.

This form must also include form buttons. It is expected in this form that the buttons will be:
* '''Cancel''' - Changes must be made to the Cancel button type to remove the returned UDF, in case the customer changes their mind after full or partial entry of the form. The popup window will then be closed.
* '''Confirm''' - this will validate the form as normal, checking that the required fields have been entered. If this fails, the form will highlight the information not entered and inform the customer. If this passes validation, the process will save the UDF and close the form, returning the entered UDF to the calling form.

When confirmed or cancelled, the form will return a status ("C" or "X", depending on whether the Confirm or Cancel button was clicked in the sub-form. The button object will store the returned XML in the VALUE fieldObj property, and extract the status into another property for checking at validation.

If the Button field has a REQUIRED tag set to "Y", then the status must not be "X". When validating the T&Cs form entry, this must be checked. 

{{Note}} This is generic coding - in this implementation, the '''Gift Aid Registration''' button will ''not'' be required.

When validating the T&Cs form and generating the UDF to return to the server (and on to C-TMS through the job update), the VALUE tag should be populated like any other field object i.e. from the value stored against the object.

For Button fields, the value will actually be resulting XML from the sub-form.

So, a form ("MYFORM") with a single normal TEXT field called "MYFIELD" that has "ABC123" entered into it would return the following XML:

    <FORM NAME="MYFORM">
        <FIELD ID="MYFIELD">
            <TEXT>My Field</TEXT>
            <SUBTEXT></SUBTEXT>
            <GROUP></GROUP>
            <POST></POST>
            <FORMAT>T</FORMAT>
            <REQUIRED>N</REQUIRED>
            <VALUE>ABC123</VALUE>
        </FIELD>
    </FORM>
    
A form ("MYFORM") with a single Button field "MYBUTTON" with a sub-form "MYSUBFORM", ID 321 (entering MYFIELD as above) that has been completed will return the following:

    <FORM NAME="MYFORM">
        <FIELD ID="MYBUTTON">
            <TEXT>My Button</TEXT>
            <SUBTEXT></SUBTEXT>
            <GROUP></GROUP>
            <POST></POST>
            <FORMAT>BT</FORMAT>
            <REQUIRED>N</REQUIRED>
            <ACTION>321</ACTION>
            <VALUE>
                <FORM NAME="MYSUBFORM" CONFIRM="C">
                    <FIELD ID="MYFIELD">
                        <TEXT>My Field</TEXT>
                        <SUBTEXT></SUBTEXT>
                        <GROUP></GROUP>
                        <POST></POST>
                        <FORMAT>T</FORMAT>
                        <REQUIRED>N</REQUIRED>
                        <VALUE>ABC123</VALUE>
                    </FIELD>
                </FORM>
            </VALUE>
        </FIELD>
    </FORM>

Although more complex in this implementation, this will be the basis of the configuration of the Collection T&Cs and of the Gift Aid Registration form. Sample configurations have been created and are present in the project folder.

This UDF will be returned in the EPL_TNCS field to C-TMS.


<!-- NEW PAGE --> 
{{Doc_Appendix
|Appendix=A
|Estimate=Y
|Glossary=EPOD
|Ref1=Charity Gift Aid Declaration.docx
|RefV1=&nbsp;
|RefDate1=11/09/2018
|Ref2=Complete TNC Example.xml
|RefV2=&nbsp;
|RefDate2=26/09/2018
|REQ=0
|EST=1
|FS=2.5
|TS=0
|DEV=18.25
|ST=2.5
|IMP=1
|PM=1.5
|Client={{#var:Client}}
|Year={{#var:Year}}
|FSEST=Y
|FOC=Y
|Rev1=Murray Middleton
|Rev1Title=OBS Logistics Project Manager
|Rev2=Mike Raynor
|Rev2Title=Gone for Good Limited Representative
}}</div> 
[[Category:{{#var:Client}} FS]]