Problembeschreibung

Bei der Entwicklung von mehreren Plugins kann es vorkommen, dass Texte mehrfach übersetzt werden müssen, wodurch somit Redundanzen entstehen. Der Ursprung liegt dann bei Atlassian Confluence, welches das Sharen von i18n-keys über die verschiedenen Plugins hinweg nicht ermöglicht.

Problemlösung

Damit Redundanzen beseitigt werden können, müssen die i18n-keys zentral abgelegt werden. Dazu kann man einen bestimmten Plugintyp von Confluence – das Sprachplugin – nutzen.

Diese Erkenntnis ist wichtig, da für die Lösung des oben genannten Problems, es notwendig ist, die Standard Sprachplugins von Confluence zu deinstallieren und die darin enthaltenen property Dateien in das neue SprachPlugin zu überführen.

Außerdem muss die atlassian-plugin.xml des Sprachplugins, wie folgt angepasst werden.

<language name="German" key="de_DE" language="de" country="DE">

   <resource name="de_DE.png" type="download"
      location="templates/languages/de_DE/de_DE.png">
      <property key="content-type" value="image/png"/>
   </resource>
 </language>

<language name="Spain" key="es_ES" language="es" country="ES">
   <resource name="es_ES.png" type="download"
       location="templates/languages/es_ES/es_ES.png">

       <property key="content-type" value="image/png"/>
   </resource>
</language>

<resource name="i18n" name="i18n_my_plugin" type="i18n" location="/my_plugin"/>

<!-- Important entry, because you have to add the default
          i18n files to this new plugin -->

<resource name="i18n" name="i18n_default" type="i18n"
     location="/ConfluenceActionSupport"/>

Vielseitige Lösung

Diese Lösungsansatz beseitigt nicht nur Redundanzen, sondern bietet auch in Kombination mit Maven, eine Möglichkeit mehrere Varianten einer Pluginlösung textuell abzugrenzen.

Für diesen Fall kann man mittels Maven tricksen. Wichtig hierbei ist eine eindeutige Namenskonvention für die Unterteilung der properties vorzunehmen. Beispielsweise kann man die properties wie folgt namentlich abgrenzen:

• my_plugin.properties
• my_plugin_typex.properties
• my_plugin_typey.properties
• my_plugin_de_DE.properties
• my_plugin_typex_de_DE.properties
• my_plugin_typey_de_DE.properties

Ist das geschehen, definiert man in der atlassian-plugin.xml des LanguagePool-Plugins folgende Zeilen:

<resource name="i18n" name="i18n_my_plugin_general" type="i18n"
     location="/my_plugin"/>

<resource name="i18n" name="i18n_my_plugin_specific" type="i18n"
     location="/my_plugin_${TYPE}"/>

Letztlich müssen im Eclipse zwei neue Maven Run-Configurations erstellt werden, die das entsprechende Goal (Bsp.: package, install oder atlassian-pdk:install) verwendet und im Environment-Tab die Variable TYPE auf typex oder auf typey setzt.

Das Berechtigungskonzept von Confluence ist in der Confluence Doku verteilt auf mehrere Seiten. Da wir in letzter Zeit immer wieder Antworten auf Berechtigungsfragen liefern mussten, habe ich eine Zusammenfassung geschrieben, die die wichtigsten Eckpunkte aufnimmt und Confluence Eigenheiten aufdeckt. 

Los gehts

Confluence Berechtigungskonzept besteht aus drei verschiedenen Stufe. Diese sind Globale Berechtigung, Bereichsberechtigungen und Seitenberechtigungen. 

Berechtigungsebenen

Globale Berechtigungen

Liste der globalen Berechtigungen:

System Administrator

Die Rolle des System Administrators ist die mächtigste, durch sie hat der Nutzer uneingeschränkte Befugnisse bei der Verwaltung von Confluence. (u.a. Zugriff auf die Administrationskonsole) 

Confluence Administrator

Nutzer, die diese Rolle besitzen, haben die meisten Befugnisse, die auch der System  Administrator hat, inne. Die wenigen, die er nicht hat werden in der folgenden Liste zusammengetragen.

Das Setzen des Confluence-Administrator oder des System-Administrator Rechts für einen Nutzer gibt den Nutzern nicht automatisch Zugriff auf alle Seiten und Bereiche, sondern erlaubt Zugriff auf die Administrator Konsole. 

Bereichsberechtigung

Bereichsberechtigungen können nur durch einen Bereichsadministrator vergeben werden. Ein Nutzer ist ein Bereichsadministrator, wenn er für den Bereich das Recht “Admin” innehat. 

Jeder Bereich besitzt seinen eigenen unabhängigen Rechtesatz. Dieser besteht aus den folgenden Rechten:

Seitenberechtigung

Um Seiten beschränken zu können, muss dem Nutzer das Recht “Seiten beschränken” über die Bereichsadministration zugeordnet sein. 

Nutzer und Gruppen

Confluence besitzt von grundauf 2 Gruppen:
confluence-administrators
confluence-users

Zusätzlich unterscheidet Confluence noch nicht-eingeloggte Nutzer als Anonymous, im Rechtemanagement ist es möglich für diese spezielle Gruppe von Nutzern Rechte zu definieren. 

confluence-administrators

User dieser Gruppe haben Zugriff auf die Administrator Console und können systemweit administrieren.
Mitglieder dieser Gruppe können auch alle Seiten und Bereiche der betroffenen Confluence Instanz einsehen. Allerdings  keine Seiten, die durch Seitenzugriffsbeschränken die Ansicht für diese Gruppe verbieten. Mitglieder der confluence-administrators-Gruppe können allerdings über den Space-Adminbereich die Einschränkungen wieder entfernen. 

Berechtigungen im Einsatz

Überlappende Berechtigungen auf einer Ebene

Gehört ein Nutzer zu mehreren Gruppen oder/und hat zusätzlich Nutzerspezifische Rechte so addieren sich diese.
Sie sind quasi OR (additiv) verknüpft.

Ist ein Nutzer also Mitglied von 2 Gruppen (gruppe1 und gruppe2):

So besitzt der Nutzer alle 3 Rechte. 

Bereichs- vs. Seitenberechtigungen

Mittels der Seitenberechtigung kann man die eingestellten Bereichsberechtigungen nochmals auf Seitenebene eingrenzen. 

Beispiel: (zur Vereinfachung nur mit Gruppe. Gilt allerdings ebenso mit Nutzern) 

Bereichsberechtigung für Bereich X:

Seitenberechtigung für Seite Y im Bereich X:

Jeder Nutzer der gruppe2 kann auf die Seite Y im Bereich X zugreifen. Die gruppe1 hat keine Möglichkeit den Inhalt der Seite angezeigt zu bekommen. 

Rechtevererbung von Seiten

Mit einem Webinar (Registrieren) in der Reihe “Plugin of the Month” von Atlassian veröffentlichen wir am 18.2.2010 das Content Import Plugin 1.1.
Das Plugin unterstützt den Import verschiedenster Inhalte nach Confluence. Die Daten müssen in einem Austauschformat, das Confluence Datenstrukturen in XML abbildet, zur Verfügung gestellt werden. Das Austauschformat unterstützt fast alle Inhaltstypen von Confluence (Bereiche, Seiten, Blogeinträge, Kommentare und Anhänge) sowie die zugehörigen Metadaten (Ersteller, Bearbeiter, Schlagworte, Datum). So können ohne vertiefte Confluence Kenntnisse Daten aus verschiedensten Quellsystemen, wie Wikisystemen, Blogs, Foren, nach Confluence importiert werden. Weiterhin bietet Communardo einen Migrationsservice an, der den kompletten Export der Daten aus dem Quellsystem nach XML und den anschließenden Import umfasst.

Migration von Daten nach Confluence mit dem Content Import Plugin

Im Webinar (Registrieren) demonstrieren wir das Plugin, weitere Informationen stehen nach dem Release auch auf der Communardo Homepage und im Atlassian Plugin Exchange zur Verfügung.

Im Rahmen eines Webinars habe ich die aktuelle Version von Confluence vorgestellt und neue Funktionalitäten demonstriert und kommentiert: [vimeo]http://www.vimeo.com/8602746[/vimeo]

Interessant sind vor allem das Drag & Drop von Anhängen, die Unterstützung von Office 2007 und dem IE 8, die neugestalteten Dialoge und die Einführung von Gadgets. Damit ist 3.1 eine Confluence-Version, für die sich ein Update – wie eigentlich immer bei neuen Releases der Atlassian Produkte – lohnt.

In folgenden Blogposts werde ich dann wieder kleine, interessante Features, die wenig dokumentiert sind und die man erst in der täglichen Arbeit entdeckt, vorstellen.

Auch bei der Pluginentwicklung für Confluence kommt irgendwann der Zeitpunkt, an dem man sich mit komplexeren Abläufen bei der Persistierung von Daten beschäftigen muss. Um die Integrität dieser Daten sicherstellen zu können, ist man dann auf den Einsatz von Transactions angewiesen. Da Confluence das Spring Framework verwendet, bietet sich hierfür die Nutzung des TransactionTemplate an. Dieses ermöglicht es, wie in der Spring Dokumentation beschrieben, auf einfache Weise kritischen Code unter Verwendung eines Callbacks in eine Transaction zu verpacken. Dazu benötigt man jedoch noch einen PlatformTransactionManager. Dieser implementiert die Strategie für die Transaktionsbehandlung, die im Fall von Confluence auf Hibernate basiert. Auch hierzu können weitere Informationen und ein Codebeispiel auf den Seiten von Spring gefunden werden. Der PlatformTransactionManager ist als Bean im Application Context von Confluence vorhanden und kann über den ComponentContainer referenziert werden:

public PlatformTransactionManager getTransactionManager(){
    return (PlatformTransactionManager) ComponentContainer.get("transactionManager");
}

Allerdings funktioniert dieses Codebeispiel nach einer Umstellung auf V2-Plugins nicht mehr. Der Grund: Da diese Plugins in OSGI-Bundles umgewandelt werden, welche eine andere Spring Version verwenden als die Kern-Applikation, kommt es bei der Referenzierung der transactionManager-Bean über den ComponentContainer zu einer ClassCastException.

Bei der Suche nach einer Lösung für dieses Problem bin ich über ein Ticket im Issue Tracker von Atlassian gestolpert, in dessen Kommentaren eine Alternative beschrieben wird: Abhilfe schafft die Verwendung der Shared Access Layer (SAL), einer einheitlichen Service-Schicht für alle Atlassian Anwendungen. Sie stellt neben verschieden anderen Services auch ein TransactionTemplate bereit, das für Confluence bereits den auf Hibernate basierenden PlatformTransactionManager gesetzt hat und auf folgende Weise referenziert werden kann.

Zunächst muss das Template als Komponente (Spring-Bean) im Plugin-Descriptor (atlassian-plugin.xml) importiert werden:

<component-import name="SAL Transaction Template" key="salTransactionTemplate">
    <interface>com.atlassian.sal.api.transaction.TransactionTemplate</interface>
</component-import>

Dann kann man sich die Komponente per Spring Autowiring in fast alle Plugin Modultypen (z. B. Actions und Components ) injizieren lassen. Der Name der zu injizierenden Bean entspricht dem Key des component-import Elementes im Plugin-Descriptor (in diesem Beispiel also “salTransactionTemplate” ):

public void setSalTransactionTemplate(TransactionTemplate template){
    this.transactionTemplate = template;
}

Nun kann das Template wie  oben beschrieben verwendet werden.

Noch ein Hinweis: SAL wird erst ab Confluence 3.0 mit ausgeliefert. Für Confluence 2.10 muss man also eine andere Lösung finden.

<

Motivation

Es gibt eine Vielzahl an Situationen, bei den man spezifische Properties verwendet. Generelle und fast überall aufzufindende Beispiele wären die Konfiguration des Logs und der Datenbank. Für diese speziellen Ressourcen existieren zumeist spezielle Dateien, die beim Start des Servers durch individuelle Klassen/Mechanismen ausgelesen werden.

Die Frage, die zu diesem Artikel geführt hat, befasst sich mit dem Thema:

Wie können anwendungsspezfische Properties für Confluence relativ einfach und leicht wartbar hinterlegt werden?

Gemeint sind hierbei Properties, die als Schalter zwischen Modi innerhalb einer Software dienen oder die zusätzliche Konfigurationen ermöglichen.

Möglichkeiten

JVM – Parameter (Der klassische Weg.)

Dieser Weg ist für Java Anwendungen allgemeingültig und somit für die meisten Programmierer nicht neu. Als JVM – Parameter (JAVA_OPTS) wird mit dem Präfix -D und dem anschließenden Property-Wertepaar (<property_name>=<property_value>) die Property definiert. In der Anwendung selbst kann dann mit System.getProperty(“<propety_name>”) darauf zugegriffen werden. Als Rückgabewert liefert die Methode  immer ein String, den man ggf. explizit casten muss.

confluence.cfg.xml (Der elegantere Weg.)

Atlassian Confluence nutzt eine zentrale Datei (confluence.cfg.xml) in der Properties definiert werden können. Diese Datei  befindet sich im data Verzeichnis.

Wie die Extension vermuten lässt, handelt es sich hierbei um eine XML Datei. Die Definition der einzelnen Properties erfolgt wie folgt:

 <confluence-configuration>
  <setupStep>complete</setupStep>
  <setupType>custom</setupType>
  <buildNumber>1517</buildNumber>
  <properties>
    <property name="attachments.dir">${confluenceHome}\attachments</property>
    ...
    <property name="this.is.an.example">true</property>
  </properties>
 </confluence-configuration>

In diesesm Ausschnitt habe ich eine neue Property mit Namen “this.is.an.example” mit dem Wert true angelegt. (rot gekenntzeichnet) Um nun in Quellcode diesen Wert auslesen zu können muss die Serviceklasse BootstrapManagers verwendet werden.

Eine Variante dafür wäre die getProperty() Methode zu nutzen.

 BootstrapManager bootstrapManager = BootstrapUtils.getBootstrapManager();
 Object objectVal = bootstrapManager.getProperty("this.is.an.example");
 // here comes the explicit cast
 boolean booleanVal = ((Boolean) objectVal).booleanValue();

Möglich wäre auch die getString() Methode zu wählen.

 BootstrapManager bootstrapManager = BootstrapUtils.getBootstrapManager();
 String stringVal = bootstrapManager.getString("this.is.an.example");
 boolean booleanVal = Boolean.valueOf(stringVal);

Die kürzeste Variante allerdings ist die Methode isPropertyTrue() zu verwenden. Die kann folgendermaßen aussehen:

 BootstrapManager bootstrapManager = BootstrapUtils.getBootstrapManager();
 boolean booleanVal = bootstrapManager.isPropertyTrue("this.is.an.example");

Fazit

Meiner Meinung nach steigt durch die Nutzung der confluence.cfg.xml die Übersicht. Da zum einen die Daten lesbar (XML) abgelegt und zudem zentral an einer Stelle konfiguriert werden. Ein weiterer Vorteil gegenüber den JVM Parametern ist,  dass der Betrieb, der die Wartung der Skripte und der Anwendung auf dem Server vornimmt, keine Konfigurationen vergessen bzw. überschreiben kann. Letztlich ermöglichen solche gebündelten Konfigurationen in einer einzigen Datei, dass sie relativ unproblematisch für bestimmte Anwendungsfälle/Instanzen ausgetauscht werden können.

Am 29.10.2009 war Martin Koser [Blog] [Twitter], einer der bekanntesten Wiki-Evangelisten und Social Media Berater in Deutschland, zu Gast beim Confluence Community Day in Frankfurt. In seinem Vortrag ging er der Frage nach, auf welche Weise der Einsatz von Wiki-Plattformen in Unternehmen zum Erfolg geführt werden kann. In Anlehnung an die Design Patterns von Christopher Alexander, einem Architekten, sind Wikipatterns entwickelt worden, die Strewart Mader in seinem Buch “Wikipatterns” beschrieben hat. Diese Muster sind eine gute Quelle, um mehr über erfolgreiche Einführungskonzepte, aber auch Barrieren zu erfahren. Planmäßiges Vorgehen ist bei der Einführung von Wikis ganz zentral. Die organisatorische und strategische Einbettung vorab darf nicht vergessen werden. Die Arbeit am Wiki endet eigentlich nie. Eine kontinuierliche Anpassung an aktuelle Gegebenheiten muss immer wieder erfolgen. Das ist auch eine Aufgaben für den Wiki-Gärtner. “Leere Wikis fliegen nicht”. Es braucht Grundstrukturen, die initial geschaffen werden müssen. Auch Schulungen, zumindest kurz und pragmatisch, sind wichtig. Bewährt haben sich vor allem “Train-the-trainer” Modelle und Coaching-Ansätze, um die für Wikis Verantwortlichen voranzubringen.

Die Präsenation von Martin Koser ist auf Slideshare verfügbar.

Ein Blogbeitrag zum Vortrag und zum Confluence Communitiy Day hat Martin in seinem frogpond Blog veröffentlicht. Herzlichen Dank an Martin Koser für seine Vortrag und den Bericht zur Veranstaltung!

In ihrem Vortrag auf dem Confluence Community Day am 29.10.09 in Frankfurt hat Gudrun Lahm von der VBH Holding die Wissensdatenbank Ihres Unternehmens vorgestellt. VBH ist ein baden-württembergisches Mittelstandsunternehmen, welches mit all dem handelt, was für den Einbau von Fenstern und Türen benötigt wird. Als Experte unter den Anbietern ist es für VBH von großer Bedeutung, zu den Produkten einen umfangreichen Service anzubieten. Dazu gehört auch die Vermittlung von Wissen zur Verwendung dieser Produkte. Ein Bestandteil dieser Strategie ist die VBH Wissensdatenbank.

Diese Wissensdatenbank dient also nicht nur den Mitarbeitern bei VBH, sondern insbesondere auch den Kunden und Lieferanten. Die auf Atlassian Confluence basierende Wissensdatenbank hat bei VBH das bisher genutzte Diskussionsforum abgelöst. Neben dem Bereich “Rat+Tat” wurde auch ein Begriffslexikon mit 11.000 Artikeln integriert.

Das System ist inzwischen seit mehr als 6 Monaten im Einsatz und bietet Kunden und Lieferanten einen Mehrwert durch umfangreichere und aktuellere Informationen rund um die angebotenten Produkte. Aber auch die Mitarbeiter im Unternehmen nutzen die Wissensdatenbank aktiv.

Inhalte werden von Mitarbeitern des Hauses kooperativ erstellt. Die Freigabe von Inhalten, die extern verfügbar gemacht werden sollen, erfolgt jedoch weiterhin zentral. Insbesondere der Bereich “Rat+Tat” soll aufgrund guter Akzeptanz noch weiter ausgebaut werden. Die leistungsstarke Suche von Confluence hilft gerade auch den Kunden aus dem Handwerksbereich, schnell an wichtige Informationen zu gelangen. Auf Basis der Inhalte der Wissensdatenbank wird regelmäßig ein aktueller Newsletter für die Kunden erstellt und versandt. Um die zunehmende Verbreitung mobiler Endgeräte zu nutzen, wird untersucht, auf welche Weise ein mobile Zugriff auf die Wissensdatenbank erfolgen soll.

Wir bedanken uns bei Frau Lahm für den interessanten Vortrag und wünschen weiter viel Erfolg mit der VBH Wissensdatenbank.

Dies ist eine Mitschrift zur Session “OpenSocial in the Enterprise” auf der Enterprise 2.0 Conference in San Francisco.

Im Panel vertreten waren vor allem Vertreter von Google, Atlassian, SocialText, IBM und eXo. OpenSocial ist eine Entwicklung die von Google nun als Open Source verfügbar gemacht worden ist. Die ursprüngliche Ausrichtung war auf das Umfeld von Social Networking ausgerichtet.

Die Technologie hat sich in den letzten beiden Jahren stark weiterentwickelt, liegt nun als Version 0.9 vor und geht nun auf die Version 1.0 zu. Inzwischen nutzen Dienste mit in Summe von mehr als 800 Mio. Nutzern die OpenSocial Technologie. Inzwischen wird viel über den Unternehmenseinsatz diskutiert. Google wird in Kürze ein “Enterprise OpenSocial Whitepaper” veröffentlichen.

Nachfolgend die Zusammenfassung der Diskussion im Panel.

IBM ist an den OpenSocial Entwicklungen beteiligt. Hervorzuheben ist der Lotus Mashup Maker. IBM hat auch ein eingenes iWidget Protocol entwickelt. IBM sieht OpenSocial vor allem nützlich für Dashboards. Dies wird bei IBM vor allem über die JAZZ Foundation vorangetrieben. IBM sieht Verbesserungsbedarf für OpenSocial, vor allem im Bereich Stabilität, Interoperabilität zu iWidgets, OpenAjax und Dojo.

Apache SocialSite ist ein Social Networking Service, der ursprünglich von Sun entwickelt worden ist. Mit SocialSite kann man Social Networking features auf Basis von Gadgets in bestehende Websites integrieren kann.

Atlassian bietet OpenSocial Unterstützung in seine Produkten Jira und Confluence. Dabei geht es in der Regel um die Zusammenarbeit von Mitarbeitern, z.B. im Softwareentwicklungsprozess. Mit OpenSocial kann man in Jira und Confluence nun eine standard-basierte Applikationsintegration vornehmen, z.B. um Dashboards zu erstellen, Statusupdates zu integrieren. Hinweis: Communardo ist Atlassian Partner.

GateIn verbindet JBoss Portal Technologien mit OpenSocial. GateIn ist quasi eine OpenSocial Bridge, um OpenSocial Gadgets als JSR-168 Portlet in ein JBoss Portal integrieren zu können.

SocialText bietet eine Wiki und Collaboration Suite als Online-Service und Appliance. SocialText unterstützt OpenSocial für den Aufbau von Dashboards und für die Integration mit anderen Applikationen, z.B. mit einem CRM-System. Die Vertreterin von Socialtext sieht Ensatzaspekte von OpenSocial vor allem im Bereich oAuth (Authentifikation gg. externe Internetdienste), Aufbau von Kontaktnetzwerken, Aufsüren von Inhalten und Personen in externen Diensten, Austausch von Profildaten zwischen internen und externen Diensten, z.B. LinkedIn.

Die Teilnehmer am Panel sehen eine viel reichhaltigere Community für OpenSocial Gadgets als z.B. im Bereich der Java-basierten Portlets. Als Grund dafür wird die wesentlich einfachere Javascript-basierte Entwicklung von OpenSocial Gadgets angesehen. Für OpenSocial gibt es auch eine REST-basierte API.

Michael Hummel, Geschäftsführer der empulse GmbH, stellte in seinem Vortrag beim Confluence Community Day vor, wie man mit Hilfe von Confluence ein Software-Handbuch realisieren kann. Die Vortragsfolien können bei Slideshare gefunden werden:

Die von Herrn Hummel präsentierte Lösung ersetzt das gedruckte Handbuch einer Software für Reiseunternehmen. Dieses litt an geringer Akzeptanz bei den Kunden, die somit auch für triviale Fragen den in der Folge überlasteten Support in Anspruch nahmen.

Aus dieser Ausgangssituation leiteten sich die Anforderungen an ein neues Handbuch ab: Die Akzeptanz bei den Kunden sollte gesteigert und somit der Support entlastet werden. Außerdem sollten die Kosten für den Druck des Handbuches gesenkt, sowie die Entwickler der Software von den aufwendigen Reviews des Handbuches für jedes neue Release befreit werden.

Diese Anforderungen wurden mittels Atlassian Confluence realisiert. Dazu wurde das Confluence Wiki von emplse erweitert und ein spezielles Inhaltskonzept entwickelt. Durch eine entsprechende Strukturierung des Inhaltes in Bereiche und  Seitenhierarchien konnten die Formularstruktur der Software sowie Mehrsprachigkeit und kundenspezifische Inhalte (z. B. Arbeitsanweisungen) auf das Wiki abgebildet werden. Ein weiterer Vorteil ergibt sich für die Kunden in der direkten Integration der Hilfe in die Software, die mittels eines von empulse entwickelten Webservice auch nach verwandten Hilfethemen zu einem Formularelement sucht. Dazu wird zu jedem Formularelement in der Software eine Seite im Wiki gepflegt, die sich bei Aufruf der Hilfe im Webbrowser öffnet. Des Weiteren profitieren Support und Kunden von der kollaborativen Idee eines Wikis: Supportmitarbeiter können, anfangs geführt durch einen Moderator, selbstständig Änderungen an unklaren Formulierungen in der Hilfe vornehmen. Die Hinweise dazu können Kunden durch Verwendung der Kommentarfunktion in Confluence geben. Dies führt zu einer ständigen Verbesserung des Handbuches.

Weitere Informationen zum Projekt können auch im Blog von empulse gefunden werden.