The ORCID Sandbox
What is the ORCID Sandbox?
The ORCID Sandbox is a service provided by ORCID for testing purposes; the site mimics the Production ORCID Registry in function, providing both a public and member API to the Sandbox registry, and a user interface to manage Sandbox records. The Sandbox Member API allows organizations to test Member API functions without affecting production records. Anyone is free to test the ORCID API on the sandbox testing server.
Understanding the Sandbox registry
This blog post brings together in one convenient place the information about the ORCID Sandbox based on various sections of ORCID documentation (which are listed at the end of this blog). Although the Sandbox behaves very similarly to the Production registry, there are some differences which you should be aware of, outlined later in this post. ORCID membership isn’t required in order to access the Sandbox. Registration for the development sandbox service is open to anyone. The remainder of this blog post will help you understand the Sandbox and how to register to use it.
The Sandbox registry compared to the Production registry
The ORCID development Sandbox is designed to resemble the production Registry as closely as possible. Note that the Sandbox is not connected to the production ORCID registry and no information is shared between the two systems. However, the Sandbox has identical functionality, with some differences (e.g. the content is test data, the behaviour of emails and connections to outside systems are different). The ORCID sandbox lets you create test user accounts and develop your integration without having to worry about affecting data on the live (production) ORCID Registry.
The content of the Sandbox (the user information held in the ORCID records) is NOT a copy of the Production registry, it is just ‘test data’. The records contained in the registry consist of test records added by other users during their testing process. The ORCID record data in the sandbox will be data that various users have created for testing purposes. Many of the records contain test values, i.e the user information is all made up or contains values like ‘test publication’ ‘fictional funding source’ etc Some records that have been added may be copies of real records or resemble them very closely. Those user profiles could be closely similar to a real user ORCID profile – so the testing can be close to real, and sometimes it is easier to copy real information rather than make up test data.
Other differences between ORCID Production Registry and Sandbox
| Registry | Sandbox | Production |
|---|---|---|
| Links and Navigation | The links and tabs on the user interface e.g. Help, About do not work. | Links and navigation work as expected |
| Import tools | Import tools do not work. Search & Link wizards in the funding and works section generally do not function. | Import tools are available see Search and Link |
| Message sending | Only sends email messages to @mailinator.com email addresses (see section on mailinator) | Messages are sent to the registered user’s email address and inbox |
| Search Engines | Not indexed by search engines | |
| Level of service | No Service-Level Agreement No guarantees about uptime/availability, processing speed, or data availability Data is not backed up ORCID state: we reserve the right to remove data at any time — though we will make a best effort to notify users via the API Users Group if we have plans to do so |
Occasionally, the Sandbox will be one version ahead of the Production Registry to allow for API developer testing. When this happens ORCID will notify the API Users Group.
Getting down to work – creating records
One easy way to make sure that you understand the content that is being added and retrieved from the Sandbox during testing is to create a record yourself that you can control. When you create your own user entry in the sandbox it means there will be a profile that you know exists and that you can check the content of. Otherwise the entries can be a bit random, mostly empty or just containing test data and this could be confusing when trying to understand the results you are getting from the Sandbox API. In order to test the ORCD API and API calls, such as a reading and adding information to an ORCID record, you will also need to create a test ORCID record in the sandbox. This can be done through the user interface, much like on the production ORCID Registry. Once you have one or more records in the Sandbox that you control you can play around with changing permissions on the record data – granting and removing permissions to the different fields and giving permissions to the application that you are testing.
Go to https://sandbox.orcid.org/register and register for an account, using a mailinator address (see the section later in this post on mailinator) or sign in to sandbox record
Obtaining credentials to access the Sandbox
Both member and sandbox API are accessed using credentials (a client ID and secret). Different credentials are issued for the production member API and the sandbox API. Production member API credentials won’t work against the sandbox (and vice versa). In the production registry, the API features that integrators have access to are determined by their membership level. Sandbox credentials can be set to reflect the API features available at different membership levels. Credentials at member level allow you to make calls to the sandbox member API to read, write to, and update ORCID records. Access to the sandbox testing environment that mirrors the member level is freely available to anyone, even if you’re not an ORCID member organization.
Method 1 Obtaining credentials using developer tools
- Log into the Sandbox as an ORCID user (assuming you have created an ORCID record for yourself already)
- Click Developer Tools at the top of your record.
- Click the “Register for the free ORCID public API” button
- Register a sandbox application
Instructions from ORCID with further details are available. (see Enable developer tools section). This method will only give you access at public API level and the credentials are tied to an individual.
Method 2 Obtaining credentials using the client application form
To complete the form you need to enter some information on your client and your organization. The process is not completely automated and there may be a short delay (1-2 days) before your credentials are issued. The credentials can be used and updated by an organisation and are not tied to an individual.
Application form to complete for client credentials for the ORCID sandbox registry.
TIPS
- You can have a look at our post on using vendor systems for some more explanation about credentials.
- Further help with filling in the form is also available from ORCID in the ‘register a client application’ Knowledgbase article and information on redirect uris
About Mailinator
To prevent accidental notifications from being sent from the test environment, emails generally are not sent to addresses stored in the Sandbox. However to allow for testing, ORCID have enabled emails addressed to the domain mailinator.com.
This prevents the Sandbox from sending out lots of test emails to users’ real email addresses. Mailinator provides a convenience email address – it provides a way to receive email from the ORCID sandbox that can be checked (through mailinator).
If you do need to receive emails from the Sandbox, such as the email allowing you to verify your email address before registering an application to use the Public API, use a mailinator.com email address when creating the record, or if you already registered with a different address, add a mailinator.com address to the account as the primary address (you can add multiple email addresses by editing your record).
Mailinator is a free service that is not managed or maintained by ORCID. It is recommended that you review how this service works and its limitations before using mailinator addresses.
To use mailinator, you can go to https://www.mailinator.com/ make up an email address, make a note of that address, then use it when registering on the ORCID Sandbox. Your address will now be NameYouMadeUp@mailinator.com Mailinator is quite clever, if you simply make up an address which ends in @mailinator.com when entering details in the ORCID sandbox, without going to the mailinator site, mailinator will create an inbox for that address once emails are received.
The sandbox server sends notification emails only to @mailinator.com email addresses in order to not spam mail servers unintentionally. You will not receive a verification email or password reset notification unless you use a @mailinator.com address, and verification is required in order to make any manual edits to sandbox records.
To check the messages that the ORCID Sandbox has sent to your @mailinator.com address, you can use the Email tab on the mailinator site mailinator.com. Look at the mailinator inbox for messages received to that mailinator address.
If you are not testing any further sandbox features that involve receiving email notifications, then you may not need that mailinator address although you may wish to make a note of it so you can log in again or find your sandbox entry based on the email address.
In summary:
- You need to receive emails from ORCID to complete some transactions (e.g. verify the email address; edit records manually)
- ORCID sandbox only sends emails to mailinator addresses
- The good news is mailinator addresses are very easy to use; just make up an address ending in @mailinator.com and access and respond to the messages sent by ORCID Sandbox on the mailinator.com site
Moving on to production
If you are using one of the vendor systems that are ORCID enabled, you are not required to show your integration before requesting production credentials. You may still wish to use the above information so you can test against the Sandbox first, making sure you use a test instance of your vendor system.
Building your own integration
ORCID require that you to first build tools that interact with the ORCID sandbox to prevent affecting any data on the production registry during testing—or your own systems. Once your integration is ready and completely tested against the sandbox, you can apply for production credentials and contact ORCID or your consortium lead to arrange the next steps (for example a demo against the sandbox). Make sure to check out the ORCID checklist before applying for production credentials or setting up a demo.
Staying up to date and getting help
The API users group is the mailing list you need to follow to stay up to date with notifications on updates to the Sandbox API versions, and you can also get help by asking questions. Remember if your organisation is a member of the UK ORCID Jisc consortium, you can also request assistance with using the API from the dedicated UK Jisc helpdesk help@jisc.ac.uk
ORCID documentation related to Sandbox
Register a client application (accessed 30th August 2018)
Register a client application: Sandbox Member API (accessed 30th August 2018)
Is the Sandbox different from the Production Registry? ORCID API FAQ Knowledgebase Article (accessed 30th August 2018)
Why am I not receiving messages from the Sandbox ORCID API FAQ Knowledgebase Article (accessed 30th August 2018)
Getting started with your ORCID integration (accessed 30th August 2018)