Tip: All users will be able to see the Online Invoice link by default. Make sure you set the relevant form permissions after you enable this feature if access needs to be restricted.

The Online Invoice custom field supports read requests using the OpenAir XML API, SOAP API and User Scripting.

Note: The invoice URL is the short URL included in the body of the invoice email when you navigate to the Send tab for a given invoice record in OpenAir.

To enable this feature, contact OpenAir Support.

Save Payment Terms Internal ID on Invoice Records

Add support for saving the internal ID of the payment terms as well as the payment terms on the invoice record.

Depending on your account configuration, you can select the payment terms on the invoice entity property form using a dropdown list. By default, the payment terms name is stored on the invoice record but not the payment terms ID. This release adds a hidden payment terms ID field for the invoice entity.

An optional feature sets the internal ID of the payment terms selected for the invoice automatically when you create a new invoice or update an existing record. If your account is configured to show internal IDs on list views or on reports and if you are an account administrator or have the relevant role permissions, you can add the Internal id - payment_terms_id column on list views or the Internal id - payment_terms_id attribute to Invoice detail reports. With this feature enabled, the payment_termsid value can be retrieved and modified using OpenAir XML or SOAP API — see Platform.

Note: To enable this feature, contact OpenAir Support.

If the payment terms field currently shows as a text field on the invoice property form, it will show as a dropdown list after you enable this feature. The payment terms internal ID will not be populated for existing invoice records when you enable this feature. To set the payment terms internal ID for existing records, you can either save existing invoices manually or use the XML or SOAP API.

up

Reports

Timesheet Status Filter on Time Entries Reports

Filter time entries by timesheet status on time entries tabular (detail) reports.

The new filter lets you include or exclude time entries from timesheets with specific statuses. For example, you can set a status to exclude time entries from archived timesheets.

Maximum Number of Daily Time Periods Allowed in Reports

The maximum number of daily time periods in crosstabbed (summary) reports can be changed to fit a whole month, 2–month period or quarter.

Note: The maximum number of daily time periods in reports depends on the configuration for your OpenAir account and is limited for performance reason. The current limit for your account will be changed automatically to include the additional days to cover a whole month, 2–month period (62 days instead of 60) or quarter (92 days instead of 90). To change the limit for your account, contact OpenAir Support.

Support for Current Approvers Internal IDs in Reports

Add the Internal IDs of all time entry current approvers to your reports.

You can now add the attribute Time entry — Internal Id(s) — Current Approver(s) to show the internal IDs of all time entry current approvers.

• In tabular (detail) reports:

  • Tabular > Timesheets > Time entries

  • Tabular > Timesheets > TimeBills

• In crosstabbed (summary) reports:

  • Charge attribute

Note: Your account must be configured to show all internal IDs on detail reports and you must be an account administrator or have the View all pending time entries approvers role permission to add or view the attribute Time entry — Internal Id(s) — Current Approver(s) in reports.

up

Platform

OAuth 2.0 Support for Identity Provider Initiated Single Sign-on

The OAuth 2.0 feature now supports Identity Provider initiated Single Sign-on for users authorizing an API integration application to access OpenAir on their behalf.

Users must log in using their Identity Provider Single Sign-on form before the application attempts to access OpenAir on their behalf. When the application attempts to access OpenAir, the authorization screen appears automatically. Users do not need to enter their login details again as long as the Single Sign-on session has not expired.

OAuth 2.0 Support for Multiple Scope Values

Request authorization for accessing OpenAir data using one or more OpenAir APIs.

The OAuth 2.0 feature now support multiple scope values. Client applications can request authorization to use multiple OpenAir APIs to access OpenAir data. You can use the access token within the scope it was issued for or refresh the access token and request a scope within the scope the original access token was issued for. For example, if the scope of the original token includes both xml and rest, the scope of the access token requested can be rest only.

OAuth 2.0 API Integration Applications Administration Enhancements

Configure the access and refresh token lifetime, and enable, disable or remove multiple applications at the same time in the API integration applications administration screen.

The API integration applications administration screen (Administration > Global settings > Account > API integration applications) was introduced in the April 2020 OpenAir release to register and manage the integration applications using the OAuth 2.0 authorization code flow to access your OpenAir data. This release adds the following functionality and usability enhancements to the API integration applications administration screen:

• Configurable access and refresh token lifetime — You can select the expiration time of access tokens (in 5–minute increments up to 60 minutes) and refresh tokens (in one-hour increments up to 24 hours) for each client application when you register a new application or when you edit an application configuration. The default lifetimes are 15 minutes for access tokens and 24 hours for refresh tokens.

  

  

• Remove action — Click the delete icon or check the box next to the application and click Remove to remove an application from your list of registered applications. An application must be disabled before it can be removed.

  

  

• Bulk actions — Check the box next to each application you want to select and click Enable, Disable, or Remove to enable, disable, or remove several applications at the same time. You can only select multiple applications if they are either all enabled, or all disabled. After you select the first application, the application that are not available for selection and the actions that not permitted appear in light gray.

  

  

• Usability enhancements — You can use the Create button to add new applications from any screen in OpenAir. Applications are sorted by name, and names support diacritics and non-latin characters. The application configuration supports tab navigation.

  

  

Note: OpenAir API access must be enabled for your account to connect tools and services to OpenAir using OpenAir APIs. The API Integration Application screen is not available if OpenAir API access is not enabled. To enable OpenAir API access for your account, contact OpenAir Support or your OpenAir Sales Representative.

Initial Version of OpenAir REST API for Expenses

Use the new OpenAir REST API to exchange Expenses information with OpenAir in your integration applications. These release notes summarize the main functionality of OpenAir REST API. For a more detailed description, see OpenAir REST API Reference Guide.

Overview

The OpenAir REST API provides an interface for integration applications to exchange information with OpenAir.

OpenAir REST API:

• Is organized around REST.

• Uses predictable resource-oriented URLs.

• Accepts JSON-encoded request bodies.

• Returns JSON-encoded responses.

• Uses standard HTTP response codes, authentication and verbs.

OpenAir REST API lets you:

• Use CRUD (create, read, update, delete) operations on OpenAir records.

• Retrieve a list of records from a collections and use pagination.

• Filter OpenAir record collections.

OpenAir REST API is a service layer that is built on top of the business layer in OpenAir. This ensures that business rules configured for your OpenAir account are applied when an integration application interacts with your OpenAir data through OpenAir REST API. Business rules include OpenAir account configuration settings and access control mechanisms, as well as any user scripts deployed on your OpenAir account.

OpenAir REST API supports OAuth 2.0 exclusively for authentication and authorization, which is a more robust and reliable way to access data.

Note: To enable OpenAir REST API, contact OpenAir Support.

OpenAir API access must be enabled for your account before you can enable OpenAir REST API. To obtain access to OpenAir API, contact your OpenAir Sales representative.

Important: OpenAir REST API was introduced in the October 10, 2020 OpenAir release. It is an initial version with limited functionality.

Some optional features and application settings are not fully supported.

As with any other OpenAir APIs or platform features, it is crucial that you test integration applications leveraging OpenAir REST API extensively on a sandbox account. Make sure your integration applications run smoothly without error on a non-production account before you implement it on your production account.

Supported resources, methods and features

The current scope of OpenAir REST API is limited to the Expenses module. The following table summarizes the methods and features available for supported resources.

Resources	Create (POST)	Read ( GET)	Update ( PUT)	Delete ( DELETE)	Filtering	Pagination
Contacts
Expense reports
Job codes
Receipts
Receipt attachments		(single object only)

Authentication

OpenAir REST API supports authentication by OAuth 2.0 access token exclusively. You must send the OAuth 2.0 access token as a bearer token in the Authorization header for each request.

Integration applications must be registered in OpenAir to use OpenAir REST API with OAuth 2.0, and users must give the application explicit permission to access OpenAir on their behalf.

Request format

You can access OpenAir resources through the REST API by using URLs specific to each resource, and pass parameters in the query string to specify the information you need in the response.

The request URL includes:

1. Base URL — The base URL includes your account-specific domain, with a unique account identifier usually based on your Company ID, and the REST API service path.

   Environment	Base URL
   Production	https://<company-id>.app.openair.com/webapi/v2
   Sandbox	https://<company-id>.sandbox.app.openair.com/webapi/v2
   Demo	https://<company-id>.demo.app.openair.com/webapi/v2

   Note: The base URL is typically sent in the Host header.

   The examples in this document include the base URL for a production account in the Host header, and use company-id as the unique account identifier. Substitute company-id with your account identifier, which is typically based on your company ID.

2. Resource endpoint path

   • There is a predictable resource endpoint path for each entity supported.

     Entity	Path
     Receipts	/receipts/
     Expense reports	/expense-reports/
     Receipt attachments	/attachments/
     Job codes	/job-codes/
     Contacts	/contacts/

   • The path may also include URL parameters. For example:

     • {id} — The internal ID of the specific record you want to retrieve, update or delete.

3. Query string — A query string may be used to specify what information you need in the response, to use pagination or to filter the resource collection.

The request headers include:

• Authorization — OAuth 2.0 bearer token.

• Content-Type — The POST and PUT methods include the application/json content-type header.

POST and PUT requests must include a JSON-encoded request body with the object to be created, or the key-value pairs for the fields to be updated.

Filtering the resource collection (GET)

You can filter the collection of resources by using the q query parameter to specify filter conditions when retrieving the list of resources. Each condition consists of a field name, an operator, and a value. You can join several conditions using the AND and OR logical operators, and you can use parenthesis () to mark precedence.

The following table lists the comparison operators available depending on the field data type and format.

Data Type and Formats	Query Operators
[All field types and formats	EMPTY, EMPTY_NOT
boolean	IS, IS_NOT
integer($int64) number($double) number($float)	ANY_OF, ANY_OF_NOT, BETWEEN, BETWEEN_NOT, EQUAL, EQUAL_NOT, GREATER, GREATER_NOT, GREATER_OR_EQUAL, GREATER_OR_EQUAL_NOT, LESS, LESS_NOT, LESS_OR_EQUAL, LESS_OR_EQUAL_NOT, WITHIN, WITHIN_NOT
string	CONTAIN, CONTAIN_NOT, IS, IS_NOT, START_WITH, START_WITH_NOT, END_WITH, END_WITH_NOT
string($date)	AFTER, AFTER_NOT, BEFORE, BEFORE_NOT, BETWEEN, BETWEEN_NOT, ON, ON_NOT, ON_OR_AFTER, ON_OR_AFTER_NOT, ON_OR_BEFORE, ON_OR_BEFORE_NOT

Pagination (GET)

The list of resources can be returned in one or more pages when you send a GET request.

• You can specify the length of the page (the maximum number of results per page) by using the limit query parameter. If a limit is not specified, the default page length is 100. The maximum length allowed is 1000.

• You can specify the specific page to return by using the offset query parameter. The offset must be a positive number divisible by the page limit.

Other query parameters

Some methods accept the following query parameters.

• You can use the fields query parameter to return exactly the fields you need in the response (POST, GET, PUT).

• You can use return_object query parameter to return the object created or updated instead of returning the internal ID of the object created or updated only.

Note: The GET /contacts/ and GET /job-codes/ methods to retrieve a list of contacts and job codes, respectively, do not currently support the fields parameter.

Examples

The following examples demonstrate the request format.

GET request example

The following request retrieves a filtered and paginated list of expense reports.

                  GET /expense-reports?limit=10&offset=10&q=created BETWEEN ['2020-01-01', '2020-06-30'] AND currency IS 'EUR' HTTP/1.1
Host: https://company-id.app.openair.com/webapi/v2
Authorization: Bearer yAc0fCiQBZcWEoHBipZ3ScZa3TJNajGm4dGV79C1cO0CFMU2B1kKDbtk4YYkmt3a1y2Uut6eGJXFGobCyLwdcgxm 

                

PUT request example

The following request updates the receipt with the internal ID 3825, and specifies to include the object in the response, and the fields to be returned.

                  PUT /receipts/3825?fields=id,attachments&return_object=1 HTTP/1.1
Host: https://company-id.app.openair.com/webapi/v2
Content-Type: application/json
Authorization: Bearer yAc0fCiQBZcWEoHBipZ3ScZa3TJNajGm4dGV79C1cO0CFMU2B1kKDbtk4YYkmt3a1y2Uut6eGJXFGobCyLwdcgxm

{
  "cfCheckboxReceipts": true,
  "date": "2020-06-30",
  "currency": "USD",
  "isTaxIncludedInCost": false,
  "notes": "Receipt updated using OpenAir REST API"
} 

                

Documentation

The following documentation is available: OpenAir REST API Reference Guide and the system-generated REST API reference documentation in OpenAPI 3.0 JSON format.

Account administrators and employees with the Export data role permission can access the generated API reference documentation JSON if OpenAir REST API is enabled for your account. The generated documentation provides a reference for OpenAir REST API including resource descriptions, endpoints and methods, parameters, request body and response examples and schema. It includes custom fields specific to your OpenAir account that are associated with supported resources.