Third party IDs
Third party IDs are unique codes to allow customers to identify their Drillster accounts using their own reference.
Drillster assigns a unique, random-based user ID to each account that is created on the Drillster system. These IDs are
immutable (they never change) and are guaranteed to be unique across the system. The Drillster user IDs, also known as
internal user IDs, are used throughout the API to identify user accounts. A typical internal user ID looks like this:
6Eb9DmW_VB4fWOT6yGDY0Q.
In addition to the internal IDs, the system also allows customers to equip their managed Drillster accounts with an ID of their choosing. This could be a personnel number, a student ID or some other code that uniquely identifies the user in some IT system managed by the customer.
As the name implies, a third party ID consists of two parts:
- A third party
- An ID
Because the ID of a third party ID is controlled completely by the customer, the IDs alone are not guaranteed to be unique across the Drillster system. This is why each third party ID is prepended with a third party code to indicate what customer, system or numbering scheme the ID is for.
The third party and the ID are usually separated by a slash character. A typical third party ID might look like
SYSTEM/12345, where SYSTEM denotes the third party, and 12345 is the ID as used by the customer.
Third party setup
In order for customers to make use of third party IDs, a third party must be set up first, and it must be authorized for the customer's organization. Third parties cannot be set up by the customer themselves – this must be done by Drillster Support.
Setting up a new third party should typically by done in consultation with the customer. Both Drillster and the customer must have a solid understanding of the source of the third party IDs.
- What does the third party represent? Is it an IT system? Is it a personnel number? Is it a more generic numbering system such as a government ID?
- Are the IDs generated by the third party strictly used by the organization, or is the scope perhaps larger? Think for example of a hosted HR system that creates globally unique user IDs across all of their customers.
- Is there a chance that the scope of the IDs will be widened in the future?
Once both parties have a good understanding of what the third party represents, a third party record is created in the Drillster system. It takes the form of an upper case word (letters, decimal digits and underscores only). It should ideally be recognizable to the customer and their users. The proper authorization in terms of being able to use the third party is also established.
Third party IDs
Once the third party has been configured and its value communicated to the customer, it becomes possible to set up user accounts with such a third party ID. Aside from its internal ID, a Drillster user account may have any number of third party IDs, but at most one of each third party. In addition to the internal user ID, each Drillster account must have at least one external ID, including email addresses. This means that if a third party ID is used, having an email address linked to the account is no longer a requirement. However, it is still useful to have an email address linked to a Drillster account for communication and password resets.
The third party IDs themselves, i.e. the value after the third party code and the slash, are provided by the customer. They can have any value, as long as they are unique within the third party, and as long as they contain only characters from the following sets:
- Unicode uppercase (
Lu) - Unicode lowercase (
Ll) - Digits (
POSIX digit) - Punctuation (
POSIX punct) except the/character - Space (
U+0020) except at the start or end
The length of a third party ID must be between 1 and 100 characters. Keep in mind that third party IDs are case sensitive!
Examples
Below are some examples of syntactically correct third party IDs for third party EXAMPLE:
EXAMPLE/12345EXAMPLE/ABC123EXAMPLE/6Eb9DmW_VB4fWOT6yGDY0QEXAMPLE/LE BLANCEXAMPLE/204.721.12EXAMPLE/jane@example.com
These examples are not valid third party IDs:
EXAMPLE/12345/ABC– slash in the ID partEXAMPLE/ ONE TWO– spaces at start and end of the ID part