Upload
others
View
5
Download
0
Embed Size (px)
Citation preview
dox42 Server V3.5.1-4.2
Dokumentation
www.dox42.com 2
Zusammenfassung
In die diesem Dokument sind die Serviceschnittstelle sowie die Konfigurationseinstellung des
dox42Servers beschrieben.
Inhalt
Zusammenfassung ............................................................................................................................................................ 2
Inhalt ...................................................................................................................................................................................... 2
Dokumentinfo ..................................................................................................................................................................... 3
Service-Schnittstelle ........................................................................................................................................................ 4
SOAP Schnittstelle ........................................................................................................................................................ 4
REST Schnittstelle ........................................................................................................................................................ 5
Service-Header .............................................................................................................................................................. 6
Azure Active Directory Header ............................................................................................................................... 6
OutputActions ..................................................................................................................................................................... 7
SaveAction ....................................................................................................................................................................... 8
SharePointAction.......................................................................................................................................................... 9
Spezielle SharePoint und Managed Metadata Felder setzen.................................................................... 11
EmailAction .................................................................................................................................................................. 12
ReturnAction ................................................................................................................................................................ 15
PrintAction .................................................................................................................................................................... 16
dox42LIVEAction........................................................................................................................................................ 16
Konfigurationsparameter ............................................................................................................................................ 17
Beispiel ........................................................................................................................................................................... 18
CORS Konfiguration ................................................................................................................................................... 19
Azure Active Directory Zugriff .............................................................................................................................. 20
Custom Error Messages Beispiel ......................................................................................................................... 20
Hyphenation Dictionaries Beispiel ..................................................................................................................... 20
Maximale Request-Größe und Timeout ............................................................................................................ 20
Lizenz Aktivierung ..................................................................................................................................................... 21
Installation ......................................................................................................................................................................... 22
Upgrade ............................................................................................................................................................................... 24
Support ................................................................................................................................................................................ 24
www.dox42.com 3
Dokumentinfo
Version: dox42 Server V3.5.1-4.0
Autor: DI Christian Bauer
Datum: 03.08.2020
www.dox42.com 4
Service-Schnittstel l e
Der dox42 Server ist über eine SOAP- und eine REST-WebService Schnittstelle erreichbar.
Operation: GenerateDocument/GenerateSlides
Die Operation lässt sich über folgende Paramater steuern:
› DocTemplate (String)
Pfad zum Dokumenttemplate
(z.B. C:\doctemplates\solarantrag.docx, ~\templates\mobilfunkrechnung.docx,
C:\doctemplates\salesreport.pptx)
› InputParams (Key-Value String/String)
Liste der Inputparameter und Werte:
› ParamName: Name des Parameters (nicht case-sensitive)
› Value: Wert des Parameters
› PostGenActions
Liste, der nach der Dokumentgenerierung abzuarbeitenden OutputActions:
› ActionName: Name der Action (z.B. SaveAction), nicht case-sensitive
› Params: Parameter der Action (wie InputParams)
Operation: GenerateSpreadSheet
Die Operation lässt sich über folgende Paramater steuern:
› DataMap (String)
Pfad zum DataMap
(z.B. C:\doctemplates\salesreport.dm, ~\templates\mobilfunkrechnung.dm)
› InputParams (Key-Value String/String)
Liste der Inputparameter und Werte:
› ParamName: Name des Parameters (schreibungsunabhängig)
› Value: Wert des Parameters
› PostGenActions
Liste, der nach der Dokumentgenerierung abzuarbeitenden OutputActions:
› ActionName: Name der Action (z.B. SaveAction), nicht case-sensitive
› Params: Parameter der Action (wie InputParams)
Die Parameter der einzelnen OutputActions sind in diesem Dokument beschrieben.
SOAP Schnittstelle
URL: http://www.YourDomain.com/dox42service.asmx
WSDL: http://www.YourDomain.com/dox42service.asmx?WSDL
www.dox42.com 5
REST Schnittstelle
URL: http://www.YourDomain.com/dox42RestService.ashx
REST und SOAP Schnittstelle haben identische Parameter und OutputActions. Bei der REST
Schnittstelle werden alle Parameter als URL-Parameter übergeben. Ab Version 3.6.3 können alle
Parameter auch als POST Parameter übergeben werden. Dabei gilt die folgende Syntax:
Parametername Erfordernis Auswirkung
Operation Obligatorisch
GenerateDocument |
GenerateSpreadSheet
Auswahl der aufzurufenden
Operation
DocTemplate Obligatorisch bei
Operation=GenerateDocument
Pfad zum Dokumenttemplate
DataMap Obligatorisch bei
Operation=
GenerateSpreadSheet
Pfad zum DataMap
InputParam.
<ParameterName>
Für jeden Inputparameter Übergabe der Werte für
Inputparameter, z.B.:
InputParam.KundenID=42
<OutputAction>.
<ParameterName>
Für jeden Parameter jeder
OutputAction
Übergabe der Werte für
OutputAction-Parameter, z.B.:
ReturnAction.Format=pdf
ReturnAction.disp Optional
Inline | attachment
Steuert das Browser-Handling
des zurückgelieferten
Dokuments
ReturnAction.Mode Optional
File (Standard) | Text
Bei Text wird der Inhalt des
Dokuments direkt als Text im
Browser ausgegeben. Das
ermöglicht u.a. das dynamische
Generieren von HTML Seiten.
ReturnAction.fileName Optional, nur bei
ReturnAction.disp = attachment
sinnvoll
Name des zurückgelieferten
Dokumentes
RedirectURL Optional, nur ohne
ReturnAction sinnvoll
Nach Generierung wird ein
Redirect durchgeführt
www.dox42.com 6
Achtung: URL-Encoding für Sonderzeichen! (http://www.w3schools.com/tags/ref_urlencode.asp):
„Kunde.Name=Müller“ => „Kunde.Name=M%C3%BCller“
Beispiel für einen REST-Aufruf:
http://www.YourDomain.com/dox42RestService.ashx?
Operation=GenerateDocument&
DocTemplate=%7e%5cTemplates%5cSales_Report%5cSales_Report.doc &
InputParam.SelectEmployee=5&InputParam.SelectYear=2012&
ReturnAction.format=pdf&ReturnAction.fileName=SalesReport.pdf&ReturnAction.disp=attachment
HTTP Request-Body
Sollen umfangreiche Daten an das dox42 Service übertragen werden, so können diese als POST
Parameter oder im Request-Body (ab Version 4.0) übertragen werden. Um den Request-Body
auszulesen legen Sie in Ihrer DataMap einen InputParameter mit dem Namen „RequestBody“ an. An
diesen InputParameter werden die Daten aus dem HTTP Request Body übergeben und können z.B.
mit einer XML/JSON Datenquelle ausgelesen werden.
Service-Header
Das dox42 SOAP Service lässt sich über einen Service-Header absichern. Dieser enthält
Benutzername und Passwort. In der web.config kann die Verwendung des Service-Headers
konfiguriert werden.
Azure Active Directory Header
Das dox42 Service versteht einen Authorization Header, der ein Azure Active Directory Token enthält
(ab Version 4.0).
Javascript Beispiel:
xhttp.setRequestHeader("Authorization", 'Bearer ' + token);
www.dox42.com 7
OutputAct ions
Im Produkt dox42 Server sind folgende OutputActions enthalten:
› SaveAction: Generiertes Dokument in einem Dateiordner speichern
› SharepointAction: Generiertes Dokument in einer SharePoint-Dokumentenbibliothek
speichern
› EmailAction: Generiertes Dokument per E-Mail versenden
› ReturnAction: Generiertes Dokument über die WebService-Schnittstelle zurückliefern
› PrintAction: Generiertes Dokument drucken
› CustomOutputAction: Sie können auch selbst eine dox42 OutputAction implementieren und
verwenden. Custom Output Actions müssen in der web.config
registriert werden (analog Custom Data Sources) und folgendes
Interface implementieren: dox42CustomOutputActionKit.ICustomOutputAction
Im Folgenden sind die Parameter der OutputActions beschrieben. Die Parameternamen werden nicht
case sensitive behandelt. In allen Parameterwerten können Datenfelder verwendet werden (siehe
Tabelle für Ausnahmen).
Beispiel: FileName = „Antrag_<%Buerger.Name%>.pdf“
www.dox42.com 8
SaveAction
Parametername Erfordernis Auswirkung
FileName obligatorisch Speichername, unter dem das Dokument
abgelegt wird.
z.B. C:\Dokumente\SalesReport.pdf
Über die Dateierweiterung wird der Dateityp
bestimmt (.docx, .xlsx, .pptx, .pdf, html,...).
Siehe auch weiter unten.
SpecialFormat
(nur dox42ForDocuments)
optional Bei PDF kann das PDF-Format bestimmt
werden, Werte:
PDFA1b und PDFForm. Bei PDFForm bleiben
Formularfelder im PDF erhalten.
Bei HTML gibt es folgende Optionen:
HTMLCode
Der Text des dox42-Templates wird als HTML-
Code interpretiert.
HTMLZIP
Eine ZIP Datei mit der HTML Datei und den
enthaltenen Images wird erzeugt. (Ab Version
3.6.3).
Bei Textdateien (*.txt) kann eine alternative
Extension angegeben werden. Damit können
Metadaten-files für Archivsysteme erzeugt
werden, Beispiel:
FileName = Order_<%Cust.OderNo%>.txt
SpecialFormat = jpl
Ergebnis: Order_42.jpl
(seit Version 3.5)
Sign optional Wert: true
Bei PDF kann eine digitale Signatur aufgebracht
werden (nur dox42ForDocuments) Das
Zertifikat und das dazugehörige Passwort
müssen in der web.config definiert sein.
Mögliche Ausgabeformate
Word: doc, docx, docm, dot, dotx, pdf, html, txt, jpg, png, tiff, bmp, rtf, odt Excel: xls, xlsx, xlsm, xlt, xltx, xltm, xlsb, txt, csv, html, pdf, xml, tiff, ods PowerPoint: pptx, pps, pdf, tiff
www.dox42.com 9
SharePointAction
Parametername Erfordernis Auswirkung
Site obligatorisch Die Sharepoint-Site
z.B. http://mysite.com
Library obligatorisch Die Sharepoint-Dokumentenbibliothek
bzw. der Name des Rootfolders
FileName obligatorisch Speichername, unter dem das Dokument
abgelegt wird.
z.B. SalesReport.pdf
Über die Dateierweiterung wird der Dateityp
bestimmt (.docx, .xlsx, .pptx, .pdf, html,...).
Folder optional Dokument in diesen Ordner speichern.
SpecialFormat
(nur dox42ForDocuments)
optional Bei PDF kann das PDF-Format bestimmt
werden, mögliche Werte:
PDFA1b und PDFForm. Bei PDFForm bleiben
Formularfelder im PDF erhalten.
Bei HTML kann die Option:
HTMLCode
gesetzt werden, dann wird der Text des
generierten Dokuments als HTML-Code
interpretiert.
Sign optional Wert: true
Bei PDF kann eine digitale Signatur aufgebracht
werden (nur dox42ForDocuments) Das
Zertifikat und das dazugehörige Passwort
müssen in der web.config definiert sein.
Field1.Name
Field1.Value
optional Fields ermöglichen das Setzen von Spalten in
der SharePoint-Dokumentenbibliothek. Sie
können mehrere Felder setzen: Field1, Field2,…
Benützen Sie als Feldname den SharePoint
interal field name.
Tipp: Sie können den internal field name
herausfinden, indem Sie die Liste mit der dox42
SharePoint Datenquelle öffnen und die
Checkbox „use internal field names“ setzen.
ContentType optional Name des zu setzenden Content-Types
www.dox42.com 10
DocumentDataField
optional Wird dieses Feld angegeben, so wird nicht das
generierte Dokument in die Sharepoint-
Dokumentenbibliothek gespeichert, sondern
das Dokument aus dem angegeben dox42
Datenfeld geladen (Z.B.: Data.MyDokument)
und in die Sharepoint- Dokumentenbibliothek
gespeichert.
Das DocumentDataField kann einen Pfad, eine
URL oder ein binäres Dokument enthalten.
CheckInMessage optional Wird dieses Feld angegeben, checkt der Server
das Dokument nach dem Speichern mit der
angegebenen Nachricht ein. Gibt es bereits ein
gleichnamiges Dokument in der Library, so wird
dieses vorher automatisch ausgecheckt.
Username optional Wenn nicht angegeben, wird der Service
Account des dox42 Servers als SharePoint User
verwendet.
Password optional
SharePoint_online optional true/false
Muss bei SharePoint online (Office 365) gesetzt
werden - alternativ zu Azure_AD.
SharePoint_FBA optional true/false
Muss bei Sites mit aktivierter Forms based
Authentication gesetzt werden.
Azure_AD optional true/false
Im Request muss ein Authorization Header mit
einem Azure Active Directory Token enthalten
sein, welches zur Authentisierung verwendet
wird - alternative zu SharePoint_online.
(Ab Version 4.0).
retry_count optional Eine natürliche Zahl >= 0
Definiert, dass die SharePointAction das
Speichern im Fehlerfall (z.B.: Timeout) mehrfach
versucht und wie oft.
Default = 0 (no retry).
(Ab Version 4.1.3).
www.dox42.com 11
Spezielle SharePoint und Managed Metadata Felder setzen
Bei Auswahlfeldern (Choice) setzen Sie einfach den Wert.
Bei Auswahlfeldern (Choice), die mehrere Werte enthalten können (Multi Value), setzen Sie diese
durch „;#“ getrennt, also z.B.: „rot;#gelb;#blau“
Bei Lookup/Person/Group-Felder setzen Sie die ID.
Bei Lookup/Person/Group-Felder, die mehrere Werte enthalten können (Multi Value), müssen Sie ID
und Wert angeben: „ID;#Wert“ , also z.B.: „3;#Hawaii;#9;#Vienna“. Tatsächlich berücksichtigt wird
dabei aber nur die ID.
www.dox42.com 12
EmailAction
Parametername Erfordernis Auswirkung
Mode optional
mögliche Werte:
TxtEMail
HtmlEMail
Attachment (Standardwert)
Bestimmt ob das generierte
Dokument als Text oder HTML für
den E-Mail-Text verwendet, oder als
Attachment mitgesendet wird.
TxtEMail und HtmlEMail sind nur bei
GenerateDocument sinnvoll zu
verwenden.
FileName Obligatorisch bei Mode =
Attachment, sonst ignoriert
Name des Attachments
Über die Dateierweiterung wird der
Dateityp bestimmt (.docx, .xlsx,
.pptx, .pdf, html,...).
SpecialFormat
(nur dox42ForDocuments)
optional Bei PDF kann das PDF-Format
bestimmt werden, Werte:
PDFA1b und PDFForm. Bei PDFForm
bleiben Formularfelder im PDF
erhalten.
Bei HTML kann die Option:
HTMLCode
gesetzt werden, dann wird der Text
des generierten Dokuments als
HTML-Code interpretiert.
Sign optional Wert: true
Bei PDF kann eine digitale Signatur
aufgebracht werden (nur
dox42ForDocuments). Das Zertifikat
und das dazugehörige Passwort
müssen in der web.config definiert
sein.
Receiver obligatorisch Empfänger E-Mail-Adressen
bei mehreren Adressen durch ein
Komma getrennt
ReceiverCC optional Carbon Copy Empfänger
ReceiverBCC optional Blind Carbon Copy Empfänger
www.dox42.com 13
Parametername Erfordernis Auswirkung
Sender optional Absender E-Mail-Adresse
Wird diese nicht angegeben, so wird
die in der web.config konfigurierte
Adresse verwendet.
MailServerUsername optional Kann zusätzlich zu Sender
angegeben werden. Dann wird für
die Authentifizierung am Mailserver
dieser Username verwendet.
Seit Version 3.6.2.4
SenderPassWord entfällt, wenn Sender oder
MailServerUsername nicht
angegeben,
sonst obligatorisch
Passwort des Absenders für sein E-
Mail-Konto oder
MailServerUsername auf den, in der
web.config konfigurierten, E-Mail-
Server.
Header obligatorisch E-Mail-Betreff
Body optional
E-Mail-Text als reiner Text
(nur bei mode = Attachment)
HtmlBody optional
E-Mail-Text als HTML
(nur bei mode = Attachment)
BodyTemplate optional Ein dox42 Word Template mit dem
der Email-Body generiert wird.
Dieses Template muss die gleiche
Datamap als das Attachment
benützen.
(nur bei mode = Attachment)
Seit Version 3.5.1
StaticAttachment1.Path
StaticAttachment1.Base64
StaticAttachment1.Name
optional (alternativ zu
Base64)
z.B. C:\Bilder\MeinBild.jpg
Base64 codierte Datei
optional (alternativ zu Path)
obligatorisch bei Base64,
sonst optional
z.B. MeinBild.jpg
StaticAttachments ermöglichen das
Mitsenden von statischen Beilagen.
Sie können mehrere Beilagen
mitsenden: StaticAttachment2…
StaticAttachment3…
Es kann der Pfad zu einer Datei oder
die Beilage Base64-codiert
übergeben werden.
www.dox42.com 14
Parametername Erfordernis Auswirkung
MailServer optional Damit lässt sich der in der
Web.Config eingestellt Mailserver
übersteuern.
MailServerPort Optional
Ab Version 3.4.3.10
Damit lässt sich der in der
Web.Config eingestellt Mailserver
Port übersteuern.
SSL Optional
Ab Version 3.5
true oder false
SaveMSGFile Optional
Ab Version 3.5.0.19
Dateipfad unter dem das gesendete
Mail als MSG-Datei gespeichert
werden soll. Z.B.: C:\Windows\Temp\Order_<%Customer.ID%>.msg
SendMode Optional
Ab Version 3.6
Mögliche Werte: send, save, return
send: Standardwert, Mail wird sofort
versendet.
save: Mail wird nicht versendet,
sondern als Draft unter dem in
SaveMSGFile angegebenen Pfad
gespeichert. Parameter SaveMSGFile
muss angegeben sein.
return: Mail wird nicht versendet,
sondern als Draft in der Return-
Message zurückgeliefert. Ab Version
3.6.3.
Um bei E-Mail Adresse einen Alias zu verwenden benützen Sie folgende Syntax (seit Version 3.6.2.5):
MyCompany Sales {[email protected]}
MyCompany Sales <[email protected]>, funktioniert auch, kann aber beim REST-Service zu
Fehlern führen.
www.dox42.com 15
ReturnAction
Parametername Erfordernis Auswirkung
Format obligatorisch Dateityp (.docx, .xlsx, .pptx, .pdf, html,...).
Mode optional
mögliche Werte:
File (Standard)
Text
Definiert ob das generierte Dokument als Datei
(Mode=File) in ServiceResult.GeneratedDocs oder
als Text (Mode=Text) in
ServiceResult.ResultMessage retourniert wird.
SpecialFormat
(nur dox42ForDocuments)
optional Bei PDF kann das PDF-Format bestimmt werden,
Werte:
PDFA1b und PDFForm. Bei PDFForm bleiben
Formularfelder im PDF erhalten.
Bei HTML kann die Option:
HTMLCode
gesetzt werden, dann wird der Text des
generierten Dokuments als HTML-Code
interpretiert.
Sign optional Wert: true
Bei PDF kann eine digitale Signatur aufgebracht
werden (nur dox42ForDocuments). Das Zertifikat
und das dazugehörige Passwort müssen in der
Web.config definiert sein.
www.dox42.com 16
PrintAction
Parametername Erfordernis Auswirkung
PrinterName optional Der zu verwendende Drucker
Collate optional
(true/false)
Sortieren?
Copies optional Anzahl Kopien
Duplex optional
(Vertical,
Horizontal,
Simplex)
Duplexdruck
FromPage optional Drucken von Seite …
ToPage optional …bis Seite
dox42LIVEAction
Die dox42LIVEAction verwendet eine Output Konfiguration aus einer dox42LIVE.config Datei um
Output Action auszuführen. Der Aufbau einer dox42LIVE.config ist in der dox42 LIVE Dokumentation
beschrieben.
Um eine dox42LIVEAction in einem dox42 SOAP oder REST Service zu verwenden speichern Sie die
dox42LIVE.config Datei in dasselbe Verzeichnis als dox42RestService.ashx und dox42Service.asmx ,
normalerweise: C:\dox42Server.
Ab Version 4.1.3.
Parameter name Requirement Effect
LiveActionName mandatory Der LiveActionName wie in der dox42LIVE.config
definiert.
www.dox42.com 17
Konfigurat ionsparameter
Folgende Parameter können für den dox42 Server in den AppSettings der web.config konfiguriert
werden:
› LicenseFilePath: Gibt den Pfad des Speicherortes an, wo der Server das License-File
ablegen soll. Ist kein License-File vorhanden, nimmt der dox42 Server Kontakt mit dem d
dox42 License-Server auf, um den LicenseKey zu verifizieren. Gelingt dies, so schreibt er das
License-File auf den konfigurierten Pfad.
› LicenseKey: LicenseKey des dox42 Servers
› MailServer: E-Mail-Server, der zum Versenden von E-Mails genützt wird (optional)
› MailServerPort: E-Mail-Server Port (optional)
› dox42ServerMail: Standard Absenderadresse des dox42 Services (optional)
› MailServerPassWord: Passwort zum dox42ServerMail (optional)
› SendErrorsToMail: Standard E-Mail-Adresse für Fehlermeldungen (optional)
› Certificate: zum Signieren verwendetes Zertifikat (optional)
› CertificatePassWord: Passwort des Zertifikates (optional)
› CheckServiceHeader (true/false): Gibt an, ob der Service-Header ausgewertet werden soll. Bei
“false” muss kein Service-Header mitgesendet werden.
› UserPermissionODBCConnectionString: ODBC ConnectionString auf eine Datenbank, welche
User-Permissions enthält
(Pflicht, wenn CheckServiceHeader = true)
› CheckUserPermissionSQL: Select Statement, welches auf der
UserPermissionODBCConnectionString-Datenbank ausgeführt wird. Das Statement muss 1
oder “true” für erfolgreiche Autorisierung des Users zurückliefern. Im Statement werden die
Tags %username% und %password% gegen die im Header mitgelieferten Werte
ausgetauscht.
(Pflicht, wenn CheckServiceHeader = true)
› ThrowExceptionOnError (true/false):
true: Bei einem Fehler retourniert das Service eine Exception.
false (oder nicht vorhanden): Fehlermeldungen werden in der ResultMessage übergeben.
Dieser Konfigurationsparameter steht ab Build 3.3.0.8 zur Verfügung
› CustomErrorMessagesFile:
Pfad eines XML Files mit den Custom Error Messages (opional). Mittels Custom Error
Messages ist es möglich Fehlermeldungen, die einen definierten Text beinhalten, durch
andere Fehlermeldungen zu ersetzen. Ein Beispiel für ein solches File finden Sie im Anhang.
› HyphenationDictiorariesFile:
Pfad eines XML Files mit Hyphenation Dictionaries (opional). Mittels Hyphenation
Dictionaries ist es möglich die automatische Silbentrennung zu steuern. Ein Beispiel für ein
solches File finden Sie im Anhang. (Ab Version 3.4.3.10)
www.dox42.com 18
› CheckTrustedTemplateLocations (true/false):
true: Bei jedem Aufruf wird geprüft, ob der Pfad/Link des Templates bzw. der Datamap mit
einem Pfad/Link in der Sektion „trustedTemplateLocations“ beginnt. Ist das nicht der Fall,
wird der Call abgebrochen.
false (oder nicht vorhanden): Keine Prüfung.
ACHTUNG: Das Ausschalten dieser Option ermöglicht jeden, der Ihr dox42 Service
aufrufen darf, beliebige Templates/DataMaps auch von unbekannten Internet URLs auf
Ihrem Server zu generieren! Wir empfehlen daher DRINGEND diese Option immer auf true
einzustellen.
Dieser Konfigurationsparameter steht ab Build 3.3.4 zur Verfügung
› TempFolder:
Pfad auf ein Verzeichnis, in dem der dox42 Server temporäre Dateien ablegen soll. Wird der
TempFolder nicht angegeben, so wird das Standard Windows Temp-Verzeichnis verwendet.
Dieser Konfigurationsparameter steht ab Version 3.5 zur Verfügung
› RESTInterfaceReturnsFullErrorInfo (true/false):
Bei true wird beim REST Call umfangreichere Fehlerinformation ausgegeben.
Dieser Konfigurationsparameter steht ab Version 3.6.1 zur Verfügung
› RESTInterfaceReturnsHTTPError500 (true/false):
Bei true wird beim REST Call bei einem Fehler der http Statuscode 500 gesetzt.
Dieser Konfigurationsparameter steht ab Version 4.0.1 zur Verfügung
› SOAPServiceReturnsFullErrorInfo(true/false):
Bei true wird beim SOAP Call bei einem Fehler umfangreichere Fehlerinformation
ausgegeben. Dieser Konfigurationsparameter steht ab Version 4.1.1.0 zur Verfügung
Beispiel
<appSettings>
<add key="LicenseFilePath" value="c:\dox42\dox42WebService\License" />
<add key="LicenseKey" value="…"/>
<add key="MailServer" value="smtp.1und1.de"/>
<add key="dox42ServerMail" value="[email protected]"/>
<add key="MailServerPassWord" value="…"/>
<add key="SendErrorsToMail" value="[email protected]"/>
<add key="Certificate" value="c:\dox42\dox42WebService\Certs\Certificate.pfx"/>
<add key="CertificatePassWord" value="…"/>
<add key="CheckServiceHeader" value="true"/>
<add key="UserPermissionODBCConnectionString"
value="Driver={SQL Server Native Client 10.0};Server=…;Database=…;Uid=…;Pwd=…;"/>
<add key="CheckUserPermissionSQL"
value="SELECT COUNT(*) FROM Users where Username =
'%username%' and Password = '%password%'" />
<add key="ThrowExceptionOnError" value="false"/>
<add key="CustomErrorMessagesFile" value="C:\dox42Server\CustomErrors.xml"/>
<add key="CheckTrustedTemplateLocations " value="true"/>
<add key="TempFolder " value="C:\dox42Server\WorkingDir"/>
<add key="RESTInterfaceReturnsFullErrorInfo" value="false"/>
<add key="RESTInterfaceReturnsHTTPError500" value="false" />
<add key="SOAPServiceReturnsFullErrorInfo" value="false" />
</appSettings>
www.dox42.com 19
Custom Data Sources werden in einer eigenen Sektion namens „customDataSources“ registriert.
<customDataSources>
<add key="CSVDataEngine.CSVDataSourceParser"
value="CSV Datenquelle;c:\dox42\dox42WebService\bin\CSVDataEngine.dll;"/>
</customDataSources>
Custom Output Actions Sources werden in einer eigenen Sektion namens „customOutputActions“
registriert.
<customOutputActions> <add key="MyCustomOutputActions.MyOutputAction" value=" MyOutputAction; c:\dox42\dox42WebService\bin\MyCustomOutputActions.dll;"/>
</customOutputActions>
Trusted Template Locations werden in einer Sektion names „trustedTemplateLocations“ erfasst.
<trustedTemplateLocations> <add key="local" value="C:\dox42Server\templates"/> <add key="sharepoint" value="http://www.mysharepoint.mycompany.com/dox42Templates"/> </trustedTemplateLocations>
In der NLog.config-Datei können Log Einstellungen vorgenommen werden. Die Konfiguration des
verwendeten Logging-Frameworks NLog ist unter www.nlog-project.org dokumentiert.
CORS Konfiguration
Wird der dox42 Server z.B. per Javascript XMLHttpRequest aus einer Web-Applikation unter einer
anderen URL als die Applikation selbst aufgerufen, kann es zu einem Cross-Origin Resource Sharing
(CORS) Fehler kommen.
Beispiel:
Aufrufende Web-Applikation: https://yourcompany.sharepoint.com/yoursite
dox42 Server: https://dox42server.yourcompany.com
Um dies zu ermöglichen können Sie den Zugriff in der web.config ermöglichen, Beispiel:
<system.webServer> <httpProtocol> <customHeaders> <clear /> <add name="Access-Control-Allow-Origin" value="*" /> <add name="Access-Control-Allow-Headers"
value="Content-Type, Accept, Authorization" /> <add name="Access-Control-Allow-Methods" value="GET,POST,OPTIONS" /> <add name="Access-Control-Expose-Headers"
value= "Content-Type, Content-Disposition, Accept" /> </customHeaders> </httpProtocol> </system.webServer>
Siehe auch:
https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS
http://www.w3.org/TR/cors/
www.dox42.com 20
Azure Active Directory Zugriff
Diese Einstellung ist nötig damit der dox42 Server auf Templates, welche in SharePoint Online
verwaltet warden, zugreifen kann. (Ab Version 4.0.)
ConfigSection:
<configSections>
. . . <section name ="azureAD" type ="dox42.Core.Utils.AzureADSectionHandler,dox42Core"/> </configSections>
Azure AD Section:
<azureAD> <add resource365="https://mytenant.sharepoint.com"
appID="…" tenant="…" clientKey="*********************************" />
</azureAD>
Custom Error Messages Beispiel
<?xml version="1.0" encoding="utf-8"?> <CustomErrorMessagesDS xmlns="http://dox42.com/CustomErrorMessagesDS.xsd"> <CustomErrorMessage> <Test2SearchInExc>Error uploading file http://mysharepoint</Test2SearchInExc> <NewMessage> SharePoint-farm not responding, please contact your administrator</NewMessage> </CustomErrorMessage> </CustomErrorMessagesDS>
Wenn Sie dieses File mit einem Text-Editor bearbeiten, achten Sie auf das Speichern im Encoding UTF-8.
Hyphenation Dictionaries Beispiel
<?xml version="1.0" standalone="yes"?> <HyphenationDictionary xmlns="http://www.dox42.com/HyphenationDictionary.xsd"> <Dictionary> <Culture>de-CH</Culture> <DictionaryPath>C:\dox42Server\hyph_de_CH.dic</DictionaryPath> </Dictionary> </HyphenationDictionary>
Um automatische Silbentrennung mit dem dox42 Word Add-In zu verwenden, stellen Sie ein entsprechendes File mit Namen HyphenationDictionary.config auf C:\Users\<<USER>>\AppData\Local\dox42V1
Maximale Request-Größe und Timeout
Wenn Sie große Request an dox42 senden, große Dateien retournieren oder bei Massendruck kann
es nötig sein die maximale Request-Größe oder auch den Timeout zu erhöhen. (Der Default Timeout
in ASP.NET beträgt 90 Sekunden. Danach bricht der IIS den Call ab.) Diese kann ebenfalls in der
web.config eingestellt werden:
www.dox42.com 21
<system.web>
<httpRuntime maxRequestLength="10000000" executionTimeout="1000"/>
</system.web>
Lizenz Aktivierung
Tragen Sie den Lizenzschlüssel in der Web.config unter „LicenseKey“ ein.
Beim ersten Aufruf kontaktiert der dox42 Server den dox42 License-Server um den Key zu aktivieren
und schreibt eine Lizenzdatei (*.lic) in das unter „LicenseFilePath“ angegebene Verzeichnis.
Sollte der Server nur über einen Proxy ins Internet zugreifen können, hilft vielleicht folgender Eintrag
in der web.config.
Sollten Sie keine Internetverbindung von Ihrem Server aus herstellen können, wenden Sie sich bitte
an [email protected]. Wir stellen Ihnen dann eine Lizenzdatei zur Verfügung.
www.dox42.com 22
Instal lat ion
Im Folgenden wird die Installation auf einem Windows 2008 R2 Server mit IIS 7.5 und installiertem
ASP.NET 4.0 (oder höher) beschrieben.
1. Kopieren Sie das Verzeichnis dox42ServerVXXXX\dox42ServerVXXXX\dox42Server auf C:\dox42Server (Sie können auch ein anderes virtuelles Verzeichnis wählen.)
2. Richten Sie im inetmgr eine Site dafür ein:
Achten Sie dabei auf den Port! Sie können natürlich einen anderen Port vergeben. Sehr häufig ist aber der vorbelegte (Port 80) bereits durch andere Webanwendungen (z.B. Sharepoint) in Verwendung. Selbstverständlich unterstützt der dox42 Server https.
3. Kopieren Sie Ihre Aspose.Total.Lic File in das Bin Verzeichnis Ihres dox42 Servers (C:\dox42Server\Bin) – für Testversion nicht notwendig.
4. Installieren Sie das NET 4.5.2 Framework.
5. Aktivieren Sie ASP.NET mittels Server Manager (inklusive HTTP Activation).
6. Wenn Sie mit diesem dox42 Server auf SharePoint Online auf Office 365 zugreifen möchten, installieren Sie außerdem Microsoft SharePoint Server 2013 Client Components SDK. Download: http://www.microsoft.com/en-us/download/details.aspx?id=35585
7. Führen Sie iisreset aus.
www.dox42.com 23
8. Konfigurieren Sie den dox42 Server-AppPool etwa wie folgt:
Hier wurde ein Service-User namens dox42Server als Identität verwendet. Statt dessen können Sie auch ApplicationPoolIdentity verwenden, oder mittels Windows-Authentication den aufrufenden User impersonieren. Um dox42 Beispielvorlagen mit MS Access DB Zugriff (benötigt 32 Bit) generieren zu können müssen Sie ev. 32-Bit-Anwendungen aktivieren.
9. Wechseln Sie wieder im inetmgr zur Site > Berechtigungen verwalten und geben dem dox42 Service User oder der ApplicationPoolIdentity (User „IIS AppPool\dox42Server“ mit Suchpfad auf lokalen Rechner) Lese- und Schreibrechte auf C:\dox42Server und auf das Temp-Verzeichnis.
10. Konfigurieren Sie die web.config (key, license-dir, Mail-Server) und NLog.config (log-dir).
11. Freischalten des Ports nach außen auf der Firewall.
12. Test mit dox42 ServerTestClient. Diesen finden Sie unter C:\dox42ServerVXXXX\ dox42ServerTestClient_*.
13. Achten Sie auf adäquate Zugriffskontrolle auf Ihr dox42 Service um unberechtigten Zugriff zu verhindern.
14. Um AAD zu verwenden benötigen Sie ein HTTPS Zertifikat. Wenn Sie Hilfe in der Installation eines Zertifikats benötigen, sollte Ihnen dieses Video helfen: https://youtu.be/HHU46l6G2oc
www.dox42.com 24
Upgrade
Um eine neue Version zu installieren gehen Sie bitte wie folgt vor:
1. Machen Sie ein Backup Ihres dox42 Server Verzeichnisses, so können Sie im Problemfall zurücksteigen.
2. Löschen Sie alle Dateien im Bin Verzeichnis AUSSER Aspose.Total.lic und aller dll-Dateien, die zu Ihren Custom Data Sources und Output Actions gehören. Custom Data Sources und Output Actions sind in der web.config eingetragen, z.B.: dox42SAP, dox42AX, dox42DynamicCRM, etc. Bitte sehen Sie in der jeweiligen Dokumentation nach um die Liste der benötigten Dateien zu ermitteln.
3. Kopieren Sie alle Dateien vom Bin Verzeichnis des dox42 Server Pack in das Bin Verzeichnis Ihres dox42 Servers.
4. Kopieren Sie alle Dateien AUSSER dox42LIVE.config vom dox42LIVE Verzeichnis des dox42 Server Pack in das dox42LIVE Verzeichnis Ihres dox42 Servers.
5. Überprüfen Sie ob Dox42Service.asmx und dox42RestService.ashx im dox42 Server Verzeichnis vorhanden sind.
6. Überprüfen Sie Ihre web.config auf neue Einstellungsmöglichkeiten. 7. Starten Sie den dox42 Server im IIS neu. 8. Test mit dox42 ServerTestClient 9. Das war’s, viel Spaß ☺
Support
Für Supportanfragen wenden Sie sich bitte an [email protected]
Viel Erfolg mit Ihrem dox42 Server!