FormSolutions Schnittstelle

Die Firma Form-Solutions bietet einen Formularserver an, in dem elektronisch ausfüllbare PDF-Formulare hinterlegt sind. Neben vielen vordefinierten Formularen können auch eigene Dokumente in dem System abgelegt werden.
Die FormSolutions-Schnittstelle ermöglicht den Redakteuren einen Link auf eines dieser Formulare zu erstellen. Zu diesem Zweck wird das gewünschte Dokument zunächst über eine Recherche-Maske ermittelt. Anschließend können verschiedene Konfigurationen vorgenommen oder angepasst werden. Außerdem kann angegeben werden, ob und wie die Daten übermittelt werden sollen. Schließlich wird die von der Schnittstelle erzeugte Url zu dem Dokument in dem entsprechenden Artikel des IES gespeichert.

Voraussetzungen

Um die Form-Solutions-Schnittstelle einrichten zu können müssen folgende Voraussetzungen gegeben sein:

• Der IES muss Zugang zum Internet haben, um den Formsolutions-Server erreichen zu können.
• Die Redakteure, die die Formulare Verknüpfen sollen, müssen Zugang zum Internet haben, um den Formsolutions-Server erreichen zu können.
• Der Kunde muss eine Form-Solutions Lizenz besitzen, um den den Form-Solutions-Server ansprechen zu können
• Mit der Lizenz wird dem Kunden ein CMS-Key für die Form-Solutions-Schnittstelle mitgeteilt, der vom IES verwendet werdet wird. Der Key sollte keine Sonderzeichen enthalten!
• Zusätzlich ist ein Default-Nutzer-Nummer erforderlich, dessen ID dem Kunden von Form-Solutions mitgeteilt wird. Sie muss das Format 00000000-0001-0001 haben.

Neu Implementation (ab Infosite5 5.11.1, Infosite6 6.1.1 und CityGov 3.7.1) )

Funktionsweise

Mit Hilfe des spt:formsolutions-Tag wird ein Dialog geöffnet, der zur Suche eines Formulars in das FormSolutions-System führt. Nach der Auswahl eines Formulars kann dieses für die Nutzung konfiguriert werden. Mit dem Abschluss der Konfiguration (Neue Formulareinstellungen speichern) wird der Dialog geschlossen und die generierte Url wird an das Redaktionssystem übergeben. Bei einer späteren Nachbearbeitung wird direkt die Konfiguration für diese Formular-Url angezeigt.

Installation: a) Strukturen per XIP einspielen

• Das XIP-Paket formsolution.xip kann beim Support angefragt werden. Anschließend kann es über die Konsole oder über die XIP-Oberfläche >>CMS-HOST<</ies/xip/ eingespielt werden. Beim Einspielen des XIP werden lediglich im Reiter 'Import Regeln' alle Werter mit Ausnahme von 'Elemente werden bei neuen Parents nicht verschoben' ausgewählt.

Installation: b) Strukturen manuell erstellen

• Es muss ein TemplatePool 'Form-Solutions' mit dem Anchor 'ies.tplp.formsolutions' existieren, der unterhalb des Pools 'IES' hinterlegt ist. Der Pool muss mit dem Flag 'Dieser Pool enthält Seitentemplates' besitzen.
• Dann muss folgendes Template in diesem Pool angelegt werden:

Name: Form-Solutions: Konfiguration, Anchor ies.tple.formsolutions.configuration' und dem Inhalt:

<sp:io type="in">
  <em>
  Diese Konfigurationswerte werden über den Form-Solutions import gesetzt und können an dieser Stellen nicht geändert werden.
  Ist eine Änderung der Werte nötig, muss diese Änderung am Importer vorgenommen werden.
  </em>
  <br/>
  <br/>
  Webservice Url<br>
  <spt:text name="wsurl" size="80"/><br/>
  CMS-Key<br>
  <spt:text name="cms" size="80"/><br/>
  Nutzer-Nummer<br>
  <spt:text name="user" size="80"/><br/>
  <br/>
  Default LinkText<br>
  <spt:text name="sp_title" size="80"/><br/>
</sp:io>

• Es muss ein ArtikelPool 'Form-Solutions' unterhalb des Pools 'IES' mit dem Anchor 'ies.infp.formsolutions' angelegt werden.
• In den Pooleigenschaften für diesen ArtikelPool muss neben dem 'Standard Infosite Container' der 'Form-Solutions' Template-Pool für die Bearbeitung ausgewählt werden.
• In diesem Pool muss der FormSolution Konfigurations-Artikel (als Ressource) mit dem Anker ies.infe.formsolutions.configuration angelegt werden.
• Im Bearbeitungs-Step des Konfigurations-Artikel werden die WebserviceUrl https://pdf.form-solutions.net/ws2 und die von FormSolutions zur Verfügung gestellten Zugangsdaten eingetragen.

Anschließend kann der Tag <spt:formsolutions> verwendet werden.

Alte Implementation (bis Infosite5 5.11, Infosite6 6.1 und CityGov 3.7)

Funktionsweise

Referenzen der Formulare werden in den IES (Sitepark Information Enterprise Server) importiert und durch regelmäßige Imports synchron gehalten. Mit Hilfe des spt:formsolutions-Tag kann ein Link-Dialog geöffnet werden, um ein Formulare zu verwenden. Für jede erzeugte Verlinkung wird eine neue URL erzeugt. Über dieser URL kann das Formular vom Form-Solutions-Server geladen werden (Z.B. PDF). Der spt:formsolutions-Tag erzeugt einen Button über den das Formular konfiguriert werden kann. Nach Klick auf diesen Button öffnet sich eine Seite des Form-Solutions-Servers mit der das Formular konfiguriert wird.

Installation: a) Strukturen per XIP einspielen

• Das XIP-Paket formsolution.xip kann beim Support angefragt werden. Anschließend kann es über die Konsole oder über die XIP-Oberfläche >>CMS-HOST<</ies/xip/ eingespielt werden. Beim Einspielen des XIP werden lediglich im Reiter 'Import Regeln' alle Werter mit Ausnahme von 'Elemente werden bei neuen Parents nicht verschoben' ausgewählt.

Installation: b) Strukturen manuell erstellen

• Es muss ein ArtikelPool 'Form-Solutions' unterhalb des Pools 'IES' mit dem Anchor 'ies.infp.formsolutions' angelegt werden.
• Es muss ein TemplatePool 'Form-Solutions' mit dem Anchor 'ies.tplp.formsolutions' existieren, der unterhalb des Pools 'IES' hinterlegt ist. Der Pool muss mit dem Flag 'Dieser Pool enthält Seitentemplates' besitzen.
• Dann müssen die beiden folgenden Templates in diesem Pool angelegt werden:

1. 'Form-Solutions: Konfiguration' mit dem Anchor 'ies.tple.formsolutions.configuration' und dem Inhalt:

<sp:io type="in">
  <em>
  Diese Konfigurationswerte werden über den Form-Solutions import gesetzt und können an dieser Stellen nicht geändert werden.
  Ist eine Änderung der Werte nötig, muss diese Änderung am Importer vorgenommen werden.
  </em>
  <br/>
  <br/>
  Webservice Url<br>
  <spt:text name="wsurl" readonly="true" size="80"/><br/>
  CMS-Key<br>
  <spt:text name="cms" readonly="true" size="80"/><br/>
  Nutzer-Nummer<br>
  <spt:text name="user" readonly="true" size="80"/><br/>
</sp:io>

2. 'Form-Solutions: Formular' mit dem Anchor 'ies.tple.formsolutions.form' und dem Inhalt:

<sp:io type="in">
<div class="editorblock">
  <h2>Angaben zum Formular</h2>
  <div style="margin:0.5em">
    Formular-Nummer<br/>
    <spt:text name="fs_fnr" size="30"/><br/>
    Anzahl der Seiten<br/>
    <spt:text name="fs_pagecount" size="30"/><br/>
    Erzeugt am<br/>
    <spt:text name="fs_created" size="30"/><br/>
    Letzte Änderung am<br/>
    <spt:text name="fs_changed" size="30"/><br/>
    Bemerkung<br/>
    <spt:text name="fs_bem" size="30"/><br/>
    Beschreibung<br/>
    <spt:text name="fs_beschr" size="30"/><br/>
    Typ<br/>
    <spt:text name="fs_type" size="30"/><br/>
    <br/>
    <strong>Kategorie<sp:if name="fs_categories.size" gt="1">n</sp:if></strong><br/>
    <spt:iterator name="fs_categories" layout="plain" item="it">
      <sp:select name="fs_category" type="link" style="width:20.8em">
        <sp:option value="">&nbsp;</sp:option>
        <sp:sort name="sortedList" collection="!{ies.infp.formsolutions.categories}.elements" keys="formsolutionscategory"/>
        <sp:loop collection="sortedList" item="it">
        <sp:option value="${it.id}"><sp:print name="it.formsolutionscategory"/></sp:option>
        </sp:loop>
      </sp:select>
      <sp:if name="it.isFirst" neq="true">
        <img src="<sp:print name="host"/>/img/icn_mini_delete.gif" title="Kategorie löschen" alt="Kategorie löschen" width="13" height="13" onclick="iteratorAction('removeItem', '<sp:print name="currentItemID"/>', '<sp:print expression="${htmlanchorCounter} - 1"/>', '<sp:print name="system.form"/>')" style="margin-bottom:-2px;border-width:1px;border-style:solid;border-color:#E6E6E6 #898989 #898989 #E6E6E6;vertical-align:textbottom;cursor:pointer;">
      </sp:if><br>
      <sp:if name="it.isLast" eq="true">
        <a href="#" onclick="iteratorAction('addItem', '<sp:print name="currentListID"/>', '<sp:print expression="${htmlanchor} + 1"/>', '<sp:print name="system.form"/>')" style="display:block;margin-top:3px;margin-left:5px;border-width:1px;border-style:solid;border-color:#E6E6E6 #898989 #898989 #E6E6E6;padding:2px;float:left;font-size:95%;text-decoration:none;">Kategorie hinzufügen</a><br>
      </sp:if>
    </spt:iterator>
  </div>
</div>
</sp:io>

Server-Konfiguration

Um den Import einrichten zu können müssen von dem Kunden folgende Informationen bereit gestellt werden:

• CMS-Key und Kunden-ID, die von FormSolutions zur Verfügung gestellt werden.
• Ein Login und Passwort für den IES-User, der die Daten in den IES-Mandanten einspielt. Dieser kann nach eigenen Angaben konfiguriert werden.

Dann sind die beiden folgende Dateien in dem Ordner /etc/sitepark/conf/ anzulegen:

1. form-solutions.xml
Diese XML-Datei definiert alle nötigen Parameter für den Daten-Import in den IES und besitzt sämtliche Angaben um die Formular-Daten von dem FormSolutions-Server zu laden.

• Hier müssen die Attribute cmskey und user entsprechend den Daten des Kunden ersetzt werden.
• Außerdem müssen in der Zeile ies-connection die Parameter login, password und anchor_of_the_client gesetzt werden.
• Vorsicht: Sollte der Key Zeichen wie '&' enthalten, muss der unten verwendete Platzhalter '${cmskey}' gegen den XML encodeten Key getauscht werden!

<?xml version="1.0" encoding="UTF-8"?>
<import>
  <logging>
    <appender name="FILE" class="org.apache.log4j.RollingFileAppender">
      <layout class="org.apache.log4j.PatternLayout">
        <param name="ConversionPattern" value="%d %-5p %m%n"/>
      </layout>
      <param name="File" value="${sitepark.home}/formSolutions.import.log"/>
      <param name="MaxFileSize" value="10MB"/>
      <param name="MaxBackupIndex" value="10"/>
    </appender>
    <logger name="com.sitepark.ies" additivity="false">
      <appender-ref ref="FILE"/>
      <priority value="INFO"/>
    </logger>
  </logging>
  <ies-connection login="IMPORT-USER" password="IMPORT-USER-PASSWORD" client="IMPORT-CLINET" module="Form Solutions Importer"/>
  <options>
    <createElements>true</createElements>
    <deleteWorkDir>true</deleteWorkDir>
    <createPools>true</createPools>
    <updatePools>true</updatePools>
    <updateElements>true</updateElements>
    <deletePools>true</deletePools>
    <ignoreParents>false</ignoreParents>
    <deleteOnlyEmptyPools>true</deleteOnlyEmptyPools>
    <deleteElements>true</deleteElements>
    <publishMode>all-file</publishMode>
    <xslt>${sitepark.home}/conf/formSolutions.xslt</xslt>
    <syncFile>${sitepark.home}/conf/formSolutions.sync</syncFile>
    <attributes>
      <attribute name="wsurl">https://pdf.form-solutions.net/ws2</attribute>
      <attribute name="cmskey">abcdefghijklmnopqrstxyz</attribute>
      <attribute name="user">12345678-9999-9999</attribute>
    </attributes>
  </options>
  <source type="http" url="${wsurl}/getformlist.php" method="post">
    <header name="SOAPAction">"urn:FS#getformlist"</header>
    <body content-type="text/xml; charset=UTF-8"><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/" xmlns:tns="urn:FS" SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
  <SOAP-ENV:Body>
    <tns:getformlist xmlns:tns="urn:FS">
      <cms xsi:type="xsd:string">${cmskey}</cms>
    </tns:getformlist>
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>]]></body>
  </source>
</import>

2. form-solutions.xslt Mit der XSLT werden die XML-Daten von FormSolution in ein XML-Format transformiert, welches der IES einlesen kann, um die entsprechenden Artikel zu erstellen.

<?xml version="1.0" encoding="ISO-8859-1"?>
<xsl:stylesheet version="1.0"
  xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
  xmlns:xip="http://ies.sitepark.com/xip"
  extension-element-prefixes="xip">

  <xsl:output method="xml" encoding="UTF-8" indent="yes"/>
    
  <xsl:function name="xip:getCategoryId"> <xsl:param name="s"/>
    <!-- Erstes Zeichen ermitteln -->
    <xsl:variable name="id" select="substring-before($s,' ')"/>
    <xsl:value-of select="substring-before($s,' ')"/>
  </xsl:function>

  <xsl:key name="categoryId" match="item" use="xip:getCategoryId(kat)"/>

  <xsl:template match="/">
    <xip>
      <resource parent="ies.infp.formsolutions" anchor="ies.infe.formsolutions.configuration" name="Form Solutions Konfiguration" template="ies.tple.formsolutions.configuration">
         <text name="wsurl">${wsurl}</text>
         <text name="cms">${cmskey}</text>
         <text name="user">${user}</text>
      </resource>
    <!-- Schleife über Kategorien -->
    <xsl:for-each select="//item[generate-id() = generate-id(key('categoryId', xip:getCategoryId(kat))[1])]">
      <xsl:variable name="category" select="xip:getCategoryId(kat)"/>
      <!-- gelöschte Formulare haben keine Kategorie -->
      <xsl:if test="$category != ''">
        <xsl:variable name="categoryName" select="kat/text()"/>
        <articlepool parent="ies.infp.formsolutions" anchor="ies.infp.formsolutions.forms" name="FormSolutions Formulare">
          <articlepool parent="ies.infp.formsolutions.forms" anchor="formsolutions.category.{$category}" name="{$categoryName}">
            <resource>
              <text name="container" anchor="is5:gui.container.infosite.standard"/>
              <text name="registrationTemplate" anchor="is5:gui.container.infosite.standard.all"/>
              <text name="editorTemplatePool" anchor="ies.tplp.formsolutions"></text>
            </resource>
            <!-- Schleife über alle mit gleicher Kategorie -->
            <xsl:for-each select="key('categoryId',$category)">
              <xsl:variable name="fnr_id" select="replace(fnr,' ','_')"/>
              <resource anchor="formsolutions.form.{$fnr_id}" name="{title}" template="ies.tple.formsolutions.form">
                <comment><xsl:value-of select="bem"/></comment>
                <text name="fs_fnr"><xsl:value-of select="fnr"/></text>
                <text name="fs_title"><xsl:value-of select="title"/></text>
                <text name="fs_pagecount"><xsl:value-of select="pagecount"/></text>
                <text name="fs_created"><xsl:value-of select="created"/></text>
                <text name="fs_changed"><xsl:value-of select="changed"/></text>
                <text name="fs_beschr"><xsl:value-of select="beschr"/></text>
                <text name="fs_type"><xsl:value-of select="type"/></text>
              </resource>
            </xsl:for-each>
          </articlepool>
        </articlepool>
      </xsl:if>
    </xsl:for-each>
    </xip>
  </xsl:template>
</xsl:stylesheet>

Aktivierung

Der Import kann manuell durch Aufruf des Skriptes iesxip (früher iespkg) gestartet werden:

server:# /srv/sitepark/bin/iesxip /srv/sitepark/conf/form-solutions.xml

• Zur regelmäßigen Synchronisation ist ein Cronjob in folgender Form notwendig:

# m h  dom mon dow   command
# Formulare von form-solutions aktualisieren.
1 1 * * * /srv/sitepark/bin/iesxip  /srv/sitepark/conf/form-solutions.xml

• Auf Windows-Systemen müsste eine entsprechende 'Aufgabe' konfiguriert werden, die den beispielhaften Aufruf einmal täglich ausführt.

c:/Programme/Sitepark/bin/iesxip   c:/Programme/Sitepark/conf/form-solutions.xml