---
title: "Configuration and usage"
canonical: "https://support.appfire.com/space/TJC/815759386/Configuration%20and%20usage"
format: markdown
---
> Macro (aura-html)

The Toggl Integration streamlines time tracking within your Jira work item. This guide details how to configure it after installation.

### Prerequisites

- [Toggl account](https://toggl.com/app/profile) with an active API key.

### Configuration

1. After installing the app, open a work item in a project.
2. Navigate to the work item details sidebar, and open the Toggl Integration.
3. Click **Open Toggl site**. *The *[*Toggl profile page*](https://toggl.com/app/profile)* opens. *
4. Locate your API token within the profile settings. Click **Click to reveal** to view and copy the key.

> ⚠️ You must ensure your API token remains private to prevent the sharing of sensitive information.

5. Return to Jira and access the Toggl Integration section again.
6. Paste your API key into the *Token* field and click **Connect** to save the configuration.

After that, Toggl is ready for use. 

![Toggl Integration for Jira token field with Connect button](media://d48b2454-6eec-4d12-bfe1-e77fe2f4befe)

### Using Toggl within a work item

With the API key integrated, you can leverage Toggl directly within Jira:

#### **Start Tracking **

Clicking **Start Tracker: **`issue key` initiates time tracking for the specific work item in Toggl. A corresponding time entry is created in your Toggl Track account, automatically capturing the Jira work item key and summary. You can use the default settings, but alternatively, click **Tracking settings** to set your own tracking configuration. The options are:

![Toggl Integration for Jira tracking settings with workspace, project, and tags](media://12840047-7069-478e-be48-c87905c25d8f)

- **Select Toggl workspace – **Choose the specific workspace within your Toggl Track account where you want the time entry to be stored.
- **Select Toggl project – **Designate the relevant project within your chosen workspace for this time entry.
- **Select Toggl tags –** Assign relevant tags (keywords) to categorize the time entry within Toggl Track.
- **Apply JIRA issue labels – **Map corresponding labels from the Jira work item to the Toggl time entry for further categorization.
- **Mark as billable – **If the work on this work item is chargeable, select this option to mark the time entry as billable in Toggl.

> 📝 Through **[Configuration](https://appfire.atlassian.net/wiki/spaces/TJC/pages/816709793)**[ options](https://appfire.atlassian.net/wiki/spaces/TJC/pages/816709793), you can choose to prefill these default options instead of filling them out manually.

> ⚠️ If users pay for Toggl Premium and they use Projects, there will also be an additional [Tasks](https://support.toggl.com/en/articles/2220738-tasks) option. In that case, a project will have a Task created, there will be a field to select it.

 

#### **Stop Tracking **

Clicking **Stop Tracker** finalizes the time tracking and converts it into a work log for the associated Jira work item. At this stage, disabled *Tracking settings* with filled options that are selected for the running entry are displayed. 

![Toggl Integration for Jira running tracker with selected tracking settings](media://2e15ddd7-be82-4fa2-ae0a-89473d2be47b)

The **Time logs** tab allows you to view all the time logs related to the specific work item.  

![Toggl Integration for Jira Time logs tab for a work item](media://a59c061b-2122-4aed-b1b7-f73bbd4c13af)

After stopping the tracker, you can view and manage your time logs directly on the Toggl Track **Timer** page. For more information on the Timer page, navigate to the [Toggl Track documentation](https://support.toggl.com/en/articles/2015973-the-timer-page). 

> 📝 Make sure you name your time entries starting with the work item key (XXX-NN) followed by a colon (for example, NCG-2012: some description).

![Toggl Track Timer page with Jira work item time entries](media://31c3691e-9e10-495b-88e6-a88f86b51988)