Document toolboxDocument toolbox

Tempo servlet manual

Owned by Former user (Deleted)
Last updated: Mar 06, 2024 by Jaramy Conners
4 min read

Tempo servlets 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=2011-01-01&dateTo=2011-01-31&format=xml&diffOnly=false&tempoApiToken=my-token
    1. NB. This is an HTTP GET method
    2. (info) 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. (info)  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
        (warning) 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
        (warning) approvalStatus is not part of diffOnly=true 


On this page

In this chapter

The selected root page could not be found.

Related pages

Tempo REST API´s

  1. Result example:
Example results from GetWorklogs
 
<?xml version="1.0" encoding="UTF-8"?> 
<worklogs> 
  <worklog> 
    <worklog_id>46445</worklog_id> 
    <issue_id>13189</issue_id> 
    <issue_key>CLOUD-18</issue_key> 
    <hours>8.0</hours> 
    <work_date>2011-10-11</work_date> 
    <username>erica</username> 
    <staff_id>2410724289</staff_id> 
    <billing_key>6</billing_key> 
    <billing_attributes>Account=201405,Billable=3600,Box=true,Input=abc,longSelect=11,Number=123,Type=3<billing_attributes/> 
    <activity_id>v10444</activity_id> 
    <activity_name>CloudBay Sprint 4</activity_name> 
    <work_description>Review</work_description> 
    <parent_key/> 
    <reporter>john</reporter> 
    <external_id/> 
    <external_tstamp/> 
    <hash_value>dc11dffc091fcc72e7358067a9488fa1e31ce314</hash_value> 
  </worklog> 
</worklogs>

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). 
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
    (info) The Tempo API Security Token is explained in the Access control 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"

  3. Input example:

    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:

    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

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
    (info) The Tempo API Security Token is explained in the Access control 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
    (info) The Tempo API Security Token is explained in the Access control 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

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

Tempo Timesheets for Server Documentation
For the newest version Tempo Timesheets documentation, please visit our Help Center. For support, see our Support Portal.