Aeon API

Print Friendly and PDF Follow

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 | Aeon API URL | Swagger Documentation | OData Support | Available Endpoints | Authentication | Additional Information

Installation 

Using the Aeon API requires Aeon version 4+. Certain Microsoft .NET components must also be installed on the Aeon Server. These components are provided by Microsoft and will need to be installed separately as they are not included in the default Aeon installation:

  • Aeon 5.2+: The Aeon API requires the .NET Core components at version 2.2 or higher and the Microsoft ASP.NET Core 2.2 Runtime bundle (download from Microsoft's website). These installers are provided by Microsoft and must be run separately.
  • Aeon 5.1 and earlier: 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. 

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. 

OData Support

OData query options are available to help filter result data for select Aeon API endpoints that return a list of objects. OData is currently only supported for the Get Users endpoint.

Filtering

Custom fields defined in the CustomFieldDefinitions table are not available for OData filtering.

The $filter option allows filtering results by applying a Boolean expression. The filter expressions include logical and arithmetic operators, and string functions.

When using these operators, strings should be single-quoted, while dates and numbers must not be quoted. Multiple conditions can be combined with 'and' or 'or.'

Filter Operators

eq Equal
ne Not equal to
gt Greater than
ge Greater than or equal to
lt Less than
le Less than or equal to
and Logical and
or Logical or
startswith(property, substring) The property starts with the substring value
endswith(property, substring) The property ends with the substring value
substringof(property, substring) The property contains the substring value
Information on additional available comparators and operators can be found in the Microsoft documentation.

Example

Return users with email addresses ending in "gmail.com":

GET /<API URL>/Users?$filter=endswith(eMailAddress, '@gmail.com')

Pagination

OData pagination can be added to the query to limit the number of results returned by the endpoint using the following parameters:

skip Specifies the number of items in the queried collection that are to be skipped and not included in the result
top Specifies the number of items in the queried collection to be included in the result
Additional information on OData pagination can be found in the Microsoft documentation.

Examples

Return a list of the first 100 users:

GET /<API URL>/Users?$top=100 

Return a list of users 101-200 (i.e., skipping the first 100 results):

GET /<API URL>/Users$top=100&skip=100 

Return a list of users 201-300 (i.e., skipping the first 200 results):

GET /<API URL>/Users?$top=100&skip=200 

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

Retrieve custom fields by context type

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

Retrieve queues | Retrieve a specific queue | Retrieve requests within a specific queue

Retrieve queues

Get /api/Queues                                                                                                             
Returns queues configured in Aeon.

Retrieve a specific queue 

Get /api/Queues/{id}                                                                                                     
Returns a Queue identified by ID.

Retrieve requests within a specific queue

Get

/api/Queues/{id}/requests                                                                                        

Returns requests associated with the queue identified by ID.

Reading Rooms

Retrieve reading rooms | Retrieve a specific reading room | Retrieve closures for a specific reading room | Retrieve available appointment times for a specific reading room and date 

Retrieve 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 (Aeon 5.1 only) int
maxLeadDays (Aeon 5.1 only) 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)
policies (Aeon 5.2+)

Array of ReadingRoomPolicies objects containing the following properties:

  • id (int)
  • readingRoomID (int)
  • userStatus (string)
  • appointmentRequired (bool)
  • appointmentMinLeadDays (int)
  • appointment MaxLeadDays (int)
  • requestMinLeadDays (int)
  • requestMaxLeadDays (int)
  • autoConfirmAppointments (bool)
  • appointmentReminderDays (int)
  • notifyAppointmentReceived (bool)

Retrieve a specific reading room

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 (Aeon 5.1 only) int
maxLeadDays (Aeon 5.1 only) 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)
policies (Aeon 5.2+)

Array of ReadingRoomPolicies objects containing the following properties:

  • id (int)
  • readingRoomID (int)
  • userStatus (string)
  • appointmentRequired (bool)
  • appointmentMinLeadDays (int)
  • appointment MaxLeadDays (int)
  • requestMinLeadDays (int)
  • requestMaxLeadDays (int)
  • autoConfirmAppointments (bool)
  • appointmentReminderDays (int)
  • notifyAppointmentReceived (bool)

Retrieve closures for a specific reading room

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.

Retrieve available appointment times for a specific reading room and date

Get

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

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

Note: This endpoint will ignore appointments with a status of Cancelled when determining the appointment availability for the room. 

Parameters:

  • id (int): The ID of the reading room for which to return information.
  • date (string): The date for which availability should be returned.
  • userStatus (string)*: The user status for which availability should be returned, based on the policies defined for that status in the Status-Specific Policies table configured for the reading room in the Aeon Customization Manager.

    If a status is not specified in the userStatus parameter or if the status specified in the parameter does not have an entry in the reading room's Status-Specific Policies table, then the endpoint will return appointment availability based on the default policies defined for the reading room.

*Aeon 5.2 only

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

Retrieve a specific request | Retrieve next steps for a specific request | Create a new request | Route a request to a new status | Retrieve valid routing statuses for a request | Retrieve requests associated with a barcode | Reshelve request by barcode | Add note to a request | Retrieve notes for a specific request | Update request information

Retrieve a specific request 

Get /api/Requests/{id}                                                                                                       
Returns a request identified by transaction number.

Retrieve next steps for a specific request

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

Create a new request

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
  • Validation will apply to ensure that the request can be added to the associated appointment (if present) based on the timeframe configured in the Request Minimum/Maximum Lead Days settings for the associated reading room in the Aeon Customization Manager

Example Call:

{
"requestFor": {
"type": "Activity",
"reference": "string"
},
"username": "string",
"appointmentID": 0,
"bundleID": 0,
"callNumber": "string",
"documentType": "string",
"eadNumber": "string",
"format": "string",
"forPublication": true,
"itemAuthor": "string",
"itemCitation": "string",
"itemDate": "string",
"itemEdition": "string",
"itemInfo1": "string",
"itemInfo2": "string",
"itemInfo3": "string",
"itemInfo4": "string",
"itemInfo5": "string",
"itemIssue": "string",
"itemISxN": "string",
"itemNumber": "string",
"itemPages": "string",
"itemPlace": "string",
"itemPublisher": "string",
"itemSubTitle": "string",
"itemTitle": "string",
"itemVolume": "string",
"location": "string",
"maxCost": "string",
"pageCount": 0,
"referenceNumber": "string",
"scheduledDate": "2022-10-14T15:05:13.137Z",
"serviceLevel": "string",
"shippingOption": "string",
"site": "string",
"specialRequest": "string",
"subLocation": "string",
"systemID": "string",
"webRequestForm": "string",
"customFieldValues": {}
}

Route a request to a new status

Post

/api/Requests/{id}/route

Routes a transaction to the given transaction or photoduplication status. Routing rules will be applied.

Retrieve valid routing statuses for a request

Get /api/Requests/{id}/routes                                                                                             
Returns a list of the valid transactions and photoduplication queues a request may be routed to.

Retrieve requests associated with a barcode

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. 

Reshelve request by barcode

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. 

Add note to a request

Post /api/Requests/{transactionNumber}/notes                                                 

Adds a note to an existing request.

Parameters (required):

  • noteText (string): The text for the note being added
  • username (string): The username adding the note
    • This value does not need to be an Aeon user and can be set to a value such as "Aeon Web API" to indicate that the note was added by the API.
  • noteType (string): The type of the note being added
    • Valid values for noteType are System, Staff, User, or ItemDetail
    • If noteType is not specified, the value will default to System

API Call:

  • The endpoint requires a JSON body containing information in the following format:

Example Call:

{
"noteText": "PostNote test note",
"username": "Aeon Web API",
"noteType": "System"
}

Example Response:

{
"id": 662,
"transactionNumber": 15,
"noteDate": "2022-09-08T18:57:12.8656546",
"noteText": "PostNote test note",
"username": "Aeon Web API",
"noteType": "System"
}

Retrieve notes for a specific request

Get /api/Requests/{transactionNumber}/notes                                                 

Returns a list of notes associated with a specified request.

Parameters (required):

  • TransactionNumber: The transaction number for the request

Example Response:

[
{
"id": 1,
"transactionNumber": 1,
"noteDate": "2022-09-12T13:48:50.855Z",
"noteText": "Note Text",
"username": "username",
"noteType": "System"
},
{
"id": 2,
"transactionNumber": 1,
"noteDate": "2022-09-12T13:48:50.855Z",
"noteText": "Note Text 2",
"username": "username",
"noteType": "System"
}
]

Update request information

Patch /api/Requests/{id}                                                            

Used to update information for a specific request.

API Call:

  • In addition to the ID for the request specified in the API call, requests to this endpoint must contain a body in the JSON Patch format using the "replace" action to specify which Aeon fields on the course record to overwrite with new values:
    [
      { "op": "replace", "path": "/<aeonField1>", 
    "value": "<NewValue>" },
    { "op": "replace", "path": "/<aeonField2>",
    "value": "<NewValue>" }
    ]
    Note: The path property must specify an Aeon request field name using camelcase, e.g. 'fieldName'
  • Custom fields defined in the CustomFieldDefinitions table will need to be updated using the following format, where <ShortName> is replaced by the short name defined for the field in the Customization Manager:
    [
      {"op": "replace", "path": "/customFieldValues", 
    "value": {"<ShortName>": "<NewValue>"}}
    ]

 

Example Call:

The following example will set the ItemAuthor field to Doe, John, the ItemVolume field to 456, the ItemTitle field to null, the ItemInfo5 field to ItemInfo, and a Transaction type custom field defined in the CustomFieldDefinitions table with the short name Container3 to Custom:

[
{"op": "replace", "path": "/itemAuthor", "value": "Doe, John"},
{"op": "replace", "path": "/itemVolume", "value": "456"},
{"op": "replace", "path": "/itemTitle", "value": null},
{"op": "replace", "path": "/itemInfo5", "value": "ItemInfo"},
{"op": "replace", "path": "/customFieldValues",
"value": {"Container3": "Custom"}}
]

Additional Notes:

  • To remove a value from a field, use the replace action to set the new value for the field to null, for example:

    {"op": "replace", "path": "/itemTitle", "value": null}
  • Any Aeon request field available in the create request endpoint is available for use with this endpoint

Response:

The endpoint can return the following responses:
    • 200 Success: The operation was completed successfully and a JSON model of the updated request is returned
    • 400 Bad Request: The request information was invalid 
    • 401 Unauthorized: The API request was not properly authorized
    • 404 Not Found: The specified request was not found

 

RequestBarcodes endpoints (deprecated)

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

Retrieve Web API version

Retrieve Web API version

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

Token

Retrieve authentication token

Retrieve authentication token

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

Users

Retrieve a list of users | Retrieve a specific user | Retrieve requests for a specific user | Retrieve appointments for a specific user

Retrieve a list of users

Get /api/Users                                                                                   
This endpoint supports OData filtering.

Retrieves a list of all users up to a maximum of 2000 results.

The maximum number of users that can be retrieved by this endpoint is 2000. OData filtering and pagination can be used to limit the number and specify the type of user results returned by the endpoint. Note that custom fields defined in the CustomFieldDefinitions table are not supported for use with OData filters, but will be returned by the endpoint in the results.

Retrieve a specific user

Get /api/Users/{username}                                                                                   
Returns a user identified by username.

Retrieve requests for a specific user

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.

Retrieve appointments 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