Tempo is a JIRA plugin that eases time registration, reporting, and integration with external systems. Integration is very important for most companies, as JIRA does not provide an accounting system, something essential for billing customers and tracking expenditures like sick days and holidays. This article discusses how worklogs entered in JIRA can be integrated with an external system.
Integrating two systems is a fairly complex process; change in one system must be reflected in the other. Tempo, however, allows users to easily change worklogs, whether for something as simple as a spelling correction or the modification of a date, or for more involved tasks, such as deleting a worklog.
Tempo provides several services to integrate JIRA worklogs with external systems. The two main tools for worklog integration are:
- GetWorklogs
- UpdateWorklogs
These services are executed on the "other side," i.e., the external system executes GetWorklogs to get the available worklogs and then calls UpdateWorklogs to sign for delivery, or to notify Tempo of the worklog status in the external system. GetWorklogs uses several parameters such as a date range and diffOnly which filters out worklogs that have changed since the last update. Additional parameters such as validOnly filter out worklogs that are known to give errors in the external system.
The most commonly used scenario is to let Tempo control the dates (open periods) and call GetWorklogs with the diffOnly, validOnly and of course format=xml options. Here is an example of how the URL to GetWorklogs is usually defined in the external (calling) system:
- http://yourserver.yourdomain/plugins/servlet/tempo-getWorklog/?format=xml&diffOnly=true&validOnly=true
The external system processes the worklogs and calls UpdateWorklogs for all logs processed. The external system must make sure that all processed worklogs are correctly updated. Failure to correctly update a worklog can result in the log being duplicated. It is at the discretion of the external system whether to update all the worklogs in one big update or to process them one at a time.
A detailed description of all the services can be found here.
How to integrate - an aid to development and testing
An important part of integration is of course the development and testing! The Tempo API provides 2 important features to aid developers during development and testing:
- Specifying the format=testData parameter to GetWorklogs creates an XML that can be used as input to UpdateWorklogs
- Example: http://localhost:8080/plugins/servlet/tempo-getWorklog/?dateFrom=2011-01-01&dateTo=2011-01-31&format=testData
- Opening http://localhost:8080/plugins/servlet/tempo-updateWorklog/ in a browser opens a simple page where the developer can paste update XML and POST to Tempo
How to create a worklog "warehouse"
Some of our larger customers (including Origo itself) need much more powerful reporting than Tempo or any other JIRA plugin provides. These customers use the Tempo API to populate a "warehouse" and do their data crunching on the exported data with specialized reporting tools. Tempo eases this integration by adding several parameters to GetWorklogsthat add information to the worklogs. Examples:
- addBillingInfo
- addIssueSummary
- addIssueDetails
- addWorklogDetails
- addUserDetails
Tempo also provides 2 additional functions that can be useful when populating a "warehouse":
- BillingKeyList: returns a detailed list of all billing keys (expenditure items) in Tempo.
- HolidayList: returns a list of all holidays specified in Tempo. This is useful when calculating for example workload and staff utilization.
How to create (simple) reports based on billing key (expenditure item)
The Worklog Report function returns an XML with "cooked" data that is ready to be rendered as a nice report. This can be quite handy for organizations that need to create worklogreports as a part of an invoice.
Custom made reports with XSL
A Tempo customer has generously shared his version of Tempo reports that he creates with some PHP and XSL. You can download his reports here and start extending/customizing for your needs.
