Klokwork Team Connnector
Synchronize the client, project and tasks across your entire organization. Allow users to submit timesheet data to a centralized location. This connector is free when you buy a Klok license.
Features
Download Now
Klokwork Team Connector Plugin (12290 downloads )
Requires Klok 2.3.7 or higher
Note: Do not unzip the file. You will install it as a complete package.
Synchronize Projects
Using the Klokwork Team Connector gives Klok the ability to synchronize the project tree with a file located on your network or a URL which should return the appropriate XML data. The format of the XML should be as shown below.
When configured to use a URL instead of a file, the request for projects is made as a GET request to the configured URL. The username and password are passed as a Base64 encoded string in the Authorization header. This allows you to return unique projects to each individual user if so desired.
Sample XML
<klok>
<projects>
<project name="Sample Client" color="10092288" billable="false" estimate="0" rate="-1" tags="" description="" code="123" remoteId="1" contactName="" contactEmail="" contactPhone="">
<project name="Print Ad/Poster" color="10092288" billable="true" estimate="0" rate="-1" tags="" description="" code="123.1" remoteId="2" contactName="" contactEmail="" contactPhone="">
<project name="Copywriting" color="10092288" billable="false" estimate="0" rate="0" tags="" description="" code="123.1.1" remoteId="3" contactName="" contactEmail="" contactPhone=""/>
<project name="Design" color="10092288" billable="false" estimate="0" rate="0" tags="" description="" code="123.1.2" remoteId="4" contactName="" contactEmail="" contactPhone=""/>
<project name="Project Management" color="10092288" billable="false" estimate="0" rate="0" tags="" description="" code="123.1.3" remoteId="5" contactName="" contactEmail="" contactPhone=""/>
</project>
</project>
<project name="Sample Client 2" color="10092288" billable="false" estimate="0" rate="-1" tags="" description="" code="456" remoteId="6" contactName="" contactEmail="" contactPhone="">
<project name="Website Site" color="10092288" billable="true" estimate="0" rate="-1" tags="" description="" code="456.1" remoteId="7" contactName="" contactEmail="" contactPhone="">
<project name="Copywriting" color="10092288" billable="false" estimate="0" rate="0" tags="" description="" code="456.1.1" remoteId="8" contactName="" contactEmail="" contactPhone=""/>
<project name="Design" color="10092288" billable="false" estimate="0" rate="0" tags="" description="" code="456.1.2" remoteId="9" contactName="" contactEmail="" contactPhone=""/>
<project name="Project Management" color="10092288" billable="false" estimate="0" rate="0" tags="" description="" code="456.1.3" remoteId="10" contactName="" contactEmail="" contactPhone=""/>
</project>
</project>
<project name="Sample Client 3" color="10092288" billable="false" estimate="0" rate="-1" tags="" description="" code="789" remoteId="11" contactName="" contactEmail="" contactPhone="">
<project name="Project 1" color="10092288" billable="true" estimate="0" rate="-1" tags="" description="" code="789.1" remoteId="12" contactName="" contactEmail="" contactPhone="">
<project name="Admin" color="10092288" billable="false" estimate="0" rate="0" tags="" description="" code="789.1.1" remoteId="13" contactName="" contactEmail="" contactPhone=""/>
<project name="Business Development" color="10092288" billable="false" estimate="0" rate="0" tags="" description="" code="789.1.2" remoteId="14" contactName="" contactEmail="" contactPhone=""/>
<project name="Project Management" color="10092288" billable="false" estimate="0" rate="0" tags="" description="" code="789.1.3" remoteId="15" contactName="" contactEmail="" contactPhone=""/>
<project name="R & D" color="10092288" billable="false" estimate="0" rate="0" tags="" description="" code="789.1.4" remoteId="16" contactName="" contactEmail="" contactPhone=""/>
<project name="Vacation" color="10092288" billable="false" estimate="0" rate="0" tags="" description="" code="789.1.5" remoteId="17" contactName="" contactEmail="" contactPhone=""/>
</project>
<project name="Product 1" color="10092288" billable="true" estimate="0" rate="-1" tags="" description="This is a test project" code="789.2" remoteId="18" contactName="" contactEmail="" contactPhone="">
<project name="Sprint Planning" color="10092288" billable="false" estimate="0" rate="0" tags="" description="" code="789.2.1" remoteId="19" contactName="" contactEmail="" contactPhone=""/>
<project name="Project Management" color="10092288" billable="false" estimate="0" rate="0" tags="" description="" code="789.2.2" remoteId="20" contactName="" contactEmail="" contactPhone=""/>
<project name="UI Design" color="10092288" billable="false" estimate="0" rate="0" tags="" description="" code="789.2.3" remoteId="21" contactName="" contactEmail="" contactPhone=""/>
</project>
</project>
</projects>
</klok>If you are implementing your own back end, you will need to return the correct type of response from your server. For any request, your should return with an HTTP 200 but the body of the response would differ depending on if the request was successful or not
Sample Success Response
<klok>
<result>
<success>true</success>
</result>
</klok>There may be times when you need to return an error response. In this case, you can use the format below.
Sample Error Response
<klok>
<result>
<error code="403">
<message title="Authentication Error">Your username or password was incorrect</message>
<details>Authentication Error</details>
</error>
</result>
</klok>Submit Timesheet Data
In a similar fashion as synchronizing projects, users can upload their timesheet data to a remote file location or a URL. The user can select a date range to submit and each day in the range will be submitted as a separate XML file names in the form of YYYY-MM-DD.xml. The format of the XML is shown below.
When configured to use a URL instead of a file, the submission of timesheet data is made as a POST to the configured URL for each day in the selected range. The username and password are passed as a Base64 encoded string in the Authorization header. This will allow you to store the data appropriately.
Sample XML
<day date="2010-06-14" deviceId="laptop">
<entries>
<entry>
<local_id>8</local_id>
<comment/>
<started_at>7:16AM</started_at>
<ended_at>11:55AM</ended_at>
<date>2010-06-14</date>
<project_local_id>13</project_local_id>
<tags/>
</entry>
</entries>
<projects>
<project>
<local_id>13</local_id>
<remoteId>3</remoteId>
<name>Copywriting</name>
<extended_name>Sample Client 1 > Print Ad/Poster > Copywriting</extended_name>
<code/>
<contact_email/>
<contact_name/>
<contact_phone/>
<description/>
<rate_or_parent_rate>0</rate_or_parent_rate>
<tags/>
</project>
</projects>
</day>Integrate with Existing Systems
Because the Klokwork Team Connector works with files and URLs, there are many possible options for integrating with existing systems.
For example, you can write a program to read the files and display reports, create invoices, etc. If you don’t have developers to write this kind of program, consider Klokwork Team Console which offers some of this functionality out of the box or contact us and we may be able to develop custom functionality for you.
If you have an existing time-tracking system then it may be possible to have Klokwork Team Connector talk directly to your system. Whether PHP, Java, .Net or Coldfusion, you can make calls to your system by exposing a page or service that can accept the calls make by the connector. If you need help with this, let us know and we can help you out.
Installation
To start, download the plugin from the menu to the right. To install the plugin, click on the “Tools” menu at the top of the screen and select the “Preferences” option. On the preferences screen, select the “Plugins” option. Click the “Install connector plugin…” and select the downloaded plugin file and click OK. Once the plugin is installed it will be shown on the “Plugins” screen.
Once installed, you must configure the connector for your environment. To open the connector configuration, click the area at the bottom left corner of the screen which will either say “Offline” or “Connected”. The connector panel will open where you will see a “Connector Configuration” link. Click it to view the connector configuration panel. Select whether you want to use Network Path mode or URL mode by selecting the appropriate radio button. Everyone in your organization will use the same mode and path/url. If you are not sure which mode to select, start with Network File Mode.
You may optionally choose to include a device identifier in your configuration. This value will be passed along with the generated data when you submit your time. This may be used by external systems, such as the Klokwork Team Console, to allow time to be submitted from more than one computer or device.
You may also specify whether colors specified within the downloaded projects should overwrite your local colors or not.
Network File Location Configuration
In the Network Path field, enter the network location where the files will be stored. The path should point to the root network folder set up by for your organization. This folder will contain the Projects.xml file and a folder for each user (see the figure to the right). Each user’s folder should be named uniquely. The name of their folder will become their username. This folder should be set up by your network administrator such that every user of Klok has read access to the Projects.xml file and write access to their own user folder. The connector also supports user specific Projects.xml files. If a Projects.xml file exists in the user’s directory it will be loaded. If not, it will fall back to the global one.
URL Configuration
In the URL field, enter the url which Klok will communicate with to retrieve projects and submit timesheet data. You may configure separate urls for upload and download. The username and password fields should contain the credentials that your server will use to authenticate the request. These credentials will be passed as a Base64 encoded string in the Authorization header. The same credentials will be passed to both the upload and download URLs.
Regardless of which method you choose, the projects data must be returned to Klok in the following format
<klok>
<projects>
<project name="Sample Client" color="10092288" billable="false" estimate="0" rate="-1" tags="" description="" code="123" remoteId="1" contactName="" contactEmail="" contactPhone="">
<project name="Print Ad/Poster" color="10092288" billable="true" estimate="0" rate="-1" tags="" description="" code="123.1" remoteId="2" contactName="" contactEmail="" contactPhone="">
<project name="Copywriting" color="10092288" billable="false" estimate="0" rate="0" tags="" description="" code="123.1.1" remoteId="3" contactName="" contactEmail="" contactPhone=""/>
<project name="Design" color="10092288" billable="false" estimate="0" rate="0" tags="" description="" code="123.1.2" remoteId="4" contactName="" contactEmail="" contactPhone=""/>
<project name="Project Management" color="10092288" billable="false" estimate="0" rate="0" tags="" description="" code="123.1.3" remoteId="5" contactName="" contactEmail="" contactPhone=""/>
</project>
</project>
<project name="Sample Client 2" color="10092288" billable="false" estimate="0" rate="-1" tags="" description="" code="456" remoteId="6" contactName="" contactEmail="" contactPhone="">
<project name="Website Site" color="10092288" billable="true" estimate="0" rate="-1" tags="" description="" code="456.1" remoteId="7" contactName="" contactEmail="" contactPhone="">
<project name="Copywriting" color="10092288" billable="false" estimate="0" rate="0" tags="" description="" code="456.1.1" remoteId="8" contactName="" contactEmail="" contactPhone=""/>
<project name="Design" color="10092288" billable="false" estimate="0" rate="0" tags="" description="" code="456.1.2" remoteId="9" contactName="" contactEmail="" contactPhone=""/>
<project name="Project Management" color="10092288" billable="false" estimate="0" rate="0" tags="" description="" code="456.1.3" remoteId="10" contactName="" contactEmail="" contactPhone=""/>
</project>
</project>
</projects>
</klok>Frequently Asked Questions
When can I download the Klokwork Team Connector?
Version 1.1.8 is now available. Download it now. You must have a valid license for the full version of Klok to use the connector. You may purchase a license from our online store.
What if I already have data tracked in Klok?
Right now, all Klok connectors are intended to be installed into Klok which has not had any data tracked in it. If you already have data captured, you can start with a blank database by setting Klok’s datafile location to an empty folder. This is done on the General page of the Preference screen. Your existing data will remain in its current location.
If I use Network File Mode, how do I make sense of the submitted data?
The XML data is a structured format which can easily be read by almost any programming language. The intent is that users of this mode will have some other tool or process to parse the data. If you don’t have the resources or desire to create such a program, Klokwork Team Console may be just what you need.
How do I create the Projects.xml file?
Because the XML data is just a text file, you can manually create it in any text editor. Like any xml file, it is important to make sure the file is well-formed. You can export your project XML from Klok on the preferences screen and use that to start. The only modification you would need to make is to the remoteIdattribute. The value must be a unique identifier in your organization. It may be the same as the project code. The Klokwork Team Console can export this file for you as well.
What if we need help integrating our own timetracking system?
If you have questions regarding integration with an existing commercial or custom built timetracking system, contact us at sales@getklok.com and we can help you.