How to change data or insert new data into a data source

If you have not read the discussion on Data Sets yet, please do so first, as it will help your understanding of this recipe greatly.

Suppose you have a data base (it might be a SQL Server® data base, or Microsoft® Access, or just a spreadsheet) which has customer names and addresses in it. And suppose this database is made available to various templates either by using ChooseFromDataSource, IncludeDataSourceData, LinkToDataSource or LinkToDataSourceOnEnter, or by the “Use For All Templates” feature.

Although a database like this is likely to be set up and maintained (i.e. backed up, etc.) by a database administrator, it will usually be the users who run the templates who will be aware of changes to customer data (i.e. changes to addresses and contact personnel). It would then make sense to allow those users to make the necessary changes in the database when they occur.

Changing Existing Data

By default, when data from a data source is used on a template, the user is allowed to change the data in the XpressDox interview, and those changed data appear on the merged document, but are also saved in the data set for that template. But, by default, XpressDox will not save the changed data in the underlying data source.

However, it may be that you, as template author, actually want the data as modified by the user to be saved back into the data source.

This  option is available via the refresh and save parameters which are passed to the data source commands.

• «IncludeDataSourceData(Contacts,RefreshSave)» will cause XpressDox to save any changes made to data from that data source.

The default refresh and save parameter is RefreshNoSave.

Why the Refresh concept?

When a user chooses “Use Other Data” in the interview, then they are given the chance to select the Data Set which was saved for a previous template, and this is then used as the Data Set for the current template. However, this Data Set may have been created and saved days or weeks (or longer) in the past, and the data may no longer be current. However, if some of the data elements come from a data source, that data source is likely to be more current than the saved Data Set from a previous template, and so the Refresh options cause XpressDox to refresh the data from the data source.

Refresh and Save are linked, because it would be counter-productive to allow users to save their changes into the data source, only to find that when they “Use Other Data” the changes are essentially lost. In other words, Save implies Refresh.

However, it might be that in some circumstances the data in the original Data Set should not be refreshed from the data source (this would be the case where the Data Source contains default values). In this case the NoRefresh option makes sense.

The processing of «IncludeFileData» and «ChooseFromFile» with regard to the Refresh and save options is almost the same as for the data source commands, but there is no Save concept when dealing with data from text files.

Inserting New Data

With Version 6 the option AllowInsert has been introduced.  This will enable XpressDox to create new data in the underlying data source, so that, for instance, an account can be opened in an accounting database under control of an XpressDox template. The Cookbook article Creating new Data in a Data Source explains this in more detail.

Restricting the Save Option

Also with Version 6,  the template author has the ability to allow the Save option conditional on the values of certain data elements in the data set. For example:

«ChooseFromDataSource(Accounts,Choose the Account,RefreshSave,,,(contains(UserPrivileges,'Save')))»

This will allow the “Save” option when the UserPrivileges data element contains the string ‘Save’.

This Save sub-option Condition is applicable to all the data source commands.