FormSolutions Schnittstelle: Unterschied zwischen den Versionen

Version vom 30. Januar 2014, 08:39 Uhr

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 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="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>
    <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_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