Best Practices and Troubleshooting
Best Practices
Note
The best practices specific to YubiEnterprise APIs are in the API: Best Practices and FAQs section of API Shipment Requests.
- Have at least two Console Owners who can manage members (see User Management).
- Inform both your YubiEnterprise users and your end-users in advance of sending notifications of YubiKey delivery that they will receive email from Yubico’s YubiEnterprise Delivery. Without this advance notice, they are likely to regard these emails as phishing attempts.
- If YubiEnterprise Delivery appears to be behaving strangely, check the status of YubiEnterprise Services: http://status.yubico.com/. Subscribe to that page for updates related to YubiEnterprise Console planned maintenance and/or downtime.
- Subscription customers:
- To ensure that you do not let keys in any of your inventories expire unused, create a spreadsheet to plan the allocation of products across users and inventory types. See Example Subscriptions.
- When creating a shipment request, select the inventory type before selecting the item(s) to be shipped.
Limits and Constraints
When planning and executing shipment requests, keep in mind the primary limits and constraints set out in Delivery Policies, but also the following:
PO Boxes
Although the system can deliver to Post Office (PO) Boxes within the United States, delivery to the equivalent elsewhere in the world is unlikely to succeed.
Distributors and Resellers (Channel Partners)
The entity through which you submit a PO is always referred to as a channel partner. “Channel partner” is a term that covers distributors, resellers, and even Yubico itself. Yubico’s Channel partner ID (or ChannelPartnerId
or channelpartner_id
) is “1”.
Note
The deprecated /shipments
API did not support indirect sales, i.e. the selection of channel partners (distributors, resellers). That API only supported direct sales in that the ChannelPartnerID was always set to 1
, which means Yubico. To order inventory purchased through a distributor or reseller, use the /shipments_exact
API.
Because inventory is sorted according to the source from which it was purchased, when requesting shipment, distinguish between inventory purchased directly from Yubico and inventory purchased through distributors and resellers doing business with Yubico. The Dashboard shows your total inventory of any given product, combining quantities purchased from all sources: both directly from Yubico and indirectly through channel partners. To find out what is in which inventory, check your purchase orders.
To find out what the channel partner (reseller or distributor) ID is:
BEFORE shipment: | |
---|---|
The name of the channel partner (reseller or distributor) is shown on the Purchase orders tab, and the channel partner ID is shown on the PO detail popup accessed by clicking on the Purchase order number: |
|
AFTER shipment: | The Channel partner ID (Reseller or Distributor) is shown on the shipment request detail page, accessible by clicking the ID of the shipment request on the Shipments tab. |
Names and Addresses: First Line
First name and Last name in the Console and in the CSV file for bulk shipments, map to the first line on the shipping label.
Long recipient names can be problematic for all methods of requesting shipment, because the shipment request will fail if the contents of the First name and Last name fields and/or Company or recipient
fields exceed the maximum number of characters permitted in these fields (shown in the table below).
Workaround: When a recipient’s full name or company name exceeds the fields’ maximum lengths, split the names across the three fields, as in this example:
Location | Field (limit=15) | Field (limit=20) | Field (limit=20) |
---|---|---|---|
API | recipient_firstname |
recipient_lastname |
recipient |
CSV | First name | Last name | Company |
Console | First name | Last name | Company |
Example of an overly long name before adjustment to fit the fields | |||
Johannes-Maximilian | von Derschowitz-Dampfloch zu Querdenker | ||
Example after adjustment | |||
Joh.-Maximilian | v.DerschowitzDampfloch | zu Querdenker |
Company Name: Second Line
The second line on the shipping label maps to the name of the recipient’s company if the address is not residential. For example, the system’s address verification function recognizes that Yubico’s Santa Clara facility is in a commercial building, therefore the company name is expected in:
The Company field/table cell in the Console and in the CSV file.
The
recipient
field in the APINote
API: Do not use the
/shipments recipient
field to specify the name of the individual to whom products are to be shipped. For this, use therecipient_firstname
andrecipient_last name
fields instead.
If the address is residential, leave empty:
- The Company field/table cell in the Console and in the CSV file.
- The
recipient
field in the API.
Address Information
Incomplete or incorrect address information might cause validation errors. For example, entering the following information for a shipment request would result in failure because USPS recognizes that there are multiple companies in the building whose address is 530 Lytton Avenue:
Jan Lindberg
530 Lytton Avenue
Palo Alto, CA 94301
USA
Similarly, entering the following information for a shipment request would result in failure because a residential address would not be associated with a company.
Jan Lindberg
Yubico Inc.
6 Lea Rd
Dronfield S18 1SB
UK
When adding address information, you can for example use the address formats provided by Google Maps, see note in Troubleshooting. The limits on the various fields and the options for the dropdown are given in Shipment Request Form Fields.
Timing Constraints
- Shipment Requests
- Shipment requests can be edited or deleted until 2am PST (10am GMT), the day after they were entered. For instructions on these procedures, see Editing or Deleting a Shipment.)
- Delivery
Normal (standard) shipping: Typically, shipments will take 5-7 days for delivery in North America and Europe. Delivery to other parts of the world will take longer.
Expedited (rush) shipping: Typically, shipments within North America can be delivered in 1 business day. It may take longer to deliver shipments to other parts of the world, but Yubico will leverage the fastest delivery service reasonably available.
- Address Validation
- Every 15 minutes, the system validates addresses; therefore you might have to wait up to 15 minutes to find out if your shipment request has been queued for fulfillment. (For details, see Shipping Status Codes.)
- Availability of Stock/Inventory
- Shipment allocations may be set. (For details, see Shippable Inventory.)
- Non-subscription Purchases
- Shipment requests can be made for up to one year after a PO is submitted.
- Subscription Purchases
- Availability of products depends on the stock/inventory from which the products are drawn. (For details, see Tier Sub-categories.)
Inventory Types: Subscription 1.0
The full list of options that were potentially available in Subscription (1.0) is given below. The actual list depends on what you have purchased. Explanations for the terms in the list are given in the table below the list. For more details on subscription and non-subscription purchasing, see Modes of Purchase.
Subscription (1.0): Full List of Inventory Types
- Primary Subscr - Base Tier: Initial
- Primary Subscr - Base Tier: Buffer
- Primary Subscr - Base Tier: Replacement
- Primary Subscr - Adv. Tier: Initial
- Primary Subscr - Adv. Tier: Buffer
- Primary Subscr - Adv. Tier: Replacement
- Primary Subscr - Prem. Tier: Initial
- Primary Subscr - Prem. Tier: Buffer
- Primary Subscr - Prem. Tier: Replacement
- Primary Subscr - FIPS Tier: Initial
- Primary Subscr - FIPS Tier: Buffer
- Primary Subscr - FIPS Tier: Replacement
- Backup Subscr - Base Tier: Initial
- Backup Subscr - Base Tier: Buffer
- Backup Subscr - Base Tier: Replacement
- Backup Subscr - Adv. Tier: Initial
- Backup Subscr - Adv. Tier: Buffer
- Backup Subscr - Adv. Tier: Replacement
- Backup Subscr - Prem. Tier: Initial
- Backup Subscr - Prem. Tier: Buffer
- Backup Subscr - Prem. Tier: Replacement
- Backup Subscr - FIPS Tier: Initial
- Backup Subscr - FIPS Tier: Buffer
- Backup Subscr - FIPS Tier: Replacement
- Non-subscription - Base Tier
- Non-subscription - Advanced Tier
- Non-subscription - Premium Tier
- Non-subscription - FIPS Tier
- Standard Products
Standard Products | Subscription | Non-subscription |
---|---|---|
Standard products are
physical keys purchased
outright (on your PO
you will not find
“Standard Products”,
but instead the actual
products/models that
you purchased).
|
There is a primary
subscription and a backup
subscription for each
tier (product grouping):
Base, Advanced, Premium,
and FIPS. Each of those
tiers has Initial,
Buffer, and Replacement
sub-categories, explained
in the table below,
|
The non-subscription
tiers are for virtual
keys. Unlike
subscription tiers,
non-subscription
tiers have no
sub-categories.
|
Initial | The stock in this category reflects the
total number of users on the subscription. This
lot can be drawn upon for 12 months from the
start of your subscription term.
|
Buffer | This category is made available to you free of
charge when your subscription begins. You can
draw on it throughout the term of your
subscription.
|
Replacement | This category is intended for those who have
lost their YubiKeys or want to upgrade. The
stock in this category is reset each year of
the subscription to the Replacement limit.
|
Troubleshooting
This section addresses issues that can arise with shipping. YubiEnterprise Delivery notifies you of the situation of any given shipment via the codes in the Status column of the Shipments tab. The table below, Shipping Status Codes, lists the error codes and their explanations.
YubiEnterprise Delivery uses address validation services to reduce the incidence of issues, but it is important to be aware that just because an address exists in Google Maps, it does not mean that the address is deliverable. ‘Deliverable address’ is a United States Postal Service (USPS) classification for designating addresses to which the USPS has historically been able to deliver. YubiEnterprise Delivery’s ability to deliver is based on address information being input in the format acceptable to the relevant address validation service. The USPS-acceptable formats are set out in detail in the USPS’s Postal Addressing Standards.
Note
When revising an address, the best option is to use the format Google Maps presents, because it usually does use the address format preferred by the validation service. In the example below, the address format that was input appears in the upper field, and Google Maps’ format is shown below the photo of the location.
Address Validation Outside the US and Canada
For parts of the world with less standardized address formats, the fact that YubiEnterprise Delivery can accept an address does not mean that it is deliverable. An address will often be classified as “partially deliverable”, which means that we rely on local couriers who are familiar with the complexities of their urban systems and their delivery routes to deliver to the intended recipient.
Typically packages sent to European addresses and some parts of Asia reach their destination. Packages sent to Southeast Asia and Eastern Europe typically arrive at the right street. In those parts of the world where there are no numbers in the postal addresses, the local courier’s capability is crucial to ensuring that the package actually arrives at its destination as opposed to ending up in its general area.
Shipping Status Codes
At any of the states between 1 and 9, a shipment request can be edited. From this point on, a shipment request is either processed through to an end state, or set back to state 99.
shipment_state_code
shipment_state_id
|
Status description
(shipment_state_description)
|
Status message in Console
(shipment_state_message)
|
---|---|---|
ShipmentStateIncomplete
1
|
Shipment request received
by YubiEnterprise Delivery
system but contained some
data that could not be
processed.
(2), (3) |
Incomplete Shipping
Request
|
ShipmentStateDraft
2
|
Shipment request is being
edited and is not ready for
processing.
|
Draft |
ShipmentStateAwaitingValidation
3
|
Shipment request received,
no validation done yet.
|
Awaiting Validation |
ShipmentStateProcessingAddress
4
|
Shipment request locked as
it undergoes country check,
address validation, sales
tax rate lookup (US), DPL
check.
|
Processing |
ShipmentStateAddressValid
5
|
Shipment request address has
been validated, ready to be
picked up by fulfillment
processor.
|
Accepted for Fulfillment |
ShipmentStateAddressInvalid
6
|
Shipment request address is
invalid but an alternative
address has been found and
suggested.
(2), (3) |
Incomplete |
ShipmentStateAddressFail
7
|
Shipment request address
could not be validated and
no alternative could be
found for suggesting.
suggested.
(2), (3) |
Address is undeliverable
or could not be
understood
|
ShipmentStateError
8
|
Shipment request has failed
processing due to
insufficient credits
or insufficient inventory.
|
Error: Processing Error,
contact Support
|
ShipmentStateDPLMatch
9
|
Shipment request recipient
found on DPL, therefore it
is illegal to fulfill this
shipment request.
(4) |
Error: DPL Match |
ShipmentStateRequested
12
|
Used for manual shipments
that are requested but have
not yet been shipped.
|
Requested |
ShipmentStateShipmentError
99
|
Shipment request rejected
from ShipmentState-
ProcessingFulfillment
with “%s” error message;
could not be fulfilled by
processor.
|
Error: Shipping error,
contact Support
|
ShipmentStateProcessingShipment
100
|
Shipment request was locked
at 1000hrs UTC to calculate
and deduct tax, inventory,
and credits.
(1) |
Processing: Inventory &
Tax Deductions
|
ShipmentStateFulfillmentReady
101
|
Shipment request ready to be
queued for fulfillment.
|
Processing: Ready for
Fulfillment
|
ShipmentStateProcessingFulfillment
102
|
Shipment sent for fulfill-
ment at 10:00am (or cutoff
time.
(1) |
Processing: Sent for
Fulfillment
|
ShipmentStateShipped
103
|
Shipment sent out by
fulfillment processor and is
in transit.
|
Shipped: In transit |
ShipmentStateShipped
104
|
Shipment delivered.
|
Delivered |
ShipmentStateLost
105
|
Shipment lost and delivery
is no longer expected.
|
Shipment Lost/Missing |
ShipmentStateDeliveryException
106
|
Customs hold or undelivered
or returned shipment to
sender or any other shipping
exceptions.
|
Delivery Exception |
ShipmentStateDPLConfirmed
107
|
A shipment that was
automatically detected as a
DPL match has been reviewed
by Yubico and found to be a
confirmed match (not false
positive). The shipment will
not be processed.
|
DPL Confirmed
|
ShipmentStateCancelled
108
|
The shipment has been
cancelled, for example
because a logistics partner
is not able to ship the
order. Cancelling is a manual
action done by Yubico.
|
Cancelled
|
ShipmentStateReturnedToSender
110
|
Shipment has bounced and
been returned to sender
(Yubico or one of Yubico’s
logistics partners).
|
Returned to Sender
|
ShipmentStateShippingQueue
1025
|
Shipment queued for
fulfillment.
|
Processing:
Queued for Fulfillment
|
ShipmentStateManualFulfillment
2000
|
Shipment is being fulfilled
manually. No further action
by shipment requestor is
required.
|
Manual Processing |
(1)
Refer to Timing for cutoff times.
(2)
Incomplete Address: Secondary line information such as apartment (apt), suite, unit is missing. Therefore it is not possible to guarantee delivery to the correct recipient.
(3)
Address is Undeliverable or could not be understood: The address is either not physically deliverable or it could not be resolved to a real location.
(4)
Any shipping request with a recipient name and/or address found on the US government’s DPL (Denied Parties/Persons List) cannot be fulfilled.
Shipment Status Messages
These error messages accessible via the API tell you why a given shipment request was unsuccessful. It is worth reviewing them before making any shipping requests in order to see what sort of issues might arise and thereby avoid them in the first place.
In the Explanation column, the source of the message is given: YubiEnterprise Delivery system for internal messages, US Validation for the US Postal Service, and finally, International Validation. Messages originating from the last two are simply passed on to you by YubiEnterprise Delivery.
Message | Explanation |
---|---|
InventoryProductId not specified forProductId %d - ShipmentStateError
|
YubiEnterprise Delivery system
|
Too many keys in shipment -
TotalKeysShipped %d > %d - ShipmentStateError
|
YubiEnterprise Delivery system
|
Not enough Inventory for Shipment -
ShipmentStateError
|
See Purchase Orders
YubiEnterprise Delivery system
|
Re-enter the address differently; some parts
of it are invalid.
|
See Troubleshooting
US Validation
|
The address is invalid.
|
See Troubleshooting
US Validation
|
The address is valid.
|
No further explanation required.
US Validation
|
Remove the ‘secondary unit designator’
(apt, suite, department, etc.)
because it is superfluous.
|
Remove the apartment number, unit, etc.:
it is considered wrong or unnecessary.
US Validation
|
Enter second line information (apartment, unit,
etc.). The information in the primary line is not
specific enough.
|
Add the apartment number, unit, etc.
US Validation
|
The address is a valid military address.
|
No further explanation required.
US Validation
|
The address is a valid General Delivery address
where individuals without permanent addresses
can receive mail.
|
No further explanation required.
US Validation
|
The address is valid. An organization such as a
government agency can have its own zipcode
because it receives a large volume of mail.
|
No further explanation required.
US Validation
|
Enter a street number; for example, for Yubico
“Lytton Ave” alone is not sufficient, it needs to
be “530 Lytton Ave”.
|
The number on the primary line, for example
the “185” in “185 Berry Street” is missing.
US Validation
|
Enter a valid street number.
|
The number on the primary line, for example
the “185” in “185 Berry Street” not valid.
US Validation
|
Enter a PO Box, Rural Route, or Highway
Contract number.
|
US Validation
|
Enter a valid PO Box, Rural Route, or Highway
Contract box number.
|
US Validation
|
Enter the Private Mailbox (PMB) identifier or the
# sign, followed by the PMB number.
|
PMB number is Private Mailbox Number
US Validation
|
This address is not eligible to receive mail.
|
US Validation
|
The address is that of a Commercial Mail
Receiving Agency (CMRA) a private business that
accepts mail for recipients, and the required
private mailbox information is present.
|
US Validation
|
The address is missing some important
secondary line information
(apartment, unit, etc).
|
No further explanation required.
International Validation
|
Mail is unlikely to arrive at this destination
- please verify input.
|
No further explanation required
International Validation
|
This street could not be found within the city
or postal code.
|
No further explanation required
International Validation
|
Invalid OrganizationId for Shipment
|
YubiEnterprise Delivery system
|
Country Code not set for Shipment
|
YubiEnterprise Delivery system
|
Country could not be found from
CountryCode2: %s
|
Country code entered is not in
YubiEnterprise Delivery system list
|
Shipment has no shipment items
|
YubiEnterprise Delivery system
|
DeliveryType not set for Shipment,
defaulting to 1 - normal
|
YubiEnterprise Delivery system
|
Invalid DeliveryType %s for Shipment
|
YubiEnterprise Delivery system
|
InventoryType not set for Shipment,
defaulting to 1
|
YubiEnterprise Delivery system
|
InventoryType %s not valid set for Shipment
|
You cannot use this InventoryType for this
shipment - YubiEnterprise Delivery system
|
Negative quantity entered for ShipmentItem
with ProductId=%d defaulting to 0
|
You set the quantity of the specified
ProductID to be shipped to less than zero.
YubiEnterprise Delivery system
|
Invalid ShipmentProductQuantity for
ShipmentItem %d
|
You probably do not have sufficient inventory.
YubiEnterprise Delivery system
|
Invalid ShipmentProductLineCost for
ShipmentItem %d
|
YubiEnterprise Delivery system
|
Invalid Shipment - Total keys in shipment
greater than 500
|
You cannot ship more than 500 items at once.
YubiEnterprise Delivery system
|
Shipment has zero total item quantity
|
The number of items to be shipped must be > 0.
YubiEnterprise Delivery system
|
US Address is missing the state
name/abbrevation in region field
|
No further explanation required.
YubiEnterprise Delivery system
|
Bad ProductId in ShipmentProduct for
NewShipmentProduct
|
ProductID is wrongly specified or invalid.
YubiEnterprise Delivery system
|
Input for %s exceeded limit of %d characters
|
Specified field cannot accept the number of
characters that were entered.
YubiEnterprise Delivery system
|
Shipment of these products to this country
using this delivery type is not supported
For more information, see Delivery Policies.
|
Shipment request contravenes one or more
business rules.
YubiEnterprise Delivery system
|
- See the USPS FAQ.
Insufficient Inventory
To maintain the window during which orders can be updated, edited, or recalled/deleted, orders are held and processed in batch. Therefore there might be less inventory available by the time an order is processed than what was shown in purchase order details when the request was created. For example, the person starting to create a shipment request assumes that the 50 keys the console shows they have in inventory will still be available by the time the shipment request is submitted. When this is not the case, any shipment requests processed after the inventory is exhausted will be flagged with this error message:
Error: Processing Error, contact support.
Reason is Not enough Inventory for Shipment
- ShipmentStateError
A second issue arises from the same source: when the user clicks on the shipment request ID with that error, part of the status message displayed is “Insufficient Inventory of Product X” where “X” is an integer. To find out what X means, consult the Product Name, Stock/Inventory, product_id and inventory_product_id table.
A third issue arises from the same source: it is not possible to make single shipment requests for products that are not available in inventory - which is expected if insufficient product has been purchased, but an insufficiency of inventory can also be caused by Yubico itself running out of stock. However, this issue has now been resolved by warning the user before a shipment request is made. See Shippable Inventory.