Waybill for Jira

Setup guide

Everything a Jira administrator needs to install, configure and use Waybill.

Waybill shows live tracking on Jira work items. Someone types a tracking number into a work item, and the app works out the carrier, fetches the status, and keeps a set of Jira fields up to date. Because they are real Jira fields, you can search them with JQL and build automation rules on them.

Supported carriers: UPS, FedEx, USPS and DHL. UPS and FedEx have been verified against live shipments; USPS and DHL are built to the carriers' published APIs but have not yet been verified against live shipments. You bring your own free API credentials for each carrier you use; the app does not include any.

How it works

A person enters a tracking number in the Tracking Number field. Within a few seconds the app cleans the number (removing spaces, dashes and other characters), detects the carrier, and writes the results into the shipping fields. After that, a background job re-checks the shipment on the schedule you choose, for work items that match your rules. Shipments that are Delivered or Returned are not checked again.

Each work item tracks one tracking number.

Setup checklist

Do these once, as a Jira administrator.

  1. Install the app on your Jira site.
  2. Add the fields to your screens. The app creates its fields automatically, but Jira can take a few minutes after the install to show them (check Settings → Work items → Fields), and they only appear on a work item once they are on that project's screens. Go to Settings → Work items → Screens, open the screen your projects use, and add Tracking Number and the read-only shipping fields. Add at least Tracking Number to the create/edit screens; add the others to the view screen.
  3. Get carrier credentials. See the "Get API credentials" guide. You only need the carriers you ship with.
  4. Open Apps → Waybill (in Jira settings) and use the Carrier credentials tab to enter the credentials for each carrier. The app tests them with the carrier before saving.
  5. Choose how often to check and which work items to check on the Settings tab (see below).
  6. Test it. Enter a real tracking number on a work item. The shipping fields should fill in within a few seconds.

Site settings (Jira administrators)

Open Jira settings → Apps → Waybill. The page has three tabs: Settings, Carrier credentials and Documentation.

Carrier credentials (its own tab)

On the Carrier credentials tab, enter the credentials for each carrier you use. They are stored encrypted, are never displayed again, and are only ever visible to the app. Only Jira administrators can view or change this section. Use Remove to delete a carrier's credentials.

Refresh interval

How often shipments are re-checked: every 1, 2, 4, 6, 12 or 24 hours. One hour is the shortest possible interval. This is a site-wide setting. The check runs once an hour and picks up every work item that would otherwise go past the interval, so a work item is never left longer than the interval you choose.

Which work items are refreshed

The scheduled refresh only checks work items that match all of the rules below:

  • Statuses (required). Only work items currently in one of these statuses are refreshed. Choose the statuses where a shipment is still expected, for example "In Progress" or "Waiting for delivery", and leave out Done. If no statuses are selected, nothing is refreshed on the schedule.
  • Work types (optional). If you select any, only those work types are refreshed. Leave empty for all work types.
  • JQL filter (optional). An extra JQL condition every work item must also match. For example: labels = "hardware" AND priority in (High, Highest). The filter is checked when you save. Do not add ORDER BY; it is ignored.

These site defaults apply to every space that has not set its own rules.

Statuses and work types are matched by name, so a status called "Done" in several projects appears once in the list and matches all of them.

Space-level settings

Turn on Allow space administrators to set their own rules to let each space choose its own statuses, work types and JQL. Carrier credentials and the refresh interval always stay under Jira administrator control. If you turn this off, every space uses the site defaults.

Space settings (space administrators)

In a space, go to Space settings → Waybill. Space administrators (and Jira administrators) can choose:

  • Use site defaults. The space follows the rules set by the Jira administrator.
  • Custom rules for this space. Pick this space's own statuses, work types and JQL. The JQL is always limited to this space, so it cannot affect other spaces.
  • Don't refresh shipments in this space. Turns Waybill off for the space, including the instant update when a tracking number is entered.

When updates happen

  • Instantly when a tracking number is added or changed on a work item, in any status. This does not use the status, work type or JQL rules. It only stops if the space has Waybill switched off.
  • On a schedule for work items that match the rules above and are due, based on the refresh interval.
  • On demand with the Refresh now button in the Waybill panel on the work item.

The fields

All fields belong to the app and can be used in JQL, filters, dashboards and automation.

  • Tracking Number. The one field people edit. Text is cleaned automatically.
  • Shipping Carrier. UPS, FedEx, USPS or DHL, detected from the number.
  • Shipping Status. One consistent status across all carriers (see below).
  • Shipping Status Detail. The carrier's own wording for the latest scan.
  • Shipping Last Location. City, state and country of the latest scan.
  • Shipping Estimated Delivery. The carrier's estimated delivery, when available.
  • Shipping Delivered At. When the carrier reported delivery.
  • Shipping Last Event At. The time of the latest carrier scan.
  • Shipping Last Checked. The last time the app successfully refreshed the shipment.
  • Shipping Tracking Link. A link to the shipment on the carrier's own website.

Date and time fields are shown with the time zone abbreviation (for example EDT or PST) in your own time zone.

Shipping Status values

Every carrier's status is mapped to one of these:

  • Label Created. The carrier has the shipping information but has not received the package.
  • In Transit. The package is moving through the carrier's network.
  • Out for Delivery. The package is on the delivery vehicle.
  • Delivered.
  • Exception. A delay, failed attempt, hold, damage, address problem or similar.
  • Returned. Being returned to the sender.
  • Not Found. The carrier does not know this number yet. New labels often take a few hours to appear.
  • Unknown. The carrier returned a status the app could not classify. The detail field still has the carrier's wording.
  • Unrecognized Number. The number does not look like a UPS, FedEx, USPS or DHL number.
  • Carrier Not Configured. The carrier was detected but no credentials have been added for it.
  • Lookup Pending. The carrier had a temporary problem (it was busy, rate limiting requests, or unreachable) when a new tracking number was entered. This is not an error on your side. Waybill retries automatically at the next hourly run and the status changes when it succeeds.
  • Error. The carrier lookup failed for a new tracking number, for example because the credentials were rejected. The other shipping fields are cleared so no data from a previous shipment is shown, and the Shipping Status Detail field holds the reason. If a lookup fails for a number that has already been tracked successfully, the last known information is kept and the Waybill panel shows a warning instead.

Carrier limits and retries

Carriers limit how many requests they accept. Waybill handles this for you:

  • Temporary problems (a busy or unreachable carrier, or a rate limit) are retried automatically with increasing pauses, and the carrier's own "try again in N seconds" instruction is respected.
  • If a carrier keeps rate limiting or looks down, Waybill stops calling it for a while (starting at 15 minutes and lengthening if it continues, up to 2 hours) so your quota is not wasted. Work items keep their last known information, and new tracking numbers show Lookup Pending until the carrier is back.
  • DHL's free plan allows one request every 5 seconds, so Waybill spaces DHL requests out. With many DHL shipments a refresh takes longer, and a longer interval or narrower rules help.
  • Credentials that are rejected are never retried, because repeating them cannot help.

Automation examples

Create rules in Settings → System → Automation, using the shipping fields:

  • Move a work item when a package arrives. Trigger: *Field value changed* on Shipping Status. Condition: Shipping Status equals Delivered. Action: transition to "Received".
  • Alert on problems. Trigger: *Field value changed* on Shipping Status. Condition: Shipping Status equals Exception. Action: send an email or Slack message to the assignee.
  • Find late shipments. JQL: "Shipping Estimated Delivery" < now() AND "Shipping Status" != "Delivered".
  • Find shipments not checked recently. JQL: "Shipping Last Checked" < -1d AND "Shipping Status" is not EMPTY.

Limits

  • One tracking number per work item.
  • The shortest refresh interval is one hour.
  • Carrier API quotas apply to your own credentials. DHL's free tier is small (see the credentials guide); use a longer interval or narrower rules if you track many shipments.
  • Tested in company-managed and team-managed spaces. In a company-managed space you add the Waybill fields to the space's screens; in a team-managed space they appeared on work items without any extra setup in our tests. The customer portal view has not been tested.