FormSolutions Schnittstelle

Aus SiteparkWiki
Zur Navigation springen Zur Suche springen

Formulare der Firma Form-Solutions können in den IES integriert werden. Hierzu ist eine Form-Solutions Lizenz erforderlich.

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.

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 wir dem Kunden ein CMS-Key für die Form-Solutions-Schnittstelle mittgeteilt, 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.
  • Die zu verwendenden Formulare können zur Personalisierung mit einem Form-Solutions-Nutzer verknüpft werden. Hier muss ein Default-Nutzer bekannt sein, der initial für neue Formular-Links verwendet wird. Diese Nutzer kann bei der weiteren Konfiguration des Formulars geändert werden.

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.


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 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="false" 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>
    <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">frtugzhuq0395s64i7rgU3jvlsdjf030</attribute>
      <attribute name="user">05515000-0007-0000</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>
  &lt;/source&gt;
</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="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)">
          <resource anchor="formsolutions.form.{fnr}" name="{title} ({fnr})" 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_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>
      </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