1 Purpose and use
2 Objects and ObjectCollections
3 Schema
4 Summary
5 DataProviders
- 5.1 Attributes
- 5.2 Contents
- 5.3 List of DataProviders
- 5.4 Example DataProvider
6 Extensive example
- 6.1 XML configuration
- 6.2 Screenshots
  - 6.2.1 Manually created Objects
  - 6.2.2 Objects searched for via data interface

The data interface can be used via the https://primesoft-group.atlassian.net/wiki/spaces/PDT/pages/57081857 function.

This function is not available in "classic" templates.

As an alternative for "classic" templates, contact data can be accessed via the https://primesoft-group.atlassian.net/wiki/spaces/PDTEN/pages/61409741. For more information about the different template versions, go here.

Purpose and use

Via the data interface, data of different types can be loaded from different data sources as well as entered manually. Via a Schema the data types can be described and provided as Object or ObjectCollection for the document generation.

Objects and ObjectCollections

An Object describes an object that is defined by a Schema. In addition to the Schema, the object has an Id and a (translatable) Label. An example for an object is e.g., the recipient of a letter - on the document exactly one recipient is named and this can be described by such an object.

An ObjectCollection on the other hand is a list of objects. The list of objects is also defined by a Schema and contains an Id and a (translatable) Label. An example of such a list of objects would be invoice items from a CRM. On one invoice, with one recipient, several invoice items appear. The ObjectCollection allows to store several objects of the same type.

NOTE
If you want to allow one recipient in a template, use Objects. If you want to allow multiple recipients (e.g. in a protocol), use an ObjectCollection.

Structure

<FormsConfiguration xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <Elements>
    <Object Id="emplData" Label="Employee ddresses">
      [...]
    </Object>
    <ObjectCollection Id="CustData" Label="Customer addresses">
      [...]
    </ObjectCollection>
  </Elements>
</FormsConfiguration>

Schema

The Schema defines the structure of the data type. This schema can contain different elements that can collect or display information. The same types are supported as in the https://primesoft-group.atlassian.net/wiki/spaces/PDTEN/pages/61408842 function (Text, Date, YesNo, Choice), with the exception that grouping is not supported.

Structure

<FormsConfiguration xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <Elements>
    <ObjectCollection Id="CustData" Label="Customer addresses">
      <!-- Defines the ObjectCollection's elements to use in JavaScript -->
      <Schema>
        <Text Id="CompanyName" Label="Company name"  />
        <Text Id="Street" Label="Street" />
        <Text Id="PostalCode" Label="Zip" />
        <Text Id="City" Label="City" />
        <Text Id="Country" Label="Country" />
      </Schema>
    </ObjectCollection>
  </Elements>
</FormsConfiguration>

Summary

Basically, all Text and Choice schema elements for the display of an Object/ObjectCollection are used comma-separated in the search result list or in the selection list.
However, if you want to display only certain fields in the list view, you can configure the displayed fields via Summary:

<FormsConfiguration xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <Elements>
    <ObjectCollection Id="CustData" Label="Customer addresses">
      <!-- Defines what schema fields are shown in the result list -->
      <Summary>
        <Text Id="CompanyName" />
        <Text Id="City" />
      </Summary>
    </ObjectCollection>
  </Elements>
</FormsConfiguration>

The Field must refer to a field of the Schema via the Id.

DataProviders

To load data from other sources, DataProviders can be defined. For each Object or ObjectCollection one or more DataProvider can be defined.

Each DataProvider has the following configuration options:

DisplayName: Serves as name for the DataProvider.

SearchParameters: A search mask must be configured for the appropriate DataProvider. As syntax the same elements are used as in the Forms function (Text, Date, YesNo, Choice).

Mapping: To map the received data to the Schema , the Mapping syntax is used.
Each DataProvider can offer further, specific, configuration options.

Attributes

Attribute name	Description

Attribute name

Description

DisplayName

translate-DisplayName

Predefined display name or dynamic display name from the global translations. Note: Only one of the attributes may be set.

translate-DisplayName can be used from version 4.0.30114.0 onwards.

Element name	Description
`SearchParameters`	A search mask must be configured for the corresponding DataProvider. The same elements as in the https://primesoft-group.atlassian.net/wiki/spaces/PDTEN/pages/61408842 function (`Text`, `Date`, `YesNo`, `Choice`) are used as syntax.
`Mapping`	The https://primesoft-group.atlassian.net/wiki/spaces/PDTEN/pages/61410858-syntax is used to map the received data to the `schema`.
`…`	Each DataProvider might offer additional, specific configuration options.

List of DataProviders

The following DataProviders are available:

Name	Description	Link

Name	Description	Link
`CsvDataProvider`	Access to .csv files	https://primesoft-group.atlassian.net/wiki/spaces/PDTEN/pages/71532573
`ExcelDataProvider`	Access to Excel files	https://primesoft-group.atlassian.net/wiki/spaces/PDTEN/pages/71532589
`ExistingListDataProvider`	Access to local Excel files, which the user can select himself.	https://primesoft-group.atlassian.net/wiki/spaces/PDTEN/pages/936738851
`HttpDataProvider`	Access to HTTP/HTTPs APIs (REST/Web APIs)	https://primesoft-group.atlassian.net/wiki/spaces/PDTEN/pages/71532605
`SqlDataProvider`	Access to SQL databases	https://primesoft-group.atlassian.net/wiki/spaces/PDTEN/pages/74973185
`ProviderPipeline`	With this special DataProvider, data can be automatically reloaded after the search. You can define separate DataProviders for `Searching` and `Loading`.	https://primesoft-group.atlassian.net/wiki/spaces/PDTEN/pages/941031426

Example DataProvider

In the following example a CsvDataProvider is configured globally:

<FormsGlobalDataProviders>
  <GlobalSchemaAndSummary Key="Recipients.Objects.DefaultSchema" />
  <CsvDataProvider DisplayName="Kundenadressen">
    <Options>
      <FilePath>C:\home\site\wwwroot\addressdata.csv</FilePath>
      <HasHeaders>true</HasHeaders>
      <Delimiter>,</Delimiter>
    </Options>
    <SearchParameters>
      <Text Id="Firma" Label="Company name" />
      <Text Id="Ort" Label="City" />
    </SearchParameters>
    <Mapping>
      <Map Source="Firma" Target="CompanyName" />
      <Map Source="Strasse" Target="Street" />
      <Map Source="PLZ" Target="PostalCode" />
      <Map Source="Ort" Target="City" />
      <Map Source="Land" Target="Country" />
    </Mapping>
  </CsvDataProvider>
</FormsGlobalDataProviders>

Extensive example

In the following more extensive example an ObjectCollection with two data interfaces, a https://primesoft-group.atlassian.net/wiki/spaces/PDTEN/pages/71532573 as well as a https://primesoft-group.atlassian.net/wiki/spaces/PDTEN/pages/71532605, is configured for selecting the recipient in a letter template.

XML configuration

<FormsConfiguration>
  <Elements>
    <ObjectCollection Id="RecipientAddressData" Label="Recipient addresses">
    
      <!-- Defines the ObjectCollection's elements to use in JavaScript -->
      <Schema>
        <Text Id="CompanyName"  Label="Company name" />
        <Text Id="Street"       Label="Street" />
        <Text Id="PostalCode"   Label="Zip" />
        <Text Id="City"         Label="City" />
        <Text Id="Country"      Label="Country" />
      </Schema>
      <!-- Defines what fields are shown in the result list -->
      <Summary>
        <Field Id="CompanyName" />
        <Field Id="City" />
      </Summary>
      
      <!-- Defines the DataProviders -->
      <DataProviders>
        <!-- Address data from a csv file-->
        <CsvDataProvider DisplayName="Customer addresses">
          <Options>
            <FilePath>\\fileshare\addressdata.csv</FilePath>
            <HasHeaders>true</HasHeaders>
            <Delimiter>,</Delimiter>
          </Options>
          <SearchParameters>
            <Text Id="CompanyName" Label="Company name" />
            <Text Id="City" Label="City" />
          </SearchParameters>
          <Mapping>
            <Map Source="Company"    Target="CompanyName" />
            <Map Source="Street"     Target="Street" />
            <Map Source="PostalCode" Target="PostalCode" />
            <Map Source="City"       Target="City" />
            <Map Source="Country"    Target="Country" />
          </Mapping>
        </CsvDataProvider>
        <!-- TelSearch address provider -->
        <HttpDataProvider DisplayName="TelSearch">
          <SearchParameters>
            <Text Id="What" Label="Suchbegriff" />
          </SearchParameters>
          <Configuration>
            <Step>
              <Request Method="Get">
                <Url><![CDATA[https://tel.search.ch/api/?was={What}&key=[...]&maxnum=100]]></Url>
              </Request>
              <Response>
                <Data XPath="*[local-name()='feed']/*[local-name()='entry']">
                  <Mapping>
                    <Map Source="*[local-name()='name']" Target="CompanyName" />
                    <Map Target="Street">
                      <Map.SourceExpression><![CDATA[
                            function main()
                            {
                              const street = source("*[local-name()='street']");
                              const streetno = source("*[local-name()='streetno']");
                              return street + " " + streetno; 
                            }
                          ]]></Map.SourceExpression>
                    </Map>
                    <Map Source="*[local-name()='zip']" Target="PostalCode" />
                    <Map Source="*[local-name()='city']" Target="City" />
                    <Map SourceValue="CH" Target="Country" />
                  </Mapping>
                </Data>
              </Response>
            </Step>
          </Configuration>
        </HttpDataProvider>
      </DataProviders>
    </ObjectCollection>
    <!-- More letter related elements... -->
  </Elements>
</FormsConfiguration>

Screenshots

Manually created Objects

1) List view: without created Objects

3) List view with created Objects

The fields defined in Summary are displayed in the list view.

2) Create Objects manually

The data defined in Schema is entered in this dialog.

Objects searched for via data interface

1) List view: without created Objects

4) List view with created Objects

The fields defined in Summary are displayed in the list view.

Added entries

2) Search for Objects in DataProvider

Search entries

3) Add results from DataProvider