Tempo Servlet Manual

Integrating two systems is a fairly complex process; change in one system must be reflected in the other. Tempo, however, allows users to easily modify worklogs, whether for a simple edit such as a spelling correction or modifying a date, or for a more involved task, such as deleting a worklog.

The blog Integrating Atlassian Jira using Tempo Plugin explains how worklogs entered in Jira can be integrated with an external system.

The Tempo services are designed as Machine-to-Machine communication and are not typically used by normal users. The services provide ALL worklogs regardless of permissions. They should therefore be used with care and should only be open to a limited number of people/computers. Jira administrators control access to the Tempo services with IP address filtering.

This page explains in detail the available functions in Tempo services API and how they can be used in your company. Please comment on this page if something is not clear enough or you have some questions on this subject.

GetWorklogs

Gets all worklogs for a given period, returns data on specified format (XML, Excel or test data)

1. URL: http(s)://yourserver.yourdomain/plugins/servlet/tempo-getWorklog/?dateFrom=2022-01-01&dateTo=2022-01-31&format=xml&diffOnly=false&tempoApiToken=my-token

   1. NB. This is an HTTP GET method

   2.  The Tempo API Security Token is explained in the Access Control page.

2. Parameters:

   1. dateFrom=yyyy-mm-dd

   2. dateTo=yyyy-mm-dd

      1. Note that skipping both dates returns the current "open period" which is controlled in Jira Admin.

   3. format=xml|excel|testData

      1. External applications use the XML format

      2.   See this page if you want to include Jira custom fields to the XML export

      3. testData creates an XML that can be used as input to update

   4. diffOnly=true|false(default)

      1. External applications use diffOnly=true to get only changed records since last GetWorklogs

      2. diffOnly returns only records that have changed since last update (UpdateWorklogs) or are marked as external error (external_result is not OK)

   5. errorsOnly=true|false(default)

      1. Returns a list of worklogs that the external system marked as error or are not valid for export (missing billingKey or staffId or expression is invalid)

   6. validOnly=true|false(default)

      1. Returns a list of worklogs that are valid for import, i.e. have both billingKey and activity

   7. addBillingInfo=true|false(default)

      1. Adds billing info to each worklog

   8. addIssueSummary=true|false(default)

      1. Adds issue summary field to each worklog

   9. addIssueDetails=true|false(default)

      1. Adds issue details such as issue type, original estimate, remaining estimate, version, component, project key, project category, project name and issue priority.

   10. addWorklogDetails=true|false(default)

       1. Adds worklog details such as creation date and updated date

   11. addUserDetails=true|false(default)

       1. Adds user details such as user full name and all Jira user properties. User properties displayed in XML format only

   12. headerOnly=true|false(default)

       1. Returns only header information (no data). Used to see the current "open period".

   13. userName=userName

       1. Filters by dates and userName only

   14. billingKey=billingKeyId

       1. Filters by dates and billing key (Account, Expenditure Item) only
           Global Accounts are not supported 

   15. addIssueDescription=true|false(default)

       1. Adds issue description field to each worklog in XML format only

   16. addParentIssue=true|false(default)

       1. Adds parent issue details to each worklog in a sub-task. Valid in XML format only

   17. projectKey=projectKey

       1. Filters by dates and project key only

   18. issueKey=issueKey

       1. Filters by dates and issue key only

   19. addApprovalStatus=true|false(default)

       1. Adds Timesheets approval status, reviewer, time-stamp and comment for a user timesheet
           approvalStatus is not part of diffOnly=true 

Result example from Jira to external system:

Example results from GetWorklogs

Activity information: The activity for the worklog is one of the following:

• The Version on the issue. If there are more than one versions on the issue the version selected as the activity is the top one in the Schedule order. Activity id has v as a prefix.

• The Component on the issue. If there are more than one component on the issue the component selected is the latest (the one with the highest id). Activity id has c as a prefix.

• If the issue has both a Component and a Version the version is selected as the activity.

UpdateWorklogs

Updates worklogs with external information (external id & external hours) from external system to Jira server. 
Note: The hash_value field from getWorklog must be used with the update to verify the integrity of the update.

1. URL: http(s)://yourserver.yourdomain/plugins/servlet/tempo-updateWorklog/?tempoApiToken=my-token
    The Tempo API Security Token is explained on the Tempo Servlet manual page.
   
   

   1. HTTP GET opens a simple form to paste XML input (used for testing)

   2. HTTP POST accepts XML input and updates worklogs in Jira

      1. The input XML must be sent as parameter: worklogs

2. Example by POSTMAN or Browser:
   
   
   
   

3. Input example from external system to Jira:

   Example input to UpdateWorklogs - POST-ed with the *worklogs* parameter

   <?xml version="1.0" encoding="UTF-8"?> <worklog_updates> <worklog_update> <worklog_id>46445</worklog_id> <external_id>SAP-ID-12345</external_id> <external_hours>8.0</external_hours> <external_result>OK</external_result> <hash_value>dc11dffc091fcc72e7358067a9488fa1e31ce314</hash_value> </worklog_update> </worklog_updates>

   
   
   

4. Output example from Jira to external system:

   Example output from UpdateWorklogs

   <?xml version="1.0" encoding="UTF-8"?> <worklog_results> <worklog_result> <worklog_id>46445</worklog_id> <external_id>SAP-ID-12345</external_id> <result_tstamp>2011-10-12 11:13:48</result_tstamp> <external_hours>8.0</external_hours> <external_result>OK</external_result> <update_result>OK</update_result> <ms>125</ms> </worklog_result> </worklog_results>

   
   
   

WorklogReport  - Deprecated

Returns a worklog report as XML that can be used as input to a reporting tool (iReport).

1. URL: http(s)://yourserver.yourdomain/plugins/servlet/tempo-getWorklogReport/?dateFrom=2011-01-01&dateTo=2011-02-01&billingKey=ABC&useExternalHours=true|false&tempoApiToken=my-token
    The Tempo API Security Token is explained on the Tempo Servlet manual page.

2. Parameters:

   1. dateFrom=yyyy-mm-dd

   2. dateTo=yyyy-mm-dd

   3. billingKey=billing key to be used in the query

   4. useExternalHours=false|true (default). External hours are hours registered in external system with updateWorklog.

BillingKeyList

Returns a list of available accounts (billing keys), to be used when creating reports.

1. URL: http(s)://yourserver.yourdomain/plugins/servlet/tempo-billingKeyList&tempoApiToken=my-token
    The Tempo API Security Token is explained on the Tempo Servlet manual page.

2. Note that the enabled attribute can have the following values:

   1. "2" - Closed: The account was closed manually in Tempo Accounts.

   2. "3" - Open: The account is open

HolidayList

Returns a list of registered non-working days (holidays), to be used when calculating required hours in an external system

1. URL: http(s)://yourserver.yourdomain/plugins/servlet/tempo-holidayList/?tempoApiToken=my-token

 If you are adding a parameter like the security token in the url above you need to add ? before the first parameter.