1. Atlas Systems
  2. Aeon
  3. External Systems

Aeon API

Print Friendly and PDF Follow

Avatar
Sara Juel
Updated

The Aeon API allows developers to perform actions in Aeon and build integrations outside of the installed Aeon components. For example, the API allows the developers to connect to the database and change a transaction status.

Installation 

Using the Aeon API requires Aeon version 4+. The Aeon API requires the .NET Core components at version 2.1 or higher. This installer is provided by Microsoft and must be run separately.

Note: As of v5.1, the Aeon API is installed by default during the server installation/update process and does not need to be installed separately. However, the .NET Core components are not part of the default Aeon install and will still need to be installed separately. 


For older versions of Aeon, the latest installer for the Aeon Web API is available on the Aeon Downloads page.

Please contact Atlas Systems at 1-800-567-7401 x1 or support@atlas-sys.com for the credentials to download the installer.

Service hours are Monday through Friday 8am-5pm eastern time, excluding Federal holidays.

Aeon API URL

For standard Aeon installations, the default URL for the Aeon API is https://servername/aeon/api/. However, your path to the API may differ if using a non-standard installation path for the Aeon API on your Aeon server.

If you are unsure which path to use for your API URL, please contact Atlas Support at support@atlas-sys.com if Atlas-hosted or your local Aeon server administrator if self-hosted.

Swagger Documentation

The Aeon API has developer-oriented documentation built-in. You can get to the API Swagger documentation at https://servername/aeon/api/swagger/.

*Replace 'servername' with the IP address or DNS. 

Available Endpoints

Custom Fields | Queues | Reading Rooms | Requests | System Information | Token | Users

To use the reshelved endpoint, you must first update your Aeon server and the client to version 4.1, then update your Aeon API to version 1.2.0 with the installer linked above. All other endpoints are available on the previous version of the Aeon API, version 1.2.0. 

Custom Fields

 
Get /api/customFieldDefinitions/{contextType}                                                                                   

Returns a list of custom fields defined for the specified context type.

Parameters:

  • contextType: The context type for which to return the list of custom fields.
Click for properties of the information returned
Property Name Description
id Numeric ID of the field definition.
contextType Activity, Transaction, or User
shortName The short name of the field that can be used to add the field to a request via POST message.
dataType The data type of the field.
label The display label used for the field in the Aeon Client.
 

Custom Fields Support in Other Endpoints

To include custom fields when creating a request via the POST Request endpoint, the Request JSON object must have a property named "CustomFieldsValues" containing all custom field values that will be supplied in the "ShortName:value" format.

Response objects returned by the GET Request and POST Request endpoints and user objects returned by the GET User endpoint will contain a CustomFields property listing all defined fields for the given request, in the same "ShortName:value" format. Null values will be included.

Queues

 
Get /api/Queues                                                                                                             
Returns queues configured in Aeon.
Get /api/Queues/{id}                                                                                                     
Returns a Queue identified by ID.
Get

/api/Queues/{id}/requests                                                                                        
Returns requests associated with the queue identified by ID.

Reading Rooms

 
Get /api/ReadingRooms                                                                                                   

Returns a list of reading rooms configured for appointment scheduling in Aeon.

Parameters:

  • siteCode (optional): If supplied, only the reading rooms for that site will be returned; if not supplied, all reading rooms will be returned.
Click for properties of the information returned
Property Name Data Type
id int
name string
availableSeats int
timeZoneID string
minLeadDays int
maxLeadDays int
minAppointmentLength int
maxAppointmentLength int
appointmentPadding int
appointmentIncrement int
lastModifiedTime datetime
sites array of strings
openHours

array of OpenHours objects containing the following properties:

  • dayOfWeek (int, 0-7)
  • dayName (string)
  • openTime (string, in HH:mm:ss format)
  • closeTime (string, in HH:mm:ss format)
Get /api/ReadingRooms/{id}                                                                                            

Returns information on a specified reading room identified by ID. 

Parameters:

  • id (int): The ID of the reading room for which to return information.
Click for properties of the information returned
Property Name Data Type
id int
name string
availableSeats int
timeZoneID string
minLeadDays int
maxLeadDays int
minAppointmentLength int
maxAppointmentLength int
appointmentPadding int
appointmentIncrement int
lastModifiedTime datetime
sites array of strings
openHours

array of OpenHours objects containing the following properties:

  • dayOfWeek (int, 0-7)
  • dayName (string)
  • openTime (string, in HH:mm:ss format)
  • closeTime (string, in HH:mm:ss format)
Get

/api/ReadingRooms/{id}/Closures                                                                              

Returns a list of full closures for the specified reading room, limited to those occurring in the future. This endpoint reports both full closures (i.e. "Closed" exception types) and "partial" closures (i.e. "Reduced Availability" exception types) that reserve a number of seats greater than or equal to the reading room's total available seats.

Parameters:

  • startDate (datetime): Specifies a start time in the reading room's timezone.
  • endDate (datetime): Specifies an end time in the reading room's timezone.
  • note (string): Specifies the public note associated with the closure.
Get

/api/ReadingRooms/{id}/AvailableAppointments/{date}                                              

Returns a list of available appointment times for the specified reading room on the specified date.

Parameters:

  • id (int): The ID of the reading room for which to return information.
  • date (string): The date for which availability should be returned.
Click for properties of the information returned
Property Name Description
startTime Available start time in the reading room's timezone.
utcStartTime Available start time in the UTC timezone.
seatsAvailable The number of seats available at the listed time.
maximumAppointmentLengthMinutes The maximum possible length of an appointment beginning at the listed start time.

Requests

 
Get /api/Requests/{id}                                                                                                       
Returns a request identified by transaction number.
Get /api/Requests/{id}/nextsteps                                                                                        
Returns next step process names for the transaction identified by ID.
Post /api/Requests/create/

Creates Aeon requests for a specified user.

API Call:

At a minimum the username (user must be a valid user in the database) must be supplied; however, additional user information may be provided if supplied by the appropriate corresponding database column names.

  • Request process:

    • The request will be created and the initial routing will be performed of the transaction and will return a JSON object with creation details including the transaction, including TN, and any default field values.

Additional Notes

  • If two fields with the same name are supplied to the endpoint (e.g., two "username" fields), only the second value will be used
  • If a field that does not exist is supplied to the endpoint, that value will be ignored
Post

/api/Requests/{id}/route
Routes a transaction to the given transaction or photoduplication status. Routing rules will be applied.
Get /api/Requests/{id}/routes                                                                                             
Returns a list of the valid transactions and photoduplication queues a request may be routed to.
Post  /api/Requests/Batch/?{parameters}

Returns a list of requests for the given barcode. Unlike the RequestBarcodes/Reshelved endpoints, the endpoint allows for nonstandard characters.

API Call:

  • The request will check to see if the provided transaction number has a TransactionStatus of Awaiting Item Reshelving. If so, the API will route the request to the Item Reshelved status, and then to Request Finished status.
  • The custom queue Item Reshelved will act as a transitory status that will trigger requests to automatically route to the Request Finished status.  
  • If activeOnly is set to true, only active requests will be returned. 
Post /api/Requests/Batch/Reshelved

Reshelves request based on the given barcode. Unlike the RequestBarcodes/Reshelved endpoints, the endpoint allows for nonstandard characters.

API Call:

  • Request process:
    1. The request will search for the transaction record whose ItemNumber field matches the barcode provided in the API request. The ItemNumber field should be the only location used for the barcode number since Aeon assumes this field is the barcode and will not check any other fields for the barcode number. 
    2. The request will then check to see if the provided transaction number has a TransactionStatus of Awaiting Item Reshelving. If so, the API will route the request to the Item Reshelved status, and then to Request Finished status.
  • The custom queue Item Reshelved will act as a transitory status that will trigger requests to automatically route to the Request Finished status. 
Post /api/RequestBarcodes/{barcode}/reshelved                                                                    
The RequestBarcode endpoints have been replaced by the Requests/Batch endpoints and are now considered deprecated.

Reshelves request based on the given barcode.

API Call:

  • Request process:
    1. The request will search for the transaction record whose ItemNumber field matches the barcode provided in the API request. The ItemNumber field should be the only location used for the barcode number since Aeon assumes this field is the barcode and will not check any other fields for the barcode number. 
    2. The request will then check to see if the provided transaction number has a TransactionStatus of Awaiting Item Reshelving. If so, the API will route the request to the Item Reshelved status, and then to Request Finished status.
  • The custom queue Item Reshelved will act as a transitory status that will trigger requests to automatically route to the Request Finished status. 

Post

 /api/RequestBarcodes/{id}/reshelved                                                                            
The RequestBarcode endpoints have been replaced by the Requests/Batch endpoints and are now considered deprecated.

Reshelves request based on a given transaction number.

API Call:

  • The request will check to see if the provided transaction number has a TransactionStatus of Awaiting Item Reshelving. If so, the API will route the request to the Item Reshelved status, and then to Request Finished status.
  • The custom queue Item Reshelved will act as a transitory status that will trigger requests to automatically route to the Request Finished status.  

System Information

 
Get /api/SystemInformation/Version                                                                                   
Returns the version of the Web API.

Token

 
Post /api/Token                                                                                                               
Retrieves an authentication token for the provided staff credentials. 

Users

 
Get /api/Users/{username}                                                                                   
Returns a user identified by username.
Get
/api/Users/{username}/requests
Retrieves a list of all requests (or active requests only if the ActiveOnly parameter is used) for a specific user.
Get
/api/Users/{username}/appointments

Returns a JSON object containing the list of appointments for a given user. The appointment object also contains the associated reading room object.

Parameters:

  • Username: The username for which to retrieve appointments.
  • Context: Can be "Self," "Researcher," or "Both" to filter the list of appointments for just the user, just the user's researchers, or to include both. If no context is specified, "Self" will be the default value.
  • PendingOnly: Filters out past appointments by StartTime.

Authentication

Most of the actions will require authentication. There are 2 ways to authenticate in the Aeon API: Aeon API Key or staff tokens.

API Key

You can create an API key in the Aeon Customization Manager. More information on API keys is available at Configuring the Aeon Web Platform.

The Base Webservice URL isn't relevant for the API so you can just enter the API URL: https://yourservername.aeon.atlas-sys.com/aeon/api/.

Staff Token

The staff tokens will use the POST Token operation where you'll post an Aeon staff username and password. It will return a token which should be used as a BEARER authentication header.

Testing the Authentication

To test in the swagger interface, you can click on Authorize in the top right corner of the swagger interface. A pop-up like an image shown below will appear.

  • The first option (Name: X-AEON-API-KEY) is for the API Key; Just paste the API key directly into the value and click authorize and you should be good.
  • For the staff token authentication, note that it currently has a 5-minute timeout. You would need to POST to the Token operation to get a JWTvalue. In the swagger interface, you would enter BEARER <JWT value from Token response>
As of Aeon 4.1, the token controller used to obtain a JWT token for authentication has been upgraded to use the new staff password changes implemented in the 4.1 security release. The Web API does not support changing staff passwords at this time; therefore, if the staff account that is being used to obtain a token is locked or has an expired password, the API will not generate a token. Please change your staff password in the Staff Manager prior to generating JWT credentials after upgrading to v4.1 (this includes new installs of v4.1).

Additional Information

If there is specific functionality that you are looking to use to integrate with your services, we encourage you to submit enhancements & ideas to Uservoice at https://uservoice.atlas-sys.com/. Thanks!

 

Questions?

If this article didn’t resolve your issue, please contact Atlas Support for assistance:

Contact Support

Articles in this section