Page tree
Skip to end of metadata
Go to start of metadata

Introduction

CardDAV is an open Internet protocol (or standard) for syncing contacts. It’s built around the HTTP-based WebDAV protocol and uses vCard format for contact data. CardDAV is supported by many clients, such as Mac Contacts, The Bat, Android and others.

CardDAV templates addon provides blueprints for entering client and contact person details, a CardDAV servlet, a macro to download vCards from Confluence pages, and REST API for integration with 3-rd party applications.

As of version 1.0.4 CardDAV templates use Extra Placeholders to autocomplete the 'Phone Type', 'Email Type', 'Address Type', 'URL Type' and 'Country' fields. You might need to install Extra Placeholders addon prior to installing CardDAV Templates to get autocomplete option to work.

Blueprints

There are two blueprints packaged with this add-on:

  • Person default template
  • Organisation default template

These closely relate to Mac Contacts' person and company.


You may use the blueprints as they are, or implement your own templates. To do so you will probably need the Confluence Source Editor add-on. In order for your template to be recognised by CardDAV Templates plugin it should follow some markup guidelines:

Objects and attributes are defined via HTML classes, for example:

Error rendering macro 'code': Invalid value specified for parameter 'firstline'
<table class="wrapped">
    <colgroup>
        <col/>
        <col/>
    </colgroup>
    <tbody class="com-mesilat-object-person">
        <tr>
            <td>First Name</td>
            <td class="com-mesilat-attribute-first-name">
                <ac:placeholder>John</ac:placeholder>
            </td>
        </tr>
        ...
        <tr>
            <td>Phones</td>
            <td class="com-mesilat-attribute-phones">
                
                <table class="wrapped">
                    <colgroup> 
                        <col/> 
                        <col/> 
                    </colgroup>
                    <tbody>
                        <tr>
                            <th>Phone Type</th>
                            <th>Phone Number</th>
                        </tr>
                        <tr class="com-mesilat-object-phone">
                            <td class="com-mesilat-attribute-phone-type">
                                <ac:placeholder ac:type="carddav:phoneType">Start Typing...</ac:placeholder>
                            </td>
                            <td class="com-mesilat-attribute-phone-number">
                                <ac:placeholder>+99 999 999999999</ac:placeholder>
                            </td>
                        </tr>
                    </tbody>
                </table>
                <p>
                    <ac:structured-macro ac:name="carddav-addrow-macro" ac:schema-version="1"/>
                </p>
            </td>
        </tr>


Currently the following object tags are supported:

TagMeaning
com-mesilat-object-organizationOrganisation type
com-mesilat-object-personPerson type
com-mesilat-object-phonePhone number type
com-mesilat-object-emailEmail type
com-mesilat-object-addressPostal address type
com-mesilat-object-urlURL address type


The following attribute tags are supported:

TagMeaning
com-mesilat-attribute-nameFormatted name (is overridden by page title)
com-mesilat-attribute-first-nameFirst name
com-mesilat-attribute-last-nameLast name
com-mesilat-attribute-middle-nameMiddle name
com-mesilat-attribute-birth-dateDate of birth (YYYY/MM/DD)
com-mesilat-attribute-titleJob title
com-mesilat-attribute-organizationOrganisation
com-mesilat-attribute-roleRole, such as 'Decision Maker'
com-mesilat-attribute-phone-typeValid phone types: 'Work', 'Home', 'Mobile', 'Fax', 'Preferred', 'Non-standard', 'Other'
com-mesilat-attribute-phone-numberPhone number
com-mesilat-attribute-email-typeValid email type: 'Work', 'Home', 'Preferred', 'Non-standard', 'Other'
com-mesilat-attribute-email-addressEmail address
com-mesilat-attribute-address-typeValid address types: 'Work', 'Home', 'Postal', 'Parcel', 'Domestic', 'International', 'Preferred', 'Non-standard', 'Other'
com-mesilat-attribute-streetStreet Address
com-mesilat-attribute-regionRegion
com-mesilat-attribute-postal-codePostal code
com-mesilat-attribute-po-boxP.O. box
com-mesilat-attribute-localityCity or town
com-mesilat-attribute-countryCountry
com-mesilat-attribute-extendedExtra address details
com-mesilat-attribute-url-typeValid URL types: 'Work', 'Home', 'Preferred', 'Non-standard', 'Other'
com-mesilat-attribute-url-addressURL address

CardDAV Servlet

CardDAV servlet was tested with the following clients:

  • OSX Contacts
  • The Bat!

CardDAV server implemented by the servlet is readonly, which means that you cannot modify person or organisation details in Confluence from your CardDAV client.

You setup CardDAV with OSX Contacts as follows:


(info) Important notice to Apple Contact users: in later versions of Mac OSX the application will always start searching for contacts with address: http://<host name>/.well-known/carddav Your system administrator will have to setup this address for you. There are basically two options: reverse web proxy and Tomcat rewrite valve:

Reverse proxy

NGINX server configuration example (assumes that Confluence and NGINX are running on the same host and Confluence is using default development port 1990)

nginx.conf
...
http
{
 upstream confluence_dev
    {
        server localhost:1990;
    }
    ...
    server {
        listen       80 default_server;
        rewrite      ^/\.well-known/carddav$ http://localhost/confluence/plugins/servlet/carddav permanent;

        location / {
            root   html;
            index  index.html index.htm;
        }

        location /confluence
        {
            proxy_pass	     http://confluence_dev;
            proxy_set_header Host $host;
            proxy_set_header X-Forwarded-For $remote_addr;
            proxy_redirect   off;
        }
    ...
}
...

Of course, exact settings must match your environment.

Tomcat valve

For more details please refer to Tomcat Rewrite Valve page. The following configuration worked for me (I use Tomcat 9):

{TOMCAT_HOME}/conf/server.xml
      ...
      <Host name="localhost"  appBase="webapps"
            unpackWARs="true" autoDeploy="true">
        <Valve className="org.apache.catalina.valves.rewrite.RewriteValve" />
        ...
      </Host>
    </Engine>
  </Service>
</Server>
{TOMCAT_HOME}/conf/Catalina/localhost/rewrite.config
RewriteRule ^/\.well\-known/carddav /confluence/plugins/servlet/carddav [R=301] 


vCard Macro

You can use vCard Macro to download vCard data directly from the Confluence page. This can be useful if your email client does not support CardDAV.

REST API

EndpointDetailsExample
{CONFLUENCE_BASE}/rest/carddav-templates/1.0/data/page/pageIdReturns JSON array with person/organisation details on page
[ {
  "_type_" : "organization",
  "organization" : "Greenpeace UK",
  "phones" : {
    "_type_" : "phone",
    "phone-type" : "Work",
    "phone-number" : "+44 207 865 8100"
  },
  "emails" : {
    "_type_" : "email",
    "email-type" : "Work",
    "email-address" : "[email protected]"
  },
  "addresses" : {
    "_type_" : "address",
    "address-type" : "Work",
    "postal-code" : "N1 2PN",
    "street" : "Canonbury Villas",
    "locality" : "London",
    "region" : "",
    "country" : "UK",
    "po-box" : "",
    "extended" : ""
  },
  "urls" : {
    "_type_" : "url",
    "url-type" : "Work",
    "url-address" : "http://www.greenpeace.org.uk/"
  }
} ]
{CONFLUENCE_BASE}/rest/carddav-templates/1.0/data/allReturns JSON array with person/organisation statuses on Confluence. 'A' stands for active pages; 'D' means the page was deleted
[ {
  "id" : "1966089_0",
  "page-id" : 1966089,
  "etag" : 1498800994010,
  "status" : "D"
}, {
  "id" : "917508_0",
  "page-id" : 917508,
  "etag" : 1498896487592,
  "status" : "A"
}, {
  "id" : "1966082_0",
  "page-id" : 1966082,
  "etag" : 1498939502391,
  "status" : "A"
}, {
  "id" : "2162695_0",
  "page-id" : 2162695,
  "etag" : 1499002727976,
  "status" : "A"
} ] 

Hope you find it useful.

Your Rating: Results: PatheticBadOKGoodOutstanding! 16 rates

Source code for the addon is available on GitHub. To report a bug please use the Issue Tracker

  • No labels