Hello and welcome to this short tutorial. The tutorial is intended to help ONE Record users get started with their ONE Record servers. The examples are based on a local development environment, e.g. the ONE Record Server is available at http://localhost:8080. However, all steps can be performed on any other ONE Record Server, regardless of the environment, e.g. cloud environment deployments such as Amazon AWS or Microsoft Azure.
This tutorials covers the following topics:
- Setup a local development environment
- Setup a cloud environment with Amazon AWS
- Authentication with Access Tokens
- Connecting to a ONE Record Server
- Requesting Logistics Objects
- Creating Logistics Objects
- Updating Logistics Objects
The tutorial is based on the ONE Record API specification v2.0.0, ONE Record data model v3.0.0, and the NE:ONE Server v1.1.0.
| Name | Description | Example |
|---|---|---|
| ONE Record server URL | Base URL of the ONE Record Server that can be used to get the ServerInformation | |
| LogisticsObjectURI | Globally unique identifier that is created when a new LogisticsObject is created | http://localhost:8080/logistics-objects/eff8ba45-6d2c-4f0b-8a33-9de8f830f38b |
| Data holder URI | Data holder of a ONE Record Server and the LogisticsObject located on it. Technically, this is a data object of type Organization, which is a subclass of LogisticsObject | |
| Access token URL | HTTP endpoint provided by the authentication server that can be queried with client_id and client_secret to get an ID token |
|
| client_id | A public identifier for app/daemon/client used to authenticate to an authentication server. |
|
| client secret | Secret known only to the app/daemon/client and the authentication server. Comparable to a password. |
|
| scope | Limits an application's access. Not necessary for ONE Record authentication, but required by some authentication servers. | https://.onmicrosoft.com//access_as_application |
| access token | An access token / ID token is a JSON Web Token (JWT) that contains authenticated user information, issued by an authorization server as part of the authentication response. This needs to be sent with every ONE Record request to authenticate the client | eyJhbGciOiJSUzI1...zKUHw |
- Docker installed
- Docker Compose installed
- Git installed
- Clone the repository
git clone https://github.com/ddoeppner/one-record-server-first-steps
- Switch to the directory to docker-compose
cd one-record-server-first-steps/docker-compose - Start all services with docker compose
docker compose up -d
- Wait until all containers are up and running:
[+] Running 6/6 ✔ Network docker-compose_default Created 0.0s ✔ Container docker-compose-graph-db-1 Healthy 0.0s ✔ Container docker-compose-keycloak-1 Healthy 0.0s ✔ Container docker-compose-ne-one-server-1 Started 0.0s ✔ Container docker-compose-graph-db-setup-1 Started 0.0s
- Try to access the ONE Record Server by http://localhost:8080 using your favorite browser. You should see a HTTP Error 401, because you did not authenticate yet. But this confirms that the ONE Record Server is up and running.
- Postman desktop app installed or Postman web app. However, When running the ONE Record server locally, you need to use the Postman Desktop Agent. See here for more information on this topic.
- when testing with a local ONE Record Server, the Postman desktop app is recommended.
- Your ONE Record Server URL
- Access Token URL configured in your ONE Record Server
- Credentials that authenticates you as the data owner of a ONE Record Server: client_id, client_secret, and scope (optional)
- On the home screen of Postman, click Create Workspace
- Select a name of the new Workspace, for example, ONE Record Tutorials
- Visibility can be left with Team
- Click Create Workspace
- Click Import
- Drag'n'Drop the Postman collection or select file. (The Postman collection can be found here.)
- Expand the newly imported collection "ONE Record - First Steps" to see all example requests by click on the caret icon
- Select “1) Obtain an access token” request
- Replace <token_endpoint> with your provided token_endpoint
- Select Response Body tab and replace <client_id> with your provided client_id
- Replace <client_id> with your provided client_id
- Replace <client_secret> with your provided client_secret
- Press Send-Button to request access token
- You should see a response with an access_token.
- Select "2) Get ServerInformation" request
- Replace <one_record_server_url> with your ONE Record Server URL
- Select Authorization tab and replace <access_token> with previously copied access_token
- Press Send-Button to request ServerInformation
- You should see a LogisticsObject of Type
Organizationas a response. This is the configured data holder of the ONE Record server.
- Select "3) Get data owner (LogisticsObject)" request
- Replace <data_owner_uri> with your provided Data Owner URI or the copied
@idfrom previous response - Select Authorization tab and replace <access_token> with previous copied access_token
- Press Send-Button to request data owner data
- Select Headers Tab in Response to check the latest-revision number. If the data owner has not been changed yet, this value should be "1".
- Select "4) Create Person (LogisticsObject)" request
- Replace <one_record_server_url> with your provided ONE Record Server URL, the endpoint must contain ´/logistics-objects`
- Select Authorization tab and replace <access_token> with previously copied access_token
- Select Request Body Tab and modify the information about the Person you want to create
- Press Send-Button to create the new Person
- Select Headers Tab in Response to check the location header. This is the LogisticsObjectURI of the newly created Person. Copy it for the next request.
- Select "5) Update DataOwner Organization (add Person and replace name)" request
- Replace <data_owner_uri> with your Data Owner URI or the copied
@idfrom previous response, default: http://localhost:8080/logistics-objects/_data-holder - Select Authorization tab and replace <access_token> with previous copied access_token
- Select Request Body Tab
- Setup the new name of the Data Owner Organization
- Replace <data_owner_uri> with your provided Data Owner URI or the copied
@idfrom previous response (4 times!) - Replace <person_LogisticsObjectURI> with your LogisticsObjectURI of the new created Person from last request
- Make sure that the revision is the same as latest-revision, i.e. 1
- Press Send-Button to update the data owner organization
- Select "Get data owner (LogisticsObject)" request again
- Press Send-Button to request data owner data
- Verify that the data owner object changed and the latest-revision is "2"
