# Saving XML output

Sometimes, you will want to save an XML file output from an eform that you're working on. You might use this to import into another application or to populate a data warehouse to power your own analytics etc.&#x20;

There are two parts to saving an XML to disk.&#x20;

1\) you first need to have mapped the format of the XML file that is to be output using the 'Mapping Designer' function

2\) you need to tell the form what to do with the file by adding an 'Action'

This article has been written to tell you how to do this. &#x20;

### **Before you start**

In order to do this, you need to ensure that the Data Mapping function (shown below) is enabled. If you can't see this it is not enabled and you should raise a ticket through the help desk to get it enabled.

{% embed url="https://help.ieg4.com" %}

![Where to access the ability to set the format of your XML](https://2446085776-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0Xv5e5CMqZNlA8r5Exkm%2Fuploads%2Fn6pvUYZJP1FX3dS5Bu5h%2FScreenshot%202021-12-09%20at%2018.34.28.png?alt=media\&token=940b9277-b6e8-4258-9b27-a605ae3876a3)

### **Mapping the XML file format**

The first thing you need to do if you want your form to output an XML file, is tell it the format of the file. To do this you need to click on the 'Data Mapping' link as shown in the screenshot above.&#x20;

When you do, you will see this:

![Where any data mappings will be shown. ](https://2446085776-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0Xv5e5CMqZNlA8r5Exkm%2Fuploads%2FrRqLGPWF9BAConkMsxsB%2FScreenshot%202021-12-09%20at%2018.35.29.png?alt=media\&token=97a381a8-d209-4ab9-b1e8-7b15576dc61a)

Here you need to click on 'Create'. The following is an example XML mapping template:

![An XML template - this can be whatever structure desired](https://2446085776-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0Xv5e5CMqZNlA8r5Exkm%2Fuploads%2FZG9P2KWA9dgLhO73HWNY%2FScreenshot%202021-12-09%20at%2018.36.47.png?alt=media\&token=d7fb77e6-2ea8-4c7f-9b9d-f6f916c29415)

You can see the XML file contains FirstName, Surname, MobileNo, Email, ServiceRequestType, HighPriority, Details as pieces of data.&#x20;

Notice that you basically need to add an empty tag for anything that should be mapped from data the customer will provide in the form. Where the value is always the same for the form i.e. the Service Request Type the actual value is populated. This is simply to illustrate you might need to pass a value to the back office which the customer may not know but that the back office needs.

Last, you can see the name of the mapping is 'GraffitiFile'. This is important later when you're creating the action to save it somewhere.



### Linking the form data to your XML format

&#x20;

Once the XML mapping template is added, open design mode in eDesigner for your form. Select Mapping Designer:

\
Then click on the name of the file template. The reason this screen appears is that it is technically possible to have multiple mapping files output:

![Accessing the Mapping Designer in the form](https://2446085776-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0Xv5e5CMqZNlA8r5Exkm%2Fuploads%2FzT6IvRn2PccP9ssDNUwU%2Fimage.png?alt=media\&token=1fe7c930-b837-4f13-8882-448e7decb034)

Then click on the name of the file template. The reason this screen appears is that it is technically possible to have multiple mapping files output:

![The list of any mapping templates available to the form](https://2446085776-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0Xv5e5CMqZNlA8r5Exkm%2Fuploads%2F0Vh4ECjjovvuimIKQ1Km%2Fimage.png?alt=media\&token=bc13ce95-1330-4f3f-af57-dfc826ca0a1a)

You'll then be presented with a UI with three columns.

* The first column contains any pages in your form.
* The second column is populated when you click on a page as it is the ID for each of the questions that are present on the page you selected
* The third column is the XML template converted into a bulleted list to remove the technical look of XML&#x20;

The task you now have is to click on each question you want in your XML and then click on the relevant XML element you want to map it to. When you do this you'll see a button that says 'Add Mapping':

![Mapping form content to the XML template](https://2446085776-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0Xv5e5CMqZNlA8r5Exkm%2Fuploads%2Fsb64YZI2QyOKlDTLvjXF%2Fimage.png?alt=media\&token=09181913-4e95-4a3c-b659-70192ec9d421)

_**Because the question IDs are what are shown in here, it is a good idea to ensure the ids are obvious as to which question they relate to.**_

Once you've mapped content to all it will look like this:

![Mapped XML content](https://2446085776-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0Xv5e5CMqZNlA8r5Exkm%2Fuploads%2Fsqc2EKvrfVqd11gpaVEz%2Fimage.png?alt=media\&token=306145c6-8f64-4fa8-baf1-c8d6f9bf3adc)

{% hint style="info" %}
&#x20;ServiceRequestType doesn't need a mapping as it is a fixed value and it's useful to know that anything that is fixed should be set in the mapping template.&#x20;
{% endhint %}

Now you've done this, when a form is submitted, an XML file will also get created.&#x20;

### Masking XML requirements&#x20;

Sometimes an XML file needs the answer the customer provides to be converted into something the back office understands. For example if the customer was being asked whether they thought some graffiti was offensive they might be given a Yes/No option. But the back office expects the value for priority to be a 1 or a 2. Where 1 means high priority and 2 means not.

To cater for this, the 'value' that your enter in the 'Value' field when creating your list is what will be passed in the XML. I.e. if they selected yes with the list set up as below, the XML would be populated with 1:

![The values from drop downs will go into the XML not the labels (i.e. the Options)](https://2446085776-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0Xv5e5CMqZNlA8r5Exkm%2Fuploads%2FXGXGZdW8As2GvXCaTeMP%2Fimage.png?alt=media\&token=f4622986-8ed0-40b9-bac5-499463cd9d2d)

### Viewing the XML

When you have completed your mapping above, you can check the file is being created as expected by going into the [**Forms Portal**](../../shared-features/forms-portal) and clicking on the Documents tab as shown below:

![Accessing the XML file](https://2446085776-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0Xv5e5CMqZNlA8r5Exkm%2Fuploads%2FeHMGke3MgyWqJFYyFS6b%2Fimage.png?alt=media\&token=2e2a2780-c31a-400c-9b16-505dc19eeb21)

The XML file is created as we mapped before. One can see the details the customer entered are mapped and that a) the Service Request Type is populated and b) the High Priority value is 1 not Yes:

```
<Issue>
<FirstName>John</FirstName>
<Surname>Mc</Surname>
<MobileNo>07713491749</MobileNo>
<Email>john.mcmahon@ieg4.com</Email>
<ServiceRequestType>GRAFFITI</ServiceRequestType>
<HighPriority>1</HighPriority>
<Details>It's really bad. It's just outside the window of 10 Downing Street.</Details>
</Issue>
```



### **Adding an action**

Now you're happy you've got the XML how you like it, you can now set up an action to:

* Save it to a file location
* Send it to an API&#x20;

To add an action you need to click on the 'Actions' link found here in Form Details:

![Where to add actions that will be fired when the form is submitted](https://2446085776-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0Xv5e5CMqZNlA8r5Exkm%2Fuploads%2FEwiFblbRANgK0JK1JQAe%2Fimage.png?alt=media\&token=4ff1c25c-08f4-4c31-8f97-5d64d92f8a84)

_**Note - because an action can be different from one environment to another, you need to do this for EACH environment.**_&#x20;

You will then need to click on the 'Advanced Create' button. This will then present you with the actions available on your own environment.&#x20;

For simplicity we've limited the list to the four most commonly used:

![Adding an action](https://2446085776-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0Xv5e5CMqZNlA8r5Exkm%2Fuploads%2FMNq9ScBv5kBrxLRSYlE6%2FScreenshot%202021-12-09%20at%2018.47.31.png?alt=media\&token=d4ad2cc0-6c12-4914-8ab4-198cf4f6a1b8)

\*If this option is not available please log a ticket through help.ieg4.com and they can enable this. When this is selected you then simply need to complete all of the different settings, which are documented below.&#x20;

&#x20;

#### Saving it to a file location

In order to save an XML file to a file location, you need to select the action called SaveDataDocument from the list. This then has the following options, which should be populated in line with the table below:

| **Name**                                                  | SaveDataDocument                                                                                                                        |
| --------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| **Description**                                           | Any name you like                                                                                                                       |
| **Location Switch XPath**                                 | N/A                                                                                                                                     |
| **XPath Location**                                        | N/A                                                                                                                                     |
| **Back Office Reference Fallback**                        | N/A                                                                                                                                     |
| **Filename XPath**                                        | N/A                                                                                                                                     |
| **Name XPath Fallback**                                   | N/A                                                                                                                                     |
| **Location XPath Fallback**                               | N/A                                                                                                                                     |
| **Prefix Reference**                                      | N/A                                                                                                                                     |
| **Modular Filenames**                                     | N/A                                                                                                                                     |
| **Static Reference**                                      | N/A                                                                                                                                     |
| **Folder\***                                              | The server location you want to save the XML files to                                                                                   |
| **Limit Back Office Ref to successful search responses**  | N/A                                                                                                                                     |
| **Document Type**                                         | The name of your XML data mapping file that you mapped the XML for. I.e. GraffitiFile is the name of the one we created in the example. |
| **Back Office Proxy**                                     | true   (note this must be lower case)                                                                                                   |
| **Back Office Proxy Namespace \*\***                      | Please contact IEG4 support for these details.                                                                                          |
| **Back Office Proxy Issuer Name \*\***                    | Please contact IEG4 support for these details.                                                                                          |
| **Back Office Proxy Issuer Secret \*\***                  | Please contact IEG4 support for these details.                                                                                          |

&#x20;

\* The location you want it to be saved to will be in the standard format for server locations. To find out what you need to enter here speak to your council's ICT team/service desk who can set up a suitable location (E.g. //internalservername/digital/IEG4xmloutput/counciltax/ if it related to Council Tax. Clearly you can a different folder for every XML output/form)

\*\* To find the settings in your eGovHub, other forms which also have these proxy settings include eChanges (Benefits CiC) and eClaim (Benefits New Claim). Alternatively you can log a support call and the support team will provide the settings or update them as required.&#x20;

{% hint style="warning" %}
Your ICT will need to ensure the proxy has permission to write to the folder which the action to save files directs them to&#x20;
{% endhint %}

The Settings that are mentioned above are found here:

![Back Office Proxy Settings](https://2446085776-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0Xv5e5CMqZNlA8r5Exkm%2Fuploads%2FUqVgikdoxWAYXeo2Fghn%2Fimage.png?alt=media\&token=9b9bc3df-18d7-4ba5-8920-eb453e6c00a5)



### Viewing the outcome of the action

If you have done this correctly, you can view the action within the Form's Portal. This time click on the Integration tab. &#x20;

![Successful Save of the XML](https://2446085776-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0Xv5e5CMqZNlA8r5Exkm%2Fuploads%2FwNlgH9viTwkJzwIRXswv%2Fimage.png?alt=media\&token=2b38ffba-4d43-4f77-8611-e5e08f110843)
